MoodleDocs - User contributions [en]

Verify Database Schema

2013-05-23T13:13:37Z

Libertymoodle: /* Typo */

{{Installing Moodle}}
If you have been upgrading your Moodle site over several versions, it is possible (likely even) that some differences may have crept in between the database table definitions (the "schema") in your database and the version you would get creating a new empty site. This happens because of small errors or oversights in the upgrade scripts. Most of these differences are not harmful, but some may cause strange or unexpected errors. For example, if a default value has been added to a field and this was not reflected in an upgrade script code that assumes the presence of the default may fail to work as expected.

The solution is after doing an upgrade (or, if your problem is that the upgrade fails, before) to compare the database schema of the "production" site to that of a newly created site (where no upgrades have been performed) using '''exactly''' the same code base. There are a number of ways of doing this, but this article outlines a simple way using the Unix command line.

* Complete the upgrade
* Generate the database schema from your recently upgraded site using the following command:
mysqldump -d -u root -p ''myproductiondb'' >production.schema
* Copy the code of your production database to a new (web accessible) location (this is important, it *must* be the same version)
* Create a new, empty database and moodledata area for the new site as per the [[Installation]] instructions
* Edit the config.php file to point at the new database and locations, or delete it and use the install script
* Run the install script to generate the (if applicable) config.php file and the database (admin and site values are not important)
* Generate the database schema from your new site using the following command:
mysqldump -d -u root -p ''mycleandb'' >clean.schema
* Run the following command to detect the differences
diff -u production.schema clean.schema >db.diff

You can now look at ''db.diff'' with your favorite editor to see the differences.

'''NOTE:''' The above obviously applies to MySQL databases. Other databases are likely to have a similar function to dump only the schema. For example PostgreSQL has the '''pg_dump''' command. The remainder of the discussion still applies.

==Interpreting the diff file==

Firstly here's a (real) example:

--
-- Table structure for table `mdl_backup_config`
@@ -129,11 +93,11 @@
DROP TABLE IF EXISTS `mdl_backup_config`;
CREATE TABLE `mdl_backup_config` (
- `id` int(10) unsigned NOT NULL auto_increment,
+ `id` bigint(10) unsigned NOT NULL auto_increment,
`name` varchar(255) NOT NULL default '',
`value` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`),
- UNIQUE KEY `name` (`name`)
+ UNIQUE KEY `mdl_backconf_nam_uix` (`name`)
) ENGINE=MyISAM AUTO_INCREMENT=15 DEFAULT CHARSET=utf8 COMMENT='To store backup configuration variables';

The file may have lots of blocks of changes. The - lines show lines to be taken out and the + lines the ones to replace them (from the production to the clean). So here, the int has been replaced with a bigint and the key name changed. Both of these, technically, should have been changed at some point by upgrade scripts but have been missed. In this case they are unlikely to affect the operation of Moodle.

===Too many changes to track manually?===

You can also use database management programs to synchronize old and new Moodle databases.

For example [http://wb.mysql.com/ MySQL Workbench] for MySQL databases.

This is very useful, if you have a lot of changes.

If you can work a Unix/Linux command line the Python script [http://schemasync.org/ Schema Sync] provides a quick and simple way to generate all the commands to update your database.

==Should I worry?==

Changes in field types (as long as they are compatible) and key name changes seem to be the common issues but '''should''' not cause problems. Things to look out for would be along the lines of missing fields and changes to default values.

If you are about to upgrade to Moodle 2.0 you should be more concerned. In order for the upgrade to proceed smoothly it is a very good idea to correct these problems.

== See also ==

* The missing indexes report in ''SiteAdmin->Misc->XMLDB editor->Check Indexes''
* [http://moodle.org/mod/forum/view.php?id=45 Moodle Databases Forum]

[[de:Datenbank-Schema prüfen]]
[[fr:Vérification du schéma de la base de données]]

Moodle migration

2013-05-15T07:21:34Z

Libertymoodle: /* See also link */

{{Installing Moodle}}
There may be times when you need to move your Moodle site from one server to another. For example, moving a Moodle site from shared hosting service's server to a dedicated server.

:''Tip:'' One common migration mistake is to forget to update the details in the migrated Moodle's ''[[Configuration file|config.php]]'' file.

==Migrating a complete Moodle site - method 1==

This involves moving a whole site from one server to another. If you are changing the domain/IP address to the new server you need to do these steps:
* '''Maintenance mode'''. Place your current Moodle site in maintenance mode to prevent any further additions to the Moodle database. Don't let administrators login during the migration as they are not affected by the maintenance mode setting.
* '''Backup your current Moodle database'''. Do this by following the instructions in the [[Upgrading | upgrading Moodle]] or [[Site backup]] page. This will give you a text file containing the mysql dump.
* '''Copy the Moodle software'''. You will need to copy the Moodle code itself to the new server - upgrade the code to the latest version if you can.
* '''Change <code>$CFG->wwwroot</code>'''. In your (possibly new) Moodle directory, change the <code>$CFG->wwwroot</code> variable in the ''config.php'' file for the new server.
* '''Copy data directory contents (moodledata)'''. Copy the contents of your data directory (check for the value in <code>$CFG->dataroot</code>) to the new server.
* '''Review moodledata permissions'''. Check also that permissions remain the same on the new dataroot folder and change the value if you have changed its location on the new server.
* '''Change your Moodle URL'''. If you have a new URL, you'll need to change this in the Moodle database to the new server. This is needed as links to pictures, files, etc are stored as absolute links and will reference the old <code>$CFG->wwwroot</code> value. So when loading a mysql backup dump of the Moodle server into mysql on another server the absolute referenced links will be broken. There are two methods of doing this:
:(a) The first method changes the Moodle URL using the Moodle script ''replace.php'' while your site is currently running just before you backup the Moodle database. Point your browser to <nowiki>http://yourserver.com/admin/replace.php</nowiki>

:Enter the url for your old server (<nowiki>http://oldserver.com/</nowiki>) and new server (<nowiki>http://newserver.com/</nowiki>) and it will fix the mysql tables. You will also need to clear out any cached links by restarting your webserver. Now, take another backup of the Moodle database - this one will have the correct URLs.

:(b) The second method is to backup the Moodle database first, then use the search and replace feature of your text editor (or use a unix tool like sed) to replace the old URL with the new one in the mysql backup file. Here is an example sed command:

: <code>#sed -e 's/oldserver.com/newserver.com/g' oldmysqldump.sql > newmysqldump.sql</code>

:''TIP:'' You may want to check the mysqldump file to see how the old server was referenced.
:After changing the URL, restore the mysql database
* '''Test the migration'''. To test the new install, access Moodle using your browser and the new server's URL. When you have tested that a number of links in the courses work, take the new Moodle site out of maintenance mode.
'''See also''': Forum discussion on [http://moodle.org/mod/forum/discuss.php?d=85812 migrating Moodle's data directory on a Windows system].

==Migrating a complete Moodle site - method 2==

Do you have shell access on both servers? If so, the following method is a very quick and efficient method to migrate a Unix based site.

It is also useful for creating snapshots or test sites.
*Set up a new empty database on the '''new''' server.

It mean that that you must not open the
http://example.domain/moodle/admin
webpage yet.
*Place your Moodle site into maintenance mode.
*Login to shell on the '''old''' server.
*Use rsync to copy '''moodledata''' and '''public_html''' (or whatever directory your Moodle install is in) to the new server - execute (replacing caps with your details; SOURCE = the directory you want to copy) for each directory:
::<code>rsync -av -e ssh SOURCE/ USERNAME@NEW_SERVER.COM:/PATH/TO/DESTINATION/</code>
On the new server you must to setup permissions on '''moodledata''' directory and it's subdirectories and files.

Say, on a Debian operating system one can run the command:
::<code>hostname:/var/lib# chown www-data:www-data -R moodle/</code>
*Dump existing database and move and import into database on new server by executing:
::<code>mysqldump --allow-keywords --opt -uMySQL_USERNAME -pPASSWORD DATABASE | ssh USER@DOMAIN "mysql -uMySQL_USERNAME -pPASSWORD DATABASE"</code>
*On the '''new server''', update '''config.php''' with relevant details.
*To fix any internal Moodle links, login to your "new" Moodle install on your new server and use '''admin/replace.php''' to search and replace the old uri for the new.
Say:
::<code>
Search and replace text throughout the whole database

Search whole database for: the.old.moodle.uri

Replace with this string: the.new.moodle.uri

*Make sure everything is working.</code>

Takes about 15 minutes.

When you are happy all has gone well, set up redirects/make DNS changes if required, take new site out of maintenance mode and "switch off" old site.

==Other points to consider==
===Changed URL image links set to old site===
So you built your Moodle Server with a <nowiki>http//192.168.0.1/Moodle address. Then you changed the URL for your site to http://OurMoodle.org/Moodle . You changed the Moodle config file so the CFGs point to the new paths. But your images point to the old url. </nowiki>

<nowiki>One simple, quick solution. Login as admin and put http://OurMoodle.org/Moodle/admin/replace.php in your browser address bar. Use the two form boxes to change http://192.168.0.1/ to http://OurMoodle.org/ .</nowiki>

===Upgrade Moodle===

When migrating Moodle it is often a good idea to take the opportunity to upgrade Moodle to the latest version. If you manage your own server, follow the instructions in [[Upgrading | upgrading moodle]], otherwise check if your host can upgrade for you.

===Restoring a single course across servers===

You may need to restore a single course from an old site to a new one, especially if you are testing the migration. When restoring a Moodle backup file to Moodle on a different server than the one used to create the backup, the absolute referenced links to files maybe broken. To fix this problem open the ''backup-coursename.zip'' file and edit the ''moodle.xml'' file replacing links with <code>$@FILEPHP@$</code>.

For example, replace <nowiki>http://yourserver.com/file.php/243/</nowiki> with <code>$@FILEPHP@$</code>

When the file is restored it will use the correct file path for the new course.

===DNS & Masquerading changes===

You may have had to change the DNS entries for the new Moodle site. If you have done so, it will take some time for the changes to replicate, so be patient. If your server is located behind a firewall, you may also have to change your firewall rules to allow access to the new server. See the [[Masquerading | masquerading docs]].

===Internal and external access===

If you have a set up where your Moodle site can be accessed via a network and via the internet, ensure you check that the new site can be accessed internally and externally.

==See also==

Moodle Docs:
* [[Site backup]]
* [[Site restore]]
* [[Backup and restore FAQ]]
* [http://www.youtube.com/watch?v=sFCXvRx20Bs Moving Moodle to a new server video]

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=62959 Changing Moodle URL]
* [http://moodle.org/mod/forum/discuss.php?d=57477 Changing site address]
* [http://moodle.org/mod/forum/discuss.php?d=76704 Upgrading whilst migrating]
* [http://moodle.org/mod/forum/discuss.php?d=65450 Internal and external access]
* [http://moodle.org/mod/forum/discuss.php?d=111807 Migrated Moodle to New Server But Can't Login]
* [http://moodle.org/mod/forum/discuss.php?d=228436 Replace script returns "Service Unavailable"]

[[fr:Migration de Moodle]]
[[nl:Moodle verhuizen]]
[[ja:Moodle移行]]
[[de:Moodle-Migration]]

error/moodle/invalidrecordunknown

2012-08-08T11:45:04Z

Libertymoodle: /* invalidrecordunknown description and possible cause */

This error can occur when Moodle tries to access a record in the Moodle database that does not exist. This can happen when you try to view your student profile in Moodle by manually entering the URL in the address bar of your browser. Example if you type http://yourschool.com/user/profile.php?id=12345 into your browser and the 12345 id does not correspond to the id of your Moodle profile you will get this error.

You should always avoid typing a url directly in the address bar of your browser when you are navigating through your Moodle site. Always use the nagigation that is part of Moodle to get around the site.

Active Directory

2011-11-30T08:00:12Z

Libertymoodle: /* See also */

Microsoft's Active Directory (AD) provides a variety of network directory services including Lightweight Directory Access Protocol (LDAP) like functions. It is included in Windows 2000 Server and later versions of their operating system. The focus of this page will be with the [[LDAP authentication]] functions.

==Trouble shooting AD and LDAP authentication==
===Warning: The PHP LDAP module does not seem to be present. Please ensure it is installed and enabled.===
This usually means that the main ldap dll or one of the supporting dlls are missing.
Let's start with the main one itself.
Browse to <nowiki>http://(moodleserver)/admin/phpinfo.php</nowiki> and examine the "Configuration File (php.ini) Path" field to determine which php.ini is being used and open it with an editor. Find the line 'extension=php_ldap.dll' and take out the semi-colon if it is there. That semi-colon will stop it loading the module all together!
While you have that file open, search for 'extension_dir' and note which folder it is set to. Open that folder and ensure the php_ldap.dll file is in there. If it isn't then put it in there.
If that still hasn't fixed it you are missing a supporting dll, but you don't get told that. To see what dlls are missing open the Command Prompt and navigate to the php directory and execute the following line 'php -m'. You should get some error messages now. Ugly, but at least they give you information! Find the dlls listed and copy them to the php directory. You may now need to restart the apache/httpd service. Run 'php -m' again and you should be error free and the message in Moodle should be gone now.

===LDAP-module cannot connect any LDAP servers===
LDAP-module cannot connect any LDAP servers:
Server: 'ldap://my.ldap.server/'
Connection: 'Resource id #26' Bind result: ''
Getting this message when you are trying to log in is a result of incorrect details for the Bind user, or the user account having insufficient permissions in Active Directory. The best way to test and resolve this is use ldp.exe to test binding until it suceeds. There are instructions on installing ldp.exe below.
Open the program and Connect to AD, giving the server name, then from the Connection menu choose Bind. Enter the details you think are correct and you will probably find that an error is returned. Try adjusting the accounts priveleges or another account until you are returned an "Authenticated as" message.
Once you are sure your account can be used to bind to AD, check that the DN of that users name is correct. Expand the tree on the left until you find the user you used to bind. Right click on that item and choose Copy DN. Go to the User Authentication page in Moodle and paste the value into the ldap_bind_dn field. Add the password and you can now feel safe your user is binding sucessfully.

===Getting correct CNs for Contexts and Creators===
For those not familiar with AD this could be very confusing, and not that easy for some who are familiar with it. Again, ldp.exe is your friend. There are instructions on installing ldp.exe below.
Open it up and expand the tree on the left until you find the group or user you want to use and right click on it and select Copy DN. Go back to the Moodle User Authentication page and paste that value into either ldap_contexts or ldap_creators.

===Getting the right user_attribute===
By default, Moodle uses an accounts cn (full name) to verify against, but most networks don't use a full given name for logon as it's too easy to guess and you can easily have two people with the same name. If this is the case for you too you need to tell Moodle to look at another field for the logon id.
In ldp.exe navigate the tree on the left to find a user account, preferably your own. Double-click the item in the tree and full-details will be loaded into the screen on the right. Look down the details until you find your logon id and note the item listed against it. For me, and a lot of people, it is sAMAccountName. Copy this name and paste it into the ldap_user_attribute on the Moodle User Authentication page.
There are instructions on installing ldp.exe below.

===Installing ldp.exe Server Tool===
ldp.exe comes as part of the Server Tools on most versions of Windows Server. Find your Windows Server installation disc and find a folder on it called Support\Tools. In there will be a SupTools.msi which will install the server tools if run. You should now have a folder under Program Files called Support Tools, in which will be ldp.exe. ldp.exe is also available in the Windows XP Support Tools, which you can download from Microsoft [http://www.microsoft.com/downloads/details.aspx?FamilyId=49AE8576-9BB9-4126-9761-BA8011FABF38&displaylang=en here]. Alternatively, a single download of ldp.exe is available [http://www.computerperformance.co.uk/w2k3/utilities/ldp.htm here].

===Example Active Directory Configuration===
Below is an example configuration for Active Directory. As detailed above, the values may vary based on your local Active Directory configuration, but should provide a good starting point for most cases.

ldap_host_url = ldap://ads.example.com
ldap_version = 3
ldap_preventpassindb = yes
ldap_bind_dn = bind-user@example.com
ldap_bind_pw = bind-password
ldap_user_type = MS ActiveDirectory
ldap_contexts = ou=moodleusers,dc=example,dc=com
ldap_user_attribute = sAMAccountName

Note that the ldap_bind_dn value should work in either the CN=bin-user,CN=Users,DC=example,DC=com format as shown in the main instructions or the bind-user@example.com format shown in this example.

==Global Catalogs==
Moodle currently only has limited support for multiple domain controllers; specifically it expects each of the LDAP servers listed to contain identical sets of information. If you have users in multiple domains this presents an issue. One solution when working with MS-AD is to use the Global Catalog. The Global Catalog is designed to be a read-only, partial representation of an entire MS-AD forest, designed for searching the entire directory when the domain of the required object is not known.

===Enabling the Global Catalog===

The Global Catalog is available on Windows 2000 and Windows 2003 Active Directory servers. To enable, open the ‘Active Directory Sites and Services’ MMC (Microsoft Management Console) snap-in. Extend ‘Sites’ and then the name of the Site containing the active directory forest you wish to use. Expand the server you wish to enable the Global Catalog on, right click ‘NTDS settings’ and select the ‘Properties’ tab. To enable, simply click the ‘Global Catalog’ checkbox. Under a Windows 2000 server it is necessary to restart the server (although it won’t prompt you to); under Windows 2003 server it is not necessary to restart the server. In either case you will generally have to wait for the AD forest to replicate before the Global Catalog offers a representation of the entire AD forest. Changes made in Active Directory will also be subject to a short delay due to the latency involved with replication. If your AD servers are firewalled port 3268 will need to be opened for Global Catalog servers.
If your organisation uses Microsoft Exchange then it its highly likely that at least one Domain Controller will already have Global Catalog enabled – Exchange 2000 and 2003 rely on the Global Catalog for address information, users also access the Global Catalog when using the GAL (Global Address List)

===Child Domains===
If your organisation has a main domain example.org, staff and students are contained in two child domains staff.example.org and students.example.org. The 3 domains (example.org, staff.example.org and students.example.org) each have a domain controller (dc01, dc02 and dc03 respectively.) Each domain controller contains a full, writable, representation of only the objects that belong to its domain. However, assuming that the Global Catalog has been enabled (see below) on one of the domain controllers (for example dc01) a query to the Global Catalog would reveal matching objects from all three domains. The Global Catalog is automatically maintained through replication across the active directory forest, it can also be enabled on multiple servers (if, for example, you need redundancy / load balancing.)

To make use of this in Moodle to allow logins from multiple domains is simple. The Global Catalog runs on port 3268 as opposed to 389 for standard LDAP queries. As a result, still assuming the Global Catalog is running on dc01, the ''''ldap_host_url'''' would be ''ldap://dc01.example.org:3268''. The rest of the settings are the same as for other MS-AS Auth setups.

You should use the ''''ldap_contexts'''' setting to indicate the locations of individuals you wish to grant access. To extend the example above a little: In the example.org domain users are all in the'' 'Users' ''OU, in the staff.example.org domain users are in two OUs at the root of the domain,'' 'Support Staff' ''and'' 'Teaching Staff' '', and in the students.example.org domain students are in an OU indicating the year that they enrolled, all of which are under the'' 'Students' ''OU. As a result our ''''ldap_contexts'''' setting may look a little like this:'' 'OU=Users,DC=example,DC=org; OU=Support Staff,DC=staff,DC=example,DC=org; OU=Teaching Staff,DC=staff,DC=example,DC=org; OU=Students,DC=students,DC=example,DC=org''.' The ''''ldap_search_sub'''' option should be set to'' 'Yes' ''to allow moodle to search within the child OUs.

Its worth noting that the Global Catalog only contains a partial representation of the attributes of each object, as defined in the Partial Attribute Set supplied by Microsoft. However common information likely to be of use to a general Moodle installation (Forename, Surname, Email Address, sAMAccountName etc) is included in the set. For specific needs the schema can be altered to remove or add various attributes - see Microsoft [http://support.microsoft.com/kb/248717 KB248717] for more information.

In most cases the Global Catalog is read-only, update queries must be made over the standard LDAP ports to the domain controller that holds the object in question (in our example, updating a student's details would require an LDAP query to the students.example.org domain controller - dc03, it would not be possible to update details by querying the Global Catalog.) The exception to this would be in an environment where there is only a single domain in the active directory forest; in this case the Global Catalog holds a writable full set of attributes for each object in the domain. However, for the purposes of Moodle authorisation, there would be no need to use the Global Catalog in this case.

===MaxPageSize setting===
Modifying the number of Active Directory objects to search:

By default Active Directory only allows searches returning a limited number of objects per search. Since there is currently no Page control support in PHP 5.2.x which would enable smaller page searches you may need to modify your MaxPageSize setting to make sure LDAP Client searches can return enough user objects to support the number of authenticating users.

If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, follow the instructions [http://support.microsoft.com/kb/315071 here] to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.

==MS Active Directory + SSL ==

If the Certificate Authority is not installed you'll have to install it first as follows:
# Click '''Start''' -> '''Control Panel''' -> '''Add or Remove programs.'''
# Click '''Add/Remove Windows Components''' and select '''Certificate Services.'''
# Follow the procedure provided to install the '''Certificate Authority'''. Enterprise level is a good choice.

Verify that SSL has been enabled on the server by installing suptools.msi from Windows installation cd's \Support\tools directory. After support tools installation:
# Select '''Start''' -> '''Run''', write '''ldp''' in the Open field.
# From the ldp window select '''Connection''' -> '''Connect''' and supply valid hostname and port number '''636'''. Also select the SSL check box.

If successful, you should get information about the connection.

See [[LDAP_authentication#Enabling_LDAPS_on_the_client_side_.28Moodle_server.29|Enabling LDAPS on the client side (Moodle server)]] for details on the client side configuration.

==See also==
*[[LDAP authentication]] in Moodle
*[http://en.wikipedia.org/wiki/Directory_service Directory services] overview in Wikipedia
*[http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol LDAP] in Wikipedia
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers - Our students are on separate domain] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=74279 How to use multiple LDAP servers with Moodle 1.8] forum discussion

[[ja:Active Directory]]

Active Directory

2011-11-30T07:58:45Z

Libertymoodle: /* See also link */

Microsoft's Active Directory (AD) provides a variety of network directory services including Lightweight Directory Access Protocol (LDAP) like functions. It is included in Windows 2000 Server and later versions of their operating system. The focus of this page will be with the [[LDAP authentication]] functions.

==Trouble shooting AD and LDAP authentication==
===Warning: The PHP LDAP module does not seem to be present. Please ensure it is installed and enabled.===
This usually means that the main ldap dll or one of the supporting dlls are missing.
Let's start with the main one itself.
Browse to <nowiki>http://(moodleserver)/admin/phpinfo.php</nowiki> and examine the "Configuration File (php.ini) Path" field to determine which php.ini is being used and open it with an editor. Find the line 'extension=php_ldap.dll' and take out the semi-colon if it is there. That semi-colon will stop it loading the module all together!
While you have that file open, search for 'extension_dir' and note which folder it is set to. Open that folder and ensure the php_ldap.dll file is in there. If it isn't then put it in there.
If that still hasn't fixed it you are missing a supporting dll, but you don't get told that. To see what dlls are missing open the Command Prompt and navigate to the php directory and execute the following line 'php -m'. You should get some error messages now. Ugly, but at least they give you information! Find the dlls listed and copy them to the php directory. You may now need to restart the apache/httpd service. Run 'php -m' again and you should be error free and the message in Moodle should be gone now.

===LDAP-module cannot connect any LDAP servers===
LDAP-module cannot connect any LDAP servers:
Server: 'ldap://my.ldap.server/'
Connection: 'Resource id #26' Bind result: ''
Getting this message when you are trying to log in is a result of incorrect details for the Bind user, or the user account having insufficient permissions in Active Directory. The best way to test and resolve this is use ldp.exe to test binding until it suceeds. There are instructions on installing ldp.exe below.
Open the program and Connect to AD, giving the server name, then from the Connection menu choose Bind. Enter the details you think are correct and you will probably find that an error is returned. Try adjusting the accounts priveleges or another account until you are returned an "Authenticated as" message.
Once you are sure your account can be used to bind to AD, check that the DN of that users name is correct. Expand the tree on the left until you find the user you used to bind. Right click on that item and choose Copy DN. Go to the User Authentication page in Moodle and paste the value into the ldap_bind_dn field. Add the password and you can now feel safe your user is binding sucessfully.

===Getting correct CNs for Contexts and Creators===
For those not familiar with AD this could be very confusing, and not that easy for some who are familiar with it. Again, ldp.exe is your friend. There are instructions on installing ldp.exe below.
Open it up and expand the tree on the left until you find the group or user you want to use and right click on it and select Copy DN. Go back to the Moodle User Authentication page and paste that value into either ldap_contexts or ldap_creators.

===Getting the right user_attribute===
By default, Moodle uses an accounts cn (full name) to verify against, but most networks don't use a full given name for logon as it's too easy to guess and you can easily have two people with the same name. If this is the case for you too you need to tell Moodle to look at another field for the logon id.
In ldp.exe navigate the tree on the left to find a user account, preferably your own. Double-click the item in the tree and full-details will be loaded into the screen on the right. Look down the details until you find your logon id and note the item listed against it. For me, and a lot of people, it is sAMAccountName. Copy this name and paste it into the ldap_user_attribute on the Moodle User Authentication page.
There are instructions on installing ldp.exe below.

===Installing ldp.exe Server Tool===
ldp.exe comes as part of the Server Tools on most versions of Windows Server. Find your Windows Server installation disc and find a folder on it called Support\Tools. In there will be a SupTools.msi which will install the server tools if run. You should now have a folder under Program Files called Support Tools, in which will be ldp.exe. ldp.exe is also available in the Windows XP Support Tools, which you can download from Microsoft [http://www.microsoft.com/downloads/details.aspx?FamilyId=49AE8576-9BB9-4126-9761-BA8011FABF38&displaylang=en here]. Alternatively, a single download of ldp.exe is available [http://www.computerperformance.co.uk/w2k3/utilities/ldp.htm here].

===Example Active Directory Configuration===
Below is an example configuration for Active Directory. As detailed above, the values may vary based on your local Active Directory configuration, but should provide a good starting point for most cases.

ldap_host_url = ldap://ads.example.com
ldap_version = 3
ldap_preventpassindb = yes
ldap_bind_dn = bind-user@example.com
ldap_bind_pw = bind-password
ldap_user_type = MS ActiveDirectory
ldap_contexts = ou=moodleusers,dc=example,dc=com
ldap_user_attribute = sAMAccountName

Note that the ldap_bind_dn value should work in either the CN=bin-user,CN=Users,DC=example,DC=com format as shown in the main instructions or the bind-user@example.com format shown in this example.

==Global Catalogs==
Moodle currently only has limited support for multiple domain controllers; specifically it expects each of the LDAP servers listed to contain identical sets of information. If you have users in multiple domains this presents an issue. One solution when working with MS-AD is to use the Global Catalog. The Global Catalog is designed to be a read-only, partial representation of an entire MS-AD forest, designed for searching the entire directory when the domain of the required object is not known.

===Enabling the Global Catalog===

The Global Catalog is available on Windows 2000 and Windows 2003 Active Directory servers. To enable, open the ‘Active Directory Sites and Services’ MMC (Microsoft Management Console) snap-in. Extend ‘Sites’ and then the name of the Site containing the active directory forest you wish to use. Expand the server you wish to enable the Global Catalog on, right click ‘NTDS settings’ and select the ‘Properties’ tab. To enable, simply click the ‘Global Catalog’ checkbox. Under a Windows 2000 server it is necessary to restart the server (although it won’t prompt you to); under Windows 2003 server it is not necessary to restart the server. In either case you will generally have to wait for the AD forest to replicate before the Global Catalog offers a representation of the entire AD forest. Changes made in Active Directory will also be subject to a short delay due to the latency involved with replication. If your AD servers are firewalled port 3268 will need to be opened for Global Catalog servers.
If your organisation uses Microsoft Exchange then it its highly likely that at least one Domain Controller will already have Global Catalog enabled – Exchange 2000 and 2003 rely on the Global Catalog for address information, users also access the Global Catalog when using the GAL (Global Address List)

===Child Domains===
If your organisation has a main domain example.org, staff and students are contained in two child domains staff.example.org and students.example.org. The 3 domains (example.org, staff.example.org and students.example.org) each have a domain controller (dc01, dc02 and dc03 respectively.) Each domain controller contains a full, writable, representation of only the objects that belong to its domain. However, assuming that the Global Catalog has been enabled (see below) on one of the domain controllers (for example dc01) a query to the Global Catalog would reveal matching objects from all three domains. The Global Catalog is automatically maintained through replication across the active directory forest, it can also be enabled on multiple servers (if, for example, you need redundancy / load balancing.)

To make use of this in Moodle to allow logins from multiple domains is simple. The Global Catalog runs on port 3268 as opposed to 389 for standard LDAP queries. As a result, still assuming the Global Catalog is running on dc01, the ''''ldap_host_url'''' would be ''ldap://dc01.example.org:3268''. The rest of the settings are the same as for other MS-AS Auth setups.

You should use the ''''ldap_contexts'''' setting to indicate the locations of individuals you wish to grant access. To extend the example above a little: In the example.org domain users are all in the'' 'Users' ''OU, in the staff.example.org domain users are in two OUs at the root of the domain,'' 'Support Staff' ''and'' 'Teaching Staff' '', and in the students.example.org domain students are in an OU indicating the year that they enrolled, all of which are under the'' 'Students' ''OU. As a result our ''''ldap_contexts'''' setting may look a little like this:'' 'OU=Users,DC=example,DC=org; OU=Support Staff,DC=staff,DC=example,DC=org; OU=Teaching Staff,DC=staff,DC=example,DC=org; OU=Students,DC=students,DC=example,DC=org''.' The ''''ldap_search_sub'''' option should be set to'' 'Yes' ''to allow moodle to search within the child OUs.

Its worth noting that the Global Catalog only contains a partial representation of the attributes of each object, as defined in the Partial Attribute Set supplied by Microsoft. However common information likely to be of use to a general Moodle installation (Forename, Surname, Email Address, sAMAccountName etc) is included in the set. For specific needs the schema can be altered to remove or add various attributes - see Microsoft [http://support.microsoft.com/kb/248717 KB248717] for more information.

In most cases the Global Catalog is read-only, update queries must be made over the standard LDAP ports to the domain controller that holds the object in question (in our example, updating a student's details would require an LDAP query to the students.example.org domain controller - dc03, it would not be possible to update details by querying the Global Catalog.) The exception to this would be in an environment where there is only a single domain in the active directory forest; in this case the Global Catalog holds a writable full set of attributes for each object in the domain. However, for the purposes of Moodle authorisation, there would be no need to use the Global Catalog in this case.

===MaxPageSize setting===
Modifying the number of Active Directory objects to search:

By default Active Directory only allows searches returning a limited number of objects per search. Since there is currently no Page control support in PHP 5.2.x which would enable smaller page searches you may need to modify your MaxPageSize setting to make sure LDAP Client searches can return enough user objects to support the number of authenticating users.

If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, follow the instructions [http://support.microsoft.com/kb/315071 here] to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.

==MS Active Directory + SSL ==

If the Certificate Authority is not installed you'll have to install it first as follows:
# Click '''Start''' -> '''Control Panel''' -> '''Add or Remove programs.'''
# Click '''Add/Remove Windows Components''' and select '''Certificate Services.'''
# Follow the procedure provided to install the '''Certificate Authority'''. Enterprise level is a good choice.

Verify that SSL has been enabled on the server by installing suptools.msi from Windows installation cd's \Support\tools directory. After support tools installation:
# Select '''Start''' -> '''Run''', write '''ldp''' in the Open field.
# From the ldp window select '''Connection''' -> '''Connect''' and supply valid hostname and port number '''636'''. Also select the SSL check box.

If successful, you should get information about the connection.

See [[LDAP_authentication#Enabling_LDAPS_on_the_client_side_.28Moodle_server.29|Enabling LDAPS on the client side (Moodle server)]] for details on the client side configuration.

==See also==
*[[LDAP authentication]] in Moodle
*[http://en.wikipedia.org/wiki/Directory_service Directory services] overview in Wikipedia
*[http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol LDAP] in Wikipedia
*[http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers - Our students are on separate domain] Using Moodle forum discussion
*[http://moodle.org/mod/forum/discuss.php?d=74279 How to use multiple LDAP servers with Moodle 1.8] Using Moodle forum discussion

[[ja:Active Directory]]

Using the Microsoft SQL Server Driver for PHP

2011-11-13T16:16:19Z

Libertymoodle: Updated driver link. Removed ref to "minimum version required is v1.1" V1.1 of th driver is deprecated.

== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using the Microsoft SQL Server (MSSQL) RDBMS. The steps detailed below must be performed '''before''' installing Moodle itself.

First of all, the minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).

== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=20098 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming that MSSQL is on the same server, otherwise
// use the actual name or IP address of your database server
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences,
// but NEVER leave this blank!
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, turn '''display_startup_errors''' to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Postgres for PHP]]
* [[Installing MSSQL for PHP]]
* [[Installing Oracle for PHP]]
* Microsoft SQL Server Driver for PHP solves major Moodle performance problems. See: [http://moodle.org/mod/forum/discuss.php?d=183987 Hardware and Performance Forum]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:XMLDB]]

Performance recommendations

2011-10-21T08:55:21Z

Libertymoodle: /* PHP performance - WinCache */

{{Performance}}
Moodle can be made to perform very well, at small usage levels or scaling up to many thousands of users. The factors involved in performance are basically the same as for any PHP-based database-driven system. When trying to optimize your server, try to focus on the factor which will make the most difference to the user. For example, if you have relatively more users browsing than accessing the database, look to improve the webserver performance.

==Obtain a baseline benchmark==

Before attempting any optimization, you should obtain a baseline benchmark of the component of the system you are trying to improve. For Linux try [http://lbs.sourceforge.net/ LBS] and for Windows use the Performance Monitor. Once you have quantitative data about how your system is performing currently, you'll be able to determine if the change you have made has had any real impact.

The overall aim of adjustments to improve performance is to use RAM (cacheing) and to reduce disk-based activity. It is especially important to try to eliminate swap file usage as much as you can. If your system starts swapping, this is a sign that you need more RAM.

The '''optimization order preference''' is usually: primary storage (more RAM), secondary storage (faster hard disks/improved hard disk configuration), processor (more and faster).

==Scalability==

Moodle's design (with clear separation of application layers) allows for strongly scalable setups. (Please check the list of [[Large installations|large Moodle installations]].)

Large sites usually separate the web server and database onto separate servers, although for smaller installations this is typically not necessary.

It is possible to load-balance a Moodle installation, for example by using more than one webserver. The separate webservers should query the same database and refer to the same filestore area, but otherwise the separation of the application layers is complete enough to make this kind of clustering feasible. Similarly, the database could be a cluster of servers (e.g. a MySQL cluster), but this is not an easy task and you should seek expert support, e.g. from a Moodle Partner.

'''See also''':
*[[Server cluster]]
*[http://moodle.org/mod/forum/discuss.php?d=4801 Scalability] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=57202 Moodle clustering] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=44470 Software load balancing] forum discussion.
*[http://moodle.org/mod/forum/discuss.php?d=49986 TCP load balancing] forum dicsussion.

==Hardware configuration==
'''Note''': The fastest and most effective change that you can make to improve performance is to '''increase the amount of RAM on your web server''' - get as much as possible (eg 4GB). Increasing primary memory will reduce the need for processes to swap to disk and will enable your server to handle more users.
* Better performance is gained by obtaining the best '''processor capability''' you can, i.e. dual or dual core processors. A modern BIOS should allow you to enable hyperthreading, but check if this makes a difference to the overall performance of the processors by using a [http://en.wikipedia.org/wiki/Super_PI CPU benchmarking tool].
* If you can afford them, use '''SCSI hard disks''' instead of SATA drives. SATA drives will increase your system's CPU utilization, whereas SCSI drives have their own integrated processors and come into their own when you have multiple drives. If you must have SATA drives, check that your motherboard and the drives themselves support NCQ (Native Command Queuing).
* Purchase hard disks with a '''low seek time'''. This will improve the overall speed of your system, especially when accessing Moodle's reports.
* Size your '''swap file''' correctly. The general advice is to set it to 4 x physical RAM.
* Use a '''RAID disk system'''. Although there are many different RAID configurations you can create, the following generally works best:
** install a hardware RAID controller (if you can)
** the operating system and swap drive on one set of disks configured as RAID-1.
** Moodle, Web server and Database server on another set of disks configured as RAID-5.
* Use '''gigabit ethernet''' for improved latency and throughput. This is especially important when you have your webserver and database server separated out on different hosts.
* Check the settings on your '''network card'''. You may get an improvement in performance by increasing the use of buffers and transmit/receive descriptors (balance this with processor and memory overheads) and off-loading TCP checksum calculation onto the card instead of the OS.
* Read this [http://moodle.org/mod/forum/discuss.php?d=68579 Case Study] on a server stress test with 300 users.
* See this [http://elearning.sgu.ac.jp/doc/PT/ accompanying report] on network traffic and server loads.
* See the [[Moodle.org configuration]]
* Also see this SFSU presentation at Educause (using VMWare): [http://www.educause.edu/Resources/AnOpenSourceLMSforaMissionCrit/162843]

==Operating System==
* You can use [http://en.wikipedia.org/wiki/Linux Linux](recommended), Unix-based, Windows or Mac OS X for the server '''operating system'''. *nix operating systems generally require less memory than Mac OS X or Windows servers for doing the same task as the server is configured with just a shell interface. Additionally Linux does not have licensing fees attached, but can have a big learning curve if you're used to another operating system. If you have a large number of processors running SMP, you may also want to consider using a highly tuned OS such as [http://en.wikipedia.org/wiki/Solaris_Operating_Environment Solaris].
* Check your own OS and '''vendor specific instructions''' for optimization steps.
** For Linux look at the [http://linuxperf.sourceforge.net/ Linux Performance Team] site.
** For Linux investigate the hdparm command, e.g. hdparm -m16 -d1 can be used to enable read/write on multiple sectors and DMA. Mount disks with the async and noatime options.
** For Windows set the sever to be optimized for network applications (Control Panel, Network Connections, LAN connection, Properties, File & Printer Sharing for Microsoft Networks, Properties, Optimization). You can also search the [http://technet.microsoft.com/ Microsoft TechNet site] for optimization documents.

==Web server performance==

Installing [http://www.mozilla.com/en-US/ Firefox] and the [https://addons.mozilla.org/en-US/firefox/addon/1843 firebug] extension will allow you to watch the time it takes for each page component to load. Also, the [https://addons.mozilla.org/en-US/firefox/addon/5369 Yslow] extension will evaluate your page against Yahoo's [http://www.skrenta.com/2007/05/14_rules_for_fast_web_pages_by_1.html 14 rules], full text [http://developer.yahoo.com/performance/rules.html Best Practices for Speeding Up Your Web Site], <strike>([http://video.yahoo.com/video/play?vid=1040890 video])</strike> for fast loading websites.

===PHP performance===
* You are strongly recommended to use a '''PHP accelerator''' to ease CPU load, such as [http://pecl.php.net/apc APC], [http://www.php-accelerator.co.uk/ PHPA], [http://trac.lighttpd.net/xcache/ Xcache], [http://sourceforge.net/projects/wincache WinCache] or [http://eaccelerator.net/ eAccelerator]. (Take care to choose a PHP accelerator that is known to work well with your version of PHP and note that Turck MMCache is [http://turckmmcache.exeprod.com/TheManifestoEnglish no longer maintained] and can cause failures with PHP 5).
* Improvements in read/write performance can be improved by putting the cached PHP pages on a [[TMPFS]] filesystem - but remember that you'll lose the cache contents when there is a power failure or the server is rebooted.
* Performance of PHP is better when installed as an '''Apache/IIS ISAPI module''' (rather than a CGI).
* Also check the '''memory_limit''' in php.ini, reduce it to 16M for Moodle version earlier than 1.7 ([http://moodle.org/mod/forum/discuss.php?d=39656 See this forum discussion]). For Moodle 1.7 or later, it is recommended that the value of memory_limit should be 40M. As of [http://www.php.net/ChangeLog-5.php PHP 5.2.1] the default value for the memory_limit directive is 128M.
* Also see [[PHP_settings_by_Moodle_version]]

===Install HowTo===
* [http://2bits.com/articles/installing-php-apc-gnulinux-centos-5.html APC on CentOS 5.x (linux)]
* [http://fplanque.com/dev/linux/install-apc-php-cache-debian-lenny APC on Debian (linux)]
* [http://www.linuxtuts.net/211-installing-memcached-php5-memcache-module-debian-apache2.html MemCache module on Debian (Apache2 and PHP5) ]
* [http://noveckg.blogspot.com/2010/03/installing-memcached-on-centos-5x.html Installing Memcache on CentOS 5.x (linux)]
* [http://noveckg.blogspot.com/2010/02/installing-eaccelerator-cache-for-php.html Installing eAccelerator on CentOS 5.x (linux)]
* [https://docs.moodle.org/en/Installing_eAccelerator_In_Ubuntu_Server/ Installing eAccelerator on Ubuntu Server (linux)]

===Apache performance===
* If you are using Apache on a Windows server, use the build from [http://www.apachelounge.com Apache Lounge] which is reported to have [http://moodle.org/mod/forum/discuss.php?d=93358 performance and stability improvements] compared to the official Apache download. Note that this is an unofficial build, so may not keep up with official releases.
* Set the '''MaxClients''' directive correctly. Use this formula to help (which uses 80% of available memory to leave room for spare):
MaxClients = Total available memory * 80% / Max memory usage of apache process
:Memory usage of apache process is usually 10MB, so a general rule of thumb is to divide your available memory in megabytes by 10 to get the value of MaxClients. To find the max memory usage of apache processes read the value from the shell command:
#ps -ylC httpd --sort:rss

:If you need to increase the value of '''MaxClients''' beyond 256, you will also need to set the '''ServerLimit''' directive.

:'''Warning''': Do not be tempted to set the value of MaxClients higher than your available memory as your server will consume more RAM than available and start to swap to disk.
* Consider reducing the '''number of modules''' that Apache loads in the httpd.conf file to the minumum necessary to reduce the memory needed.
* Use the '''latest version of Apache''' - Apache 2 has an improved memory model which reduces memory usage further.
* For Unix/Linux systems, consider lowering '''MaxRequestsPerChild''' in httpd.conf to as low as 20-30 (if you set it any lower the overhead of forking begins to outweigh the benefits).
* For a heavily loaded server, consider setting '''KeepAlive Off''' (do this only if your Moodle pages do not contain links to resources or uploaded images) or lowering the '''KeepAliveTimeout''' to between 2 and 5. The default is 15 (seconds) - the higher the value the more server processes will be kept waiting for possibly idle connections. A more accurate value for KeepAliveTimeout is obtained by observing how long it takes your users to download a page. After altering any of the KeepAlive variables, monitor your CPU utilization as there may be an additional overhead in initiating more worker processes/threads.
* As an alternative to using KeepAlive Off, consider setting-up a '''Reverse Proxy server''' infront of the Moodle server to cache HTML files with images. You can then return Apache to using keep-alives on the Moodle server.
* If you do not use a .htaccess file, set the '''AllowOverride''' variable to AllowOverride None to prevent .htaccess lookups.
* Set '''DirectoryIndex''' correctly so as to avoid content-negotiation. Here's an example from a production server:
DirectoryIndex index.php index.html index.htm
* Unless you are doing development work on the server, set '''ExtendedStatus Off''' and disable mod_info as well as mod_status.
* Leave '''HostnameLookups Off''' (as default) to reduce DNS latency.
* Consider reducing the value of '''TimeOut''' to between 30 to 60 (seconds).
* For the '''Options directive''', avoid Options Multiviews as this performs a directory scan. To reduce disk I/O further use
Options -Indexes FollowSymLinks
*'''Caching (unsupported)''' - ''Please note that this kind of caching may create major problems during upgrades.'' Apache can be told to make pages load a lot faster by specifying that the browser should cache some various page elements such as images and reuse them from local memory rather than ask for them again every time a page is requested. How to do this varies slightly between OSes but there are two basic steps:

# Install and enable mod_expires - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<IfModule mod_expires.c>
ExpiresActive On
ExpiresDefault "access plus 1 seconds"
ExpiresByType text/html "access plus 1 seconds"
ExpiresByType image/gif "access plus 1 week"
ExpiresByType image/jpeg "access plus 1 week"
ExpiresByType image/png "access plus 1 week"
ExpiresByType text/css "access plus 1 week"
ExpiresByType text/javascript "access plus 1 week"
ExpiresByType application/x-javascript "access plus 1 week"
ExpiresByType text/xml "access plus 1 seconds"
</IfModule>

The effect is to make everything stay in the cache except HTML and XML, which change dynamically. It's possible to gain a several hundred percent decrease in load times this way. Adjust the cache times according to how often your images etc change.

* Compression reduces response times by reducing the size of the HTTP response
# Install and enable mod_deflate - refer to documentation or man pages
# Add this code to the virtual server config file within the <directory> section for the root directory (or within the .htaccess file if AllowOverrides is On):
<ifModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/html text/plain text/xml
</ifmodule>

More info: [http://www.metaskills.net/blog/heuristics/sysadmin/how-to-control-browser-caching-with-apache-2 www.metaskills.net]

===IIS performance===
All alter this location in the registry:
HKLM\SYSTEM\CurrentControlSet\Services\Inetinfo\Parameters\
* The equivalent to KeepAliveTimeout is '''ListenBackLog''' (IIS - registry location is HKLM\ SYSTEM\ CurrentControlSet\ Services\ Inetinfo\ Parameters). Set this to between 2 to 5.
*Change the '''MemCacheSize''' value to adjust the amount of memory (Mb) that IIS will use for its file cache (50% of available memory by default).
*Change the '''MaxCachedFileSize''' to adjust the maximum size of a file cached in the file cache in bytes. Default is 262,144 (256K).
*Create a new DWORD called '''ObjectCacheTTL''' to change the length of time (in milliseconds) that objects in the cache are held in memory. Default is 30,000 milliseconds (30 seconds).

===Lighttpd, NginX and Cherokee performance===
You can increase server performance by using a '''light-weight''' webserver like [http://www.lighttpd.net/ lighttpd], [http://nginx.net/ nginx] or [http://www.cherokee-project.com/ cherokee] in combination with PHP in FastCGI-mode. Lighttpd was originally created as a proof-of-concept[http://www.lighttpd.net/story] to address the [http://www.kegel.com/c10k.html C10k problem] and while primarily recommended for memory-limited servers, its design origins and asynchronous-IO model make it a suitable and proven[http://blog.lighttpd.net/articles/2006/12/28/lighttpd-powers-5-alexa-top-250-sites] alternative HTTP server for high-load websites and web apps, including Moodle. See the [[lighttpd | MoodleDocs Lighttpd page]] for additional information, configuration example and links.

Alternatively, both [http://www.lighttpd.net/ lighttpd] and [http://nginx.net/ nginx] are capable of performing as a load-balancer and/or reverse-proxy to alleviate load on back-end servers[http://www.linuxjournal.com/article/10108], providing benefit without requiring an actual software change on existing servers.

Do note that these are likely to be the least tested server environments of all particularly if you are using advanced features such as web services and/or Moodle Networking. They are probably best considered for heavily used Moodle sites with relatively simple configurations.

==Database performance==

Moodle contains a script which will display some key database performance statistics from the [http://phplens.com/lens/adodb/docs-perf.htm ADOdb performance monitor]. Run the script in your browser as in the following example:

http://www.mymoodle.com/admin/dbperformance.php

Use the data displayed as a guide to tune and improve the performance of your database server.

===MySQL performance===

The following are MySQL specific settings which can be adjusted for better performance in your my.cnf (my.ini in Windows). The file contains a list of settings and their values. To see the current values use these commands
SHOW STATUS;
SHOW VARIABLES;
'''Important''': You must make backups of your database before attempting to change any MySQL server configuration. After any change to the my.cnf, restart mysqld.

If you are able, the [http://mysqltuner.com/ MySQLTuner] tool can be run against your MySQL server and will calculate appropriate configuration values for most of the following settings based on your current load, status and variables automatically.

* Enable the '''query cache''' with
query_cache_type = 1.
For most Moodle installs, set the following:
query_cache_size = 36M
query_cache_min_res_unit = 2K.
The query cache will improve performance if you are doing few updates on the database.
* Set the '''table cache''' correctly. For Moodle 1.6 set
table_cache = 256 #(table_open_cache in MySQL > 5.1.2)
(min), and for Moodle 1.7 set
table_cache = 512 #(table_open_cache in MySQL > 5.1.2)
(min). The table cache is used by all threads (connections), so monitor the value of opened_tables to further adjust - if opened_tables > 3 * table_cache(table_open_cache in MySQL > 5.1.2) then increase table_cache upto your OS limit. Note also that the figure for table_cache will also change depending on the number of modules and plugins you have installed. Find the number for your server by executing the mysql statement below. Look at the number returned and set table_cache to this value.
mysql>SELECT COUNT(table_name) FROM information_schema.tables WHERE table_schema='yourmoodledbname';
* Set the '''thread cache''' correctly. Adjust the value so that your thread cache utilization is as close to 100% as possible by this formula:
thread cache utilization (%) = (threads_created / connections) * 100
* The '''key buffer''' can improve the access speed to Moodle's SELECT queries. The correct size depends on the size of the index files (.myi) and in Moodle 1.6 or later (without any additional modules and plugins), the recommendation for this value is key_buffer_size = 32M. Ideally you want the database to be reading once from the disk for every 100 requests so monitor that the value is suitable for your install by adjusting the value of key_buffer_size so that the following formulas are true:
key_read / key_read_requests < 0.01
key_write / key_write_requests <= 1.0
* Set the '''maximum number of connections''' so that your users will not see a "Too many connections" message. Be careful that this may have an impact on the total memory used. MySQL connections usually last for milliseconds, so it is unusual even for a heavily loaded server for this value to be over 200.
* Manage '''high burst activity'''. If your Moodle install uses a lot of quizzes and you are experiencing performance problems (check by monitoring the value of threads_connected - it should not be rising) consider increasing the value of back_log.
* '''Optimize your tables weekly and after upgrading Moodle'''. It is good practice to also optimize your tables after performing a large data deletion exercise, e.g. at the end of your semester or academic year. This will ensure that index files are up to date. Backup your database first and then use:
mysql>CHECK TABLE mdl_tablename;
mysql>OPTIMIZE TABLE mdl_tablename;
:The common tables in Moodle to check are mdl_course_sections, mdl_forum_posts, mdl_log and mdl_sessions (if using dbsessions). Any errors need to be corrected using REPAIR TABLE (see the [http://dev.mysql.com/doc/refman/5.0/en/repair-table.html MySQL manual] and this [http://moodle.org/mod/forum/discuss.php?d=58208#p279638 forum script]).
* '''Maintain the key distribution'''. Every month or so it is a good idea to stop the mysql server and run these myisamchk commands.
#myisamchk -a -S /pathtomysql/data/moodledir/*.MYI
:'''Warning''': You must stop the mysql database process (mysqld) before running any myisamchk command. If you do not, you risk data loss.
* Reduce the number of '''temporary tables saved to disk'''. Check this with the created_tmp_disk_tables value. If this is relatively large (>5%) increase tmp_table_size until you see a reduction. Note that this will have an impact on RAM usage.

===PostgreSQL performance===

There are some good papers around on tuning PostgreSQL, and Moodle's case does not seem to be different to the general case.

The first thing to recognise is that if you really need to worry about tuning you should be using a separate machine for the database server. If you are not using a separate machine then the answers to many performance questions are substantially muddied by the memory requirements of the rest of the application.

You should probably '''enable autovacuum''', unless you know what you are doing. Many e-learning sites have predictable periods of low use, so disabling autovacuum and running a specific vacuum at those times can be a good option. Or perhaps leave autovacuum running but do a full vacuum weekly in a quiet period.

Set '''shared_buffers''' to something reasonable. For versions up to 8.1 my testing has shown that peak performance is almost always obtained with buffers < 10000, so if you are using such a version, and have more than 512M of RAM just set shared_buffers to 10,000 (8MB).

The buffer management had a big overhaul in 8.2 and "reasonable" is now a much larger number. I have not conducted performance tests with 8.2, but the recommendations from others are generally that you should now scale shared_buffers much more with memory and may continue to reap benefits even up to values like 100,000 (80MB). Consider using 1-2% of system RAM.

PostgreSQL will also assume that the operating system is caching its files, so setting '''effective_cache_size''' to a reasonable value is also a good idea. A reasonable value will usually be (total RAM - RAM in use by programs). If you are running Linux and leave the system running for a day or two you can look at 'free' and under the 'cached' column you will see what it currently is. Consider taking that number (which is kB) and dividing it by 10 (i.e. allow 20% for other programs cache needs and then divide by 8 to get pages). If you are not using a dedicated database server you will need to decrease that value to account for usage by other programs.

Some other useful parameters that can have positive effects, and the values I would typically set them to on a machine with 4G RAM, are:

work_mem = 10240

That's 10M of RAM to use instead of on-disk sorting and so forth. That can give a big speed increase, but it is per connection and 200 connections * 10M is 2G, so it can theoretically chew up a lot of RAM.

maintenance_work_mem = 163840

That's 160M of RAM which will be used by (e.g.) VACUUM, index rebuild, cluster and so forth. This should only be used periodically and should be freed when those processes exit, so I believe it is well worth while.

max_fsm_pages = 100000
max_fsm_relations = 5000

These are used to hold the free-space map, and if they are too small you will see performance degradation after the database has been operating for some time. The exact numbers to set can be gleaned from the output of VACUUM VERBOSE, which prints the required FSM pages at the end of it's run. The 5x increase seems to be useful for a Moodle installation, from experience.

wal_buffers = 64

These buffers are used for the write-ahead log, and there have been a number of reports on the PostgreSQL mailing lists of improvement from this level of increase.

This is a little out of date now (version 8.0) but still worth a read: http://www.powerpostgresql.com/Docs

And there is lots of good stuff here as well: http://www.varlena.com/GeneralBits/Tidbits/index.php

''Based on Andrew McMillan's post at [http://moodle.org/mod/forum/discuss.php?d=68558 Tuning PostgreSQL] forum thread.''

===Other database performance links===
* Consider using a '''distributed cacheing system''' like [http://en.wikipedia.org/wiki/Memcached memcached] but note that memcached does not have any security features so it should be used behind a firewall.
* Consider using PostgreSQL. See [[Arguments in favour of PostgreSQL]] and [http://moodle.org/mod/forum/discuss.php?d=49195 how to migrate from MySQL to PostgreSQL] (forum discussion).
* [[Increasing the database connection lifetime | Try increasing the database connection lifetime]]
* [http://dev.mysql.com/doc/refman/5.0/en/server-parameters.html General advice on tuning MySQL parameters] (advice from the MySQL manual)
* [http://www.mysqlperformanceblog.com/2007/11/01/innodb-performance-optimization-basics/ InnoDB performance optimization] taken from the [http://www.mysqlperformanceblog.com/ MySQL performance blog] site.

==Performance of different Moodle modules==

Moodle's activity modules, filters, and other plugins can be activated/deactivated. If necessary, you may wish to deactivate some features (such as chat) if not required - but this isn't necessary. Some notes on the performance of certain modules:

* The '''Chat''' module is [http://moodle.org/mod/forum/discuss.php?d=37979&parent=175079 said] to be a hog in terms of frequent HTTP requests to the main server. This can be reduced by setting the module to use ''Streamed'' updates, or, if you're using a Unix-based webserver, by running the chat in daemon mode. When using the Chat module use the configuration settings to tune for your expected load. Pay particular attention to the ''chat_old_ping'' and ''chat_refresh'' parameters as these can have greatest impact on server load.
* The '''Quiz''' module is known to stretch database performance. Try to optimise your database server by tuning. See [http://moodle.org/mod/forum/discuss.php?d=25616&parent=120770 for a brief report on performance for 55 students simultaneously using quizzes]
** See this Case Study for an extensive server stress test with 300 quiz users.[http://moodle.org/mod/forum/discuss.php?d=68579] And this accompanying report on network traffic and server loads. [http://elearning.sgu.ac.jp/doc/PT/]
* The Moodle '''Cron''' task is triggered by calling the script ''cron.php''. If this is called over HTTP (e.g. using wget or curl) it can take a large amount of memory on large installations. If it is called by directly invoking the php command (e.g. ''php -f /path/to/moodle/directory/admin/cron.php'') efficiency can be much improved.
* The '''Recent activities''' block is consuming to much resources if you have huge number of records <code>mdl_log</code>. this is being tested to optimize the SQL query.

==Moodle Image Optimization==

The base images delivered in the original Moodle distribution package provide unoptimized graphics, most of which can benefit from lossless recompression utilizing [http://optipng.sourceforge.net/ optipng] for PNGs, [http://www.lcdf.org/gifsicle/ gifsicle] for GIFs and [http://www.kokkonen.net/tjko/projects.html jpegoptim] for JPGs. Optimized graphics transfer faster and provide a faster perceived response for clients[http://www.websiteoptimization.com/speed/12/], especially distance learners. The following example will recursively optimize (without any loss of quality) all the graphics and image files included in a base Moodle installation directory on a server with the above commands installed and available.

<pre>
find /example/directory/moodle-1.9 -iname *.png -exec optipng -o7 {} \;
find /example/directory/moodle-1.9 -iname *.gif -exec gifsicle -O2 -b {} \;
find /example/directory/moodle-1.9 -iname *.jpg -exec jpegoptim -p {} \;
</pre>

Both [http://optipng.sourceforge.net/ optipng] and [http://www.lcdf.org/gifsicle/ gifsicle] are provided in the base repositories of most newer Linux distributions; [http://www.kokkonen.net/tjko/projects.html jpegoptim] must be downloaded and installed manually.

==See also==

*Using Moodle: [http://moodle.org/mod/forum/view.php?f=94 Hardware and Performance] forum

There have been a lot of discussions on moodle.org about performance, here are some of the more interesting and (potentially) useful ones:

* [http://moodle.org/mod/forum/discuss.php?d=83057 Performance woes!]
* [http://moodle.org/mod/forum/discuss.php?d=57028 Performance perspectives - a little script]
* [http://moodle.org/mod/forum/discuss.php?d=88927 Comments on planned server hardware]
* [http://moodle.org/mod/forum/discuss.php?d=102978#p461624 Moodle performance in a pil by Martin Langhoff]

[[es:Rendimiento]]
[[fr:Performance]]
[[ja:パフォーマンス]]
[[pl:Wydajnosc]]

error/auth ldap/ntlmsso iwamagicnotenabled

2011-10-05T07:25:11Z

Libertymoodle: /* Fix See Also */

See the [http://moodle.org/mod/forum/discuss.php?d=117343#p517037 Error ntlmsso_iwamagicnotenabled using NTLM SSO] discussion in the Using Moodle forum for a way to troubleshoot this error.

error/auth ldap/ntlmsso iwamagicnotenabled

2011-10-05T07:18:42Z

Libertymoodle: /* See also */

See the [http://moodle.org/mod/forum/discuss.php?d=117343#p517037 Error ntlmsso_iwamagicnotenabled using NTLM SSO] Using Moodle forum discussion for more information about this error.

NTLM authentication

2011-09-29T07:40:19Z

Libertymoodle: /* How to Turn Integrated Authentication on */

This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Site Administration >> Plugins >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation==

No installation needed. See Site Administration >> Plugins >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Windows Authentication
*On Apache - use one of the 3 methods outlined below
*On the client pc's, you might need to set the moodle server ip/moodle url as being in "local intranet" (From IE, tools -> options -> security -> local intranet)

It is important to note the following conditions must be satisfied to let NTLM SSO happens:
*you've arrived to the login page with one GET request
*you've ldap->ntlmsso_enabled
*you've ldap->ntlmsso_subnet
*you aren't logged
*the IP of the client is in ntlmsso_subnet

Thus it is needed to set the IP subnet.

If you have used previous versions of NTLM (from 1.8 and below) in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==How to Turn Integrated Authentication on==
The auth/ldap/ntlmsso_magic.php file MUST have NTLM/Integrated Authentication enabled on the server or the authentication will not work.

===IIS Configuration===
Open the IIS Management Console and navigate to the auth/ldap/ntlmsso_magic.php file.

====IIS 6.0====
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"

====IIS 7.x====
#After navigating to the 'auth/ldap' folder, switch to Content View
#right click on the file, choose "Switch to Features View"
#click on the Authentication icon on the right
#select 'Anonymous Authentication' and click the 'Disable' button
#select 'Windows Authentication' and click the 'Enable' button

*According to [http://moodle.org/mod/forum/discuss.php?d=145171#p634027 this post], if you are using IIS 7.5 (it comes with Windows Server 2008 R2), you have to select 'Windows Authentication' and click on 'Providers'. This shows a list of enabled providers (Negotiate and NTLM, by default). Change the order so that NTLM is at the top of the list.
*If 'Windows Authentication' is not available, then you need to install it as a separate authentication provider (in Control Panel).

===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba for Apache on Linux====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain.<br/> You'll need to type this account's password for the command to succeed.

: In Windows environments you could also try executing the command (as root):

# net join DOMAINNAME -S DCSERVER -U Administrator

: where DCSERVER is the Domain Controller server

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are going to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Stop and start the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core (and also in Redhat/Centos), keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138<br />
simply change the line to that was:
KeepAlive Off
to:
KeepAlive On
and restart apache (/etc/init.d/http restart)
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)
::-- Hi Dan! I have this working on Ubuntu 8.04 LTS in an RM CC4 Active Directory Domain. [[User:munk3h|Ian]] 16:31 15 December 2009 (GMT)

====Using the NTLM Auth Module for Apache on Linux====
The NTLM Auth module is a bit stale and even its authors suggest that you use the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]]

Get it from here
# get the Module from: http://modntlm.sourceforge.net/
# follow the instructions given there and inside the README that comes with the package.

I (Iñaki Arenaza) strongly recommend using the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]] over this module. It's better maintained, more robust and has more features.

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}:
* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 only, as 2.x already support Kerberos format out of the box) with the following code:

<pre>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

// HTTP __headers__ seem to be sent in ISO-8859-1 encoding
// (according to my reading of RFC-1945, RFC-2616 and RFC-2617 and
// my local tests), so we need to convert the REMOTE_USER value
// (i.e., what we got from the HTTP WWW-Authenticate header) into UTF-8
$textlib = textlib_get_instance();
$username = $textlib->convert($_SERVER['REMOTE_USER'], 'iso-8859-1', 'utf-8');

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ($pos = strpos($username, "@")) {
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</pre>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.

* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==

#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.
# NTLM seems to not work at all when BASIC authentication is enabled. (this was using the Kerberos method, other ways may work)
# If the account in your AD management console shows like "First Last", you better change the ldap settings parameter 'User Attribute' from its default of {blank} / 'cn' to 'sAMAccountName' as indicated in [http://moodle.org/mod/forum/discuss.php?d=132364#p682173 this post]. The reason is that the cn name generally looks like "First Last", once you done the ldap sync, the user name in moodle will be "first last", but IE passes the account of "domain\first.last" to moodle which does not exist in moodle.

== To get a domain name for Moodle working on IIS7.5 Windows 2008 R2 ==
Refer to http://support.microsoft.com/kb/896861. Key section listed below.
Click Start, click Run, type regedit, and then click OK.<br />
In Registry Editor, locate and then click the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0<br />
Right-click MSV1_0, point to New, and then click Multi-String Value.<br />
Type BackConnectionHostNames, and then press ENTER.<br />
Right-click BackConnectionHostNames, and then click Modify.<br />
In the Value data box, type the host name or the host names for the sites that are on the local computer, and then click OK.<br />
Quit Registry Editor, and then restart the IISAdmin service.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=186661 Moodle in a DMZ with NTLM] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

NTLM authentication

2011-09-29T07:18:42Z

Libertymoodle: /* New See also link */

This document describes how to set up '''NTLM/Windows Integrated Authentication''' in Moodle.

==Overview==
Integrated Windows Authentication uses the security features of Windows clients and servers. It does not prompt users for a user name and password. The current Windows user information on the client computer is supplied by the browser through a challenge/response authentication process with the Web server for the Moodle site.

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#You are familar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings.

If you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

::'''VERY IMPORTANT''': NTLM authentication depends on [[LDAP authentication]], and NTLM configuration is specified in the LDAP authentication settings page (Site Administration >> Plugins >> Authentication >> LDAP Server). So before trying to configure NTLM, make sure you have LDAP_authentication properly setup and working.

==Installation==

No installation needed. See Site Administration >> Plugins >> Authentication >> LDAP Server for the NTLM config options. You only have to

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*On IIS: turn on Windows Authentication
*On Apache - use one of the 3 methods outlined below
*On the client pc's, you might need to set the moodle server ip/moodle url as being in "local intranet" (From IE, tools -> options -> security -> local intranet)

It is important to note the following conditions must be satisfied to let NTLM SSO happens:
*you've arrived to the login page with one GET request
*you've ldap->ntlmsso_enabled
*you've ldap->ntlmsso_subnet
*you aren't logged
*the IP of the client is in ntlmsso_subnet

Thus it is needed to set the IP subnet.

If you have used previous versions of NTLM (from 1.8 and below) in your Moodle database you will need to make two further changes.

#The type of authentication held against each user now needs to be LDAP, as NTLM will not be recognised. To edit the fields open up a SQL query for your Moodle server and use the following query "update mdl_user set auth = 'ldap' where auth = 'ntlm' "
#If you had a previous .htaccess file in the auth/ntlm directory, you will need to move it to the auth/ldap directory. Regardless of whether it is in a .htaccess file of the httpd.conf, the <Files> line now needs to refer to ntlmsso_magic.php. If it is in the httpd.conf, the <Directory> will need to change too. This is covered later on for new installs, but is one of the fundamental changes that needs to be made for those upgrading.

==How to Turn Integrated Authentication on==
The File ntlmsso_magic.php MUST have NTLM/Integrated Authentication enabled at the server or the page will not work.

===IIS Configuration===
Open up IIS, and find the auth/ldap/ntlmsso_magic.php file,

====IIS 6.0====
#right click on the file, choose properties
#under the "file security" tab, click on the Authentication and Access control "edit" button
#untick "Enable Anonymous Access" and tick "Integrated Windows Authentication"

====IIS 7.x====
#After navigating to the 'auth/ldap' folder, switch to Content View
#right click on the file, choose "Switch to Features View"
#click on the Authentication icon on the right
#select 'Anonymous Authentication' and click the 'Disable' button
#select 'Windows Authentication' and click the 'Enable' button

*According to [http://moodle.org/mod/forum/discuss.php?d=145171#p634027 this post], if you are using IIS 7.5 (it comes with Windows Server 2008 R2), you have to select 'Windows Authentication' and click on 'Providers'. This shows a list of enabled providers (Negotiate and NTLM, by default). Change the order so that NTLM is at the top of the list.
*If 'Windows Authentication' is not available, then you need to install it as a separate authentication provider (in Control Panel).

===APACHE Configuration===
There are currently 3 possible methods for this:

====Using the NTLM part of Samba for Apache on Linux====

* Get the plugin here: http://samba.org/ftp/unpacked/lorikeet/mod_auth_ntlm_winbind/ . You need to download all the files from the link, but not the <code>contrib</code> and <code>debian</code> directories. Then follow the instructions given inside the <code>README</code> file. If you are using Debian/Ubuntu, you can follow these [[#Compiling_mod_auth_ntlm_winbind_on_Debian.2FUbuntu|compilation instructions]].
* Once you have compiled it, put it inside Apache's modules subdirectory (this location depends on a number of factors, like compiling Apache yourself, using different Linux distributions packages, an so on), and load and enable the module in Apache's configuration. For example, if your Apache modules are under <tt>/usr/lib/apache2/modules</tt>, you'll need something like this in your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>):

<IfModule !mod_auth_ntlm_winbind.c>
LoadModule auth_ntlm_winbind_module /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
</IfModule>

* Install the Samba <tt>winbind</tt> daemon package. This packages relies on Samba's configuration file to get some important settings (like the Windows domain name, uid and gid range mappings, and so on). In addition to that, you'll need to make your Linux/Unix machine part of the domain. Otherwise winbind won't be able to pull user and groups informationi from the domain controllers. You should read the Samba documentation to perform this step, but the most important part is having something like the following lines in your <code>smb.conf</code> file (in addition to what you already have there):

workgroup = DOMAINNAME
password server = *
security = domain
encrypt passwords = true
idmap uid = 10000-20000
idmap gid = 10000-20000

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

: where '''DOMAINNAME''' is the NetBIOS windows domain name, and '''Administrator''' an account with enough privileges to add new machines to the domain.<br/> You'll need to type this account's password for the command to succeed.

: In Windows environments you could also try executing the command (as root):

# net join DOMAINNAME -S DCSERVER -U Administrator

: where DCSERVER is the Domain Controller server

: Also, make sure you have disabled "Microsoft Network Server: digitally sign communications (always)" in your Domain Controllers Security Policy, unless you are using a version of Samba that can sign SMB packets.

* Restart the <tt>winbind</tt> service to apply the changes and test that it's running ok by executing:

$ wbinfo -u

: You should get the full list of Windows domain users. If you use '''<tt>-g</tt>''' instead, you'll get the domain groups list.

* Check that your <tt>winbind</tt> package installed the authentication helper command <tt>ntlm_auth</tt>, as we'll need it later. We'll assume the helper is located at <tt>/usr/bin/ntlm_auth</tt>. If yours is at a different location, make sure you adjust the path in the example below.

* Add something like this to your Apache configuration file (usually called <tt>apache2.conf</tt> or <tt>http2.conf</tt>). We'll assume that your Moodle <tt>$CFG->dirroot</tt> directory is located at <tt>/var/www/moodle</tt> in the example:
: '''For 1.9 or above use''':
<Directory "/var/www/moodle/auth/ldap/">
<Files ntlmsso_magic.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
: '''For 1.8 or below use''':
<Directory "/var/www/moodle/auth/ntlm/">
<Files oncampuslogin.php>
NTLMAuth on
AuthType NTLM
AuthName "Moodle NTLM Authentication"
NTLMAuthHelper "/usr/bin/ntlm_auth --helper-protocol=squid-2.5-ntlmssp"
NTLMBasicAuthoritative on
require valid-user
</Files>
</Directory>
* Check the permissions of the Winbind pipe directory (Ubuntu places it under <tt>/var/run/samba/winbindd_privileged</tt>, yours may be placed at a different location). Apache will need to be able to enter that directory, so we need to make sure it has the right permissions. So have a look at the permissions of that directory and note the name of the group assigned to it. The following example is from a Ubuntu 7.10 machine:

$ ls -ald /var/run/samba/winbindd_privileged
drwxr-x--- 2 root winbindd_priv 60 2007-11-17 16:18 /var/run/samba/winbindd_privileged/

:so we see the group is <tt>winbindd_priv</tt>.

* Instead of modifying the directory permissions (which could break other services that use winbind) we are going to make the Apache user (<tt>www-data</tt> in our example, but could be <tt>httpd</tt>, or <tt>nobody</tt>, etc.) is part of the appropiate group. Execute the following as root:

# adduser www-data winbindd_priv

: <tt>adduser</tt> is available in Debian and Ubuntu at least. If your distribution doesn't have <tt>adduser</tt>, you can edit <tt>/etc/group</tt> manually to achive the same effect.

* Stop and start the Apache service to apply the changes. Have a look at Apache's error log to see that everything is ok.

* Couple of gotchas - in Fedora Core (and also in Redhat/Centos), keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138<br />
simply change the line to that was:
KeepAlive Off
to:
KeepAlive On
and restart apache (/etc/init.d/http restart)
* Email Dan if you get this working - I'm keen to hear how people go using the samba winbind option!
::-- Hi Dan! I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)
::-- Hi Dan! I have this working on Ubuntu 8.04 LTS in an RM CC4 Active Directory Domain. [[User:munk3h|Ian]] 16:31 15 December 2009 (GMT)

====Using the NTLM Auth Module for Apache on Linux====
The NTLM Auth module is a bit stale and even its authors suggest that you use the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]]

Get it from here
# get the Module from: http://modntlm.sourceforge.net/
# follow the instructions given there and inside the README that comes with the package.

I (Iñaki Arenaza) strongly recommend using the [[#Using_the_NTLM_part_of_Samba_for_Apache_on_Linux|NTLM part of Samba with Apache on Linux]] over this module. It's better maintained, more robust and has more features.

====Using the mod_auth_sspi Module for Apache 2 on Windows====
NOTE: This setup is currently being used in a live production environment, and is therefore suitable for such use provided it is correctly configured and tested.

This is the recommended method for Apache 2 on Windows, however it will '''not''' work on Linux/UNIX systems.
It provides better stability and higher performance than other NTLM modules.

* Download the mod_auth_sspi Module from: http://sourceforge.net/projects/mod-auth-sspi/. At the moment of writing this (2007.09.30), the current version is mod_auth_sspi 1.0.4, which has two different ZIP files to download:

::* mod_auth_sspi-1.0.4-2.0.58.zip : Use this file if you are using Apache 2.0.x.
::* mod_auth_sspi-1.0.4-2.2.2.zip : Use this file if you are using Apache 2.2.x.

* Unzip the right file and copy mod_auth_sspi.so (it's inside '''bin''' subdirectory) to your Apache modules directory.
* Edit your Apache 2 configuration file (httpd.conf) to load the module.

<IfModule !mod_auth_sspi.c>
LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"

:: '''For 1.9 or above use''':
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>
:: '''For 1.8 or below use''':
<Directory "C:\moodle\auth\ntlm">
<Files oncampuslogin.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>
</Directory>

: '''Method 2''': The alternative method is to use a .htaccess file
:This method is recommended for servers that will host multiple Moodle instances. It allows additional Moodle instances to be configured without restarting apache, and also makes the solution a little more portable. We need to add a directive to the main httpd.conf to allow configuration of authentication within .htaccess files.
<Directory C:\moodle>
AllowOverride AuthConfig
</Directory>

:::Create a new text file named '.htaccess' in the directory 'C:\moodle\moodle\auth\ldap' and add the following directives:
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain mycollege.ac.uk
require valid-user
</Files>

:This enables the Moodle folder to be moved to any apache webserver that is configured to allow authentication configuration through .htaccess

For further help and discussion: http://moodle.org/mod/forum/discuss.php?d=56565

====Using the Kerberos Auth Module for Apache on Linux/UNIX (mod_auth_kerb)====
*Install and configure http://modauthkerb.sourceforge.net/
*Configuration of mod_auth_kerb in a Microsoft Windows Active Directory environment (AD 2003 and above) (http://grolmsnet.de/kerbtut/)

Environment details in this example:
#'''Active Directory Domain:''' EXAMPLE.AC.UK
#'''Active Directory Domain Controller:''' dc.example.ac.uk
#'''Linux/UNIX web server:''' moodle.example.ac.uk
#'''Active Directory user account for web server service principal:''' moodlekerb

Install kerberos on moodle.example.ac.uk and enter the following in krb5.conf (by default: /etc/krb5.conf)

<pre>
[libdefaults]
default_realm = EXAMPLE.AC.UK
[domain_realm]
example.ac.uk = EXAMPLE.AC.UK
[realms]
EXAMPLE.AC.UK = {
admin_server = dc.example.ac.uk
kdc = dc.example.ac.uk
}:
* Test kerberos
Issue the following command at the shell prompt:
<pre>
$> kinit user@EXAMPLE.AC.UK
</pre>

Where 'user' is an Active Directory account for which you know the password.

Next, issue the following:
<pre>$>klist</pre>
If all is OK it will list the Kerberos ticket you were granted from the domain controller (KDC)

* Create HTTP service principal for moodle.example.ac.uk
#Create the 'moodlekerb' '''user''' account in Active Directory (NOT a machine account) to map to the web server service principal (HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK)
NOTE: moodle.example.ac.uk MUST be the canonical DNS name of the server i.e. an A record (NOT a CNAME). Additionally a valid PTR (reverse DNS) record must exist and match the corresponding A record.

#Use the ktpass.exe utility to map the service principal and create a keytab file
Apache requires a keytab file, which is generated with ktpass.exe on the Windows Active Directory Domain Controller.
Shockingly, this component of Windows Server 2003 SP1 does not function correctly so one must obtain a hot fix: http://support.microsoft.com/kb/919557

Run the following command on the domain controller:
<pre>
C:\path\to\hotfix\ktpass.exe -princ HTTP/moodle.example.ac.uk@EXAMPLE.AC.UK -mapuser EXAMPLE\moodlekerb -crypto DES-CBC-MD5 +DesOnly +setPass +rndPass -ptype KRB5_NT_PRINCIPAL -out moodle.example.ac.uk.keytab
</pre>

Copy C:\path\to\hotfix\moodle.example.ac.uk.keytab to the moodle web server and remember the location (/etc/httpd/moodle.example.ac.uk.keytab or similar)

* Configure Apache / mod_auth_kerb
Edit the Apache configuration for the moodle host and add the following directives:
<pre>
<Directory /path/to/moodle/docs/auth/ldap/>
<Files ntlmsso_magic.php>
AuthName "Moodle"
AuthType Kerberos
KrbAuthRealms EXAMPLE.AC.UK
KrbServiceName HTTP
Krb5Keytab /etc/httpd/moodle.example.ac.uk.keytab
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
require valid-user
</Files>
</Directory>
</pre>

*Replace the '''ntlmsso_magic''' function in '''/auth/ldap/auth.php''' (1.9 only, as 2.x already support Kerberos format out of the box) with the following code:

<pre>
function ntlmsso_magic($sesskey) {
if (isset($_SERVER['REMOTE_USER']) && !empty($_SERVER['REMOTE_USER'])) {

// HTTP __headers__ seem to be sent in ISO-8859-1 encoding
// (according to my reading of RFC-1945, RFC-2616 and RFC-2617 and
// my local tests), so we need to convert the REMOTE_USER value
// (i.e., what we got from the HTTP WWW-Authenticate header) into UTF-8
$textlib = textlib_get_instance();
$username = $textlib->convert($_SERVER['REMOTE_USER'], 'iso-8859-1', 'utf-8');

/**
* begin kerberos - afhole@wortech.ac.uk 21-04-2009
*/
if ($pos = strpos($username, "@")) {
$username = substr($username, 0, $pos);
} else {
$username = substr(strrchr($username, '\\'), 1); //strip domain info
}
/**
* end kerberos
*/

$username = moodle_strtolower($username); //compatibility hack
set_cache_flag('auth/ldap/ntlmsess', $sesskey, $username, AUTH_NTLMTIMEOUT);
return true;
}
return false;
}
</pre>

The above code change will account for the fact that Kerberos presents the username to REMOTE_USER in the format user@DOMAIN, rather than NTLM's DOMAIN\user

==Configuring IP/Subnet Mask==
Subnet masks are based on binary patterns so need a bit of knowledge to understand. The best way to find out what IP/Subnet masks to use is to ask your Network Admin.

* The new way of specifiying subnets is even easier/more flexible than before 1.9. Just type them one after the other, separated by commas. You can use several syntaxes:
** Type the network-number/prefix-length combination. E.g. 192.168.1.0/24
** Type the network 'prefix', ending in a period character. E.g. 192.168.1.
** Type the network address range ('''this only works for the last address octect'''). E.g. 192.168.1.1-254
:All the three examples refer to the same subnetwork. So assuming you need to specify the following subnetworks:
::* 10.1.0/255.255.0.0
::* 10.2.0.0/255.255.0.0
::* 172.16.0.0/255.255.0.0
::* 192.168.100.0/255.255.255.240
:You can type:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.0/28
: or:
10.1.0.0/16, 10.2.0.0/16, 172.16.0.0/16, 192.168.100.240-255
:or even:
10.1., 10.2., 172.16., 192.168.100.0/28
:(the last one cannot be expressed as a network 'prefix' as the netmask does not fall on an octect boundary).

==Notes/Tips==

#If you are using Firefox, you will need to follow these steps:
:*Load Firefox and type about:config in the address box. The configuration settings page should be displayed.
:*In the Filter box, type the word "ntlm" to filter the NTLM strings. You should see three settings displayed.
:*Double-click on "network.automatic-ntlm-auth.trusted-uris".
:*In the box, enter the full URL of your Moodle server. For example <pre>http://moodle.mydomain.com, (the comma is important)</pre>
:*Close Firefox and restart.
# NTLM seems to not work at all when BASIC authentication is enabled. (this was using the Kerberos method, other ways may work)
# If the account in your AD management console shows like "First Last", you better change the ldap settings parameter 'User Attribute' from its default of {blank} / 'cn' to 'sAMAccountName' as indicated in [http://moodle.org/mod/forum/discuss.php?d=132364#p682173 this post]. The reason is that the cn name generally looks like "First Last", once you done the ldap sync, the user name in moodle will be "first last", but IE passes the account of "domain\first.last" to moodle which does not exist in moodle.

== To get a domain name for Moodle working on IIS7.5 Windows 2008 R2 ==
Refer to http://support.microsoft.com/kb/896861. Key section listed below.
Click Start, click Run, type regedit, and then click OK.<br />
In Registry Editor, locate and then click the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0<br />
Right-click MSV1_0, point to New, and then click Multi-String Value.<br />
Type BackConnectionHostNames, and then press ENTER.<br />
Right-click BackConnectionHostNames, and then click Modify.<br />
In the Value data box, type the host name or the host names for the sites that are on the local computer, and then click OK.<br />
Quit Registry Editor, and then restart the IISAdmin service.

==Compiling mod_auth_ntlm_winbind on Debian/Ubuntu==
You need to install the following packages (and all of their dependencies) by using aptitude, synaptic, etc.:

autoconf apache2-threaded-dev debian-builder

Once you have them installed, open up a text console, go to the directory where you downloaded the mod_auth_ntlm_winbind files an execute the following commands (as a normal user):

autoconf
./configure --with-apxs=/usr/bin/apxs2 --with-apache=/usr/sbin/apache2
make

That should compile it without errors. Then as a user that can run commands as root via sudo, execute the following command from the same directory:

sudo make install

This will create the final mod_auth_ntlm_winbind.so file and install it under /usr/lib/apache2/modules, with the rest of the Apache 2 modules (the size of the file and last modification time shown below may differ from your install):

ls -l /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so
-rw-r--r-- 1 root root 20921 2009-02-17 04:27 /usr/lib/apache2/modules/mod_auth_ntlm_winbind.so

==See also==
*[http://moodle.org/mod/forum/view.php?id=42 Using Moodle: User authentication] forum
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=45887 NTLM Authentication] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=80104 Merging AD NTLM SSO into auth/ldap] forum discussion
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=186661 Moodle in a DMZ with NTLM] forum discussion
*[http://moodle.org/mod/data/view.php?d=13&rid=314 Download the NTLM Authentication Module]

[[Category:Contributed code]]
[[Category:Authentication]]

[[fr:Authentification NTLM]]

Flat file

2011-08-25T17:34:20Z

Libertymoodle: /* See also */

Location: Flat file edit settings link in ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0

A flat file allows bulk enrolment management (enrol or unenrol) of existing users in existing course. The file is read one time by Moodle then erased. The file is located in the moodle file structure as a text file and [[Cron]] provides the timing when it is read.

==Options==
The site administrator should edit the settings for a flat file if it is enabled.
[[Image:Enrolment Flat file options.png|thumb|center|Options for flat file enrolment]]

Version 2.0

[[Image:EnrolSettngsFlatFile 2.0.png]]

:You should specify an absolute path for the upload file (eg /var/moodledata/enrolments.txt) where it can be read and modified by the webserver process.

You can choose to have an email sent to notify the Administrator, Teachers and/or students when the file has been processed.

==Flat file structure==
The file should be structured with the action, role, user id, and course ID number. Optionally a start time and end time can be added as additional fields.

The edit field link will give details on how to format the flat file on the Administration > Courses > Enrolments'' page.

[[Image:Enrolment Flat file data.png|thumb|center|Flat file instructions for fields and records]]

==See also==
*[[Upload users]]
*[[Bulk user actions]] how to download site user information (including userIDs)
Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=13289 How does flat file work?]
*[http://moodle.org/mod/forum/discuss.php?d=144997 Flat file enrolments - how is this typically used by organisations?]
*[http://moodle.org/mod/forum/discuss.php?d=45514 un-enroll a user from a course]
*[http://moodle.org/mod/forum/discuss.php?d=79250 flat file unenroll]

[[Category:Enrolment]]

[[fr:Inscription par fichier plat]]

Upload users

2011-07-16T15:44:50Z

Libertymoodle: /* See also link: Stanmdardise usernames */

{{Accounts}}
<p class="note">'''Please refer to [[TOC_with_notes#Accounts|these notes]] before editing this page.'''</p>
Location: ''Administration > Users > Accounts > Upload users''

[[Image:Upload users preview.png|thumb|Upload users preview in Moodle 1.9]]
Firstly, note that it is usually not necessary to import users in bulk - to keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the [[Internal enrolment|users create their own accounts]]. See [[Manage authentication]] for more information.

If you are sure you want to import multiple user accounts from a text file, then you need to format your text file as follows:

==Upload users file format==

* Each line contains fields '''separated''' by commas (or other delimiters) without quotes (") and no trailing delimiter
* The first line is special, and contains fieldnames defining the format for the rest of the file.

*'''Required fields''': In any order
:<p><code>username, firstname, lastname, email</code>
:Validity checks are performed for:
#<code>username</code> can only contain alphabetical '''lowercase''' letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
#<code>email</code> is in the form: ''name@example.com'' .</p>

*'''Password field''': "password" field is optional if "Create password if needed" setting is chosen (default).
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out (not working in v2.0.2?).

*'''Optional fields''': To provide values other than the default include one or more of these
:<p><code>institution, department, city, country, lang, auth, ajax, timezone, idnumber, icq, phone1, phone2, address, url, description, mailformat, maildisplay, htmleditor, autosubscribe, emailstop</code></p>

*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
:<p><code>profile_field_xxxxx</code></p>
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB: as at v2.0.2, the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".
:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.

*'''Special fields''': Used for changing of usernames or deleting of users
:<p><code>oldusername</code>, <code>deleted</code></p>

*'''Enrolment fields''': (Optional):
:<p><code>course1, type1, role1, group1, enrolperiod1, course2, type2, role2, group2, enrolperiod2</code> etc.
**<code>course</code> is the "shortname" if present the user will be enrolled in those courses.
** <code>type</code> refers to the role to be used for associated course enrolment. Value 1 is default course role, 2 is legacy Teacher role and 3 is legacy Non-editing Teacher.
** You can use role field instead to specify roles directly - use either role short name or id (numeric names of roles are not supported).
** Users may be also assigned to groups in course (group1 in course1, group2 in course2, etc.).
*** A group is identified by name or id (numeric group names are not supported).
** From Moodle 2.0, you can set the enrolment duration, in days, for each course (<code>enrolperiod1</code> for <code>course1</code>, <code>enrolperiod2</code> for <code>course2</code>, etc.).

Commas within a field must be encoded as &#44 - the script will decode these back to commas.

For Boolean fields, use <code>0</code> for false and <code>1</code> for true.

Turn email off: <code>emailstop</code> set to <CODE>1</CODE> if the email address should be disabled (default: email is enabled):

To prevent users from receiving a large number of emails from courses or forced subscription forums use the '''maildigest'''. The options for this field are 0 = No digest, 1 = Complete digest and 2 = Digest with just subjects.

Here is an example of a valid upload file:

<code>username, password, firstname, lastname, email, course1, group1<br />
jonest, verysecret, Tom, Jones, jonest@someplace.edu, math102, Section 1<br />
reznort, somesecret, Trent, Reznor, reznort@someplace.edu,math102, Section 3</code>

==Updating existing accounts==
By default Moodle creates new user accounts, and skips lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add new and update existing accounts''', and existing user account will be updated.

Include fieldname <code>oldusername</code> to updating existing accounts and change usernames. In the preview options, Set "Allow renames" to '''Yes''.
'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.

==After preview==
After the preprocessing, depending on the contents of the upload, the following may be available before final user creation
*Settings
** New user password
** Existing user details
** Existing user password
** Allow renames
** Allow deletes
** Prevent email addess duplicates
** Select for bulk operations

* Default values
** Authentication method: Manual account |no login | EMail-based self-registration
** Email display: Allow only other course members to see my email address | hide .. from everyone | allow anyone ...
** Email format Pretty HTML | plain text
** Email digest type: none|complete subjects
** Forum auto-subscribe: no |yes when I post
** When editing text: use HTML| standard web forms
** AJAX and Javascript: yes|no
** city/town
** country
** timezone
** Preferred language
** Description
** Web page
** ID number
** Institution
** Department
** Phone
** Mobile Phone
** Address

==After results ==
Users which were not added, will NOT be auto-enrolled in courses

----

Open another moodle browser and
* Site administration
** Courses
*** Add/edit courses; select the category, and the course
* Course administration
** Users
*** Enrolled Users
**** Enrol users and select the users flagged from other window

==Templates==

The default values are processed as templates in which the following codes are allowed:

* %l - will be replaced by the lastname
* %f - will be replaced by the firstname
* %u - will be replaced by the username
* %% - will be replaced by the %

Between the percent sign (%) and any code letter (l, f or u) the following modifiers are allowed:

* (-) minus sign - the information specified by the code letter will be converted to lowercase
* (+) plus sign - the information specified by the code letter will be converted to UPPERCASE
* (~) tilde sign - the information specified by the code letter will be converted to Title Case
* a decimal number - the information specified by the code letter will be truncated to that many characters

For example, if the firstname is John and the lastname is Doe, the following values will be obtained with the specified templates:

* %l%f = DoeJohn
* %l%1f = DoeJ
* %-l%+f = doeJOHN
* %-f_%-l = john_doe
* http://www.example.com/~%u/ = http://www.example.com/~jdoe/ (if the username is jdoe or %-1f%-l)

Template processing is done only on default values, and not on the values retrieved from the CSV file.

In order to create correct Moodle usernames, the username is always converted to lowercase. Moreover, if the "Allow extended characters in usernames" option in the Site policies page is off, characters different to letters, digits, dash (-) and dot (.) are removed. For example if the firstname is John Jr. and the lastname is Doe, the username %-f_%-l will produce john jr._doe when Allow extended characters in usernames is on, and johnjr.doe when off.

When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append to duplicate usernames produced by the template. For example, if the CSV file contains the users named John Doe, Jane Doe and Jenny Doe without explicit usernames, the default username is %-1f%-l and New username duplicate handling is set to Append counter, then the usernames produced will be jdoe, jdoe2 and jdoe3.

==Deleting accounts==

If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".

Deleting and uploading accounts could be done with a single CSV file. For example, the following file will add the user Tom Jones and delete the user reznort:

username, firstname, lastname, deleted
jonest, Tom, Jones, 0
reznort, , , 1

==Encoding==

In Moodle 1.8 the file must be UTF-8. In Moodle 1.9 onwards, the encoding may be selected from a large list, including ISO-8859-1.

==Hints==

===Spreadsheet===

If you use a spreadsheet program such as Excel to create your .csv file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding. A csv file is a simple text file (ASCII or Unicode) that can be used to upload user accounts.

Excel translates passwords that begin with - (minus) or + (plus) as zero. Even when saving as .csv and saying "Yes" to "Keep this format, and leave out any incompatible features." Check for this before uploading, as a zero halts the upload process.

If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), then remember to copy the cells with the formula and use special paste with values checked to make them into an acceptable data for a csv file.

===Country===
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands. Using "be" or "nl" as a country code will result in a database error.
:''Tip:'' If you are having trouble working out the two-letter code for a country, you can consult this Moodle source code file /moodle/lang/en_utf8/countries.php [http://cvs.moodle.org/moodle/lang/en_utf8/countries.php?view=markup&pathrev=MOODLE_19_STABLE or click here for a 1.9 STABLE list].
ISO Website: [http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm]

== See also ==
Moodle Docs:
*[[Flat file]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=58215 Making Email Optional]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish

[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:Groups]]

[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[zh:上传用户]]
[[ru:Загрузка пользователей]]

Development:Weekly Code Review

2011-04-28T11:52:14Z

Libertymoodle: /* See also link */

Moodle has a weekly process of code review in the stable branches to help improve the quality of stable packages and to help detect any regressions that may have occurred in stable code.

Here is the process for testers and developers:

==Every Tuesday==

===Don't check any new fixes into CVS===

HEAD is OK, but please avoid new fixes in all STABLE branches unless they are definitely definitely not going to cause new bugs ;-)

===Find bugs to test===

All developers and testers should be looking at:

Moodle 1.9 stable: [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10565 1.9.x Needs QA review]

(Make sure you can see the QA Assigned column)

Grab any bug that:

* Is from the last week
* You did not fix
* Does not have a QA assignee yet

and claim it by editing the bug to add your name as QA Assignee.

===Test the fix===

* Read the comments
* Look at the patch attached to the tracker
* Try the feature out to make sure it works as advertised
** Ensure you have debugging set to the DEBUG_DEVELOPER & look for new errors
** Test for potential regressions in other areas the fix may affect
* Post new comments (or talk on Moodle HQ) if you need clarification

===Deal with any problems===

* Post a comment on the bug with details (preferably including patch!)
* Reopen the bug
* If it looks like the original developer isn't seeing it, reassign to Eloy Lafuente for [[Development:Bug triage|triage]]
* If the fix is obvious and you have CVS access, fix it yourself

===Mark the fix as reviewed===

* When you are satisfied the bug is correctly fixed, simply change the status from Resolved to Closed
* If you committed any fix, let somebody else review it again - do not Close it yourself

==Every Wednesday==

* The download site will automatically tag the whole current stable codebase (e.g. MOODLE_19_WEEKLY) at 1:00 GMT on Wednesday morning and then build download packages

==See also==

*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=93474 Tuesday Code Reviews] forum discussion
*[[Development:Process]]

[[Category:Developer|Weekly Code Review]]
[[Category:Quality Assurance]]

Development talk:Git for developers

2011-04-04T08:29:32Z

Libertymoodle: /* Windows Git links */

== Installing Git on your computer ==
Is this really the place for childish comments about the Windows OS? Some people don't have the luxury of choice when it comes to choosing their operating systems in their work environments... --[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 06:02, 4 April 2011 (UTC)

:Luis, apologies for the comment which has now been removed. Unfortunately I don't know how to install Git on a Windows computer - it would be great if you could help. --[[User:Helen Foster|Helen Foster]] 07:48, 4 April 2011 (UTC)

:: ;-> I'm still not very familiar with Git so I haven't added anything to the docs. However, there do seem to be quite a few guides on the internet that explain Git on Windows, example: [http://nathanj.github.com/gitguide/tour.html An Illustrated Guide to Git on Windows] and [http://help.github.com/win-set-up-git/ Set Up Git (Windows)]. But we probably want something less "generic" and more Moodle specific. I'll make some notes once I've figured it all out... --[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 08:29, 4 April 2011 (UTC)

Development talk:Git for developers

2011-04-04T06:02:15Z

Libertymoodle: /* Signature */

Development talk:Git for developers

2011-04-04T06:00:08Z

Libertymoodle: /* Comments */

Development talk:Themes 2.0 adding a settings page

2011-03-29T14:12:33Z

Libertymoodle: /* Printing problem */

== Print Problem ==

The code segments on this page contain tags like <nowiki><div style="height:300px;overflow-y:scroll;"></nowiki> which adds scrollbars to the code blocks when viewed on the computer screen. This is fine on the screen as it reduces the size of the overall page, but when you print the document the content in those scrolling blocks (divs) is chopped off. Can we remove these divs or make them bigger so that the docs can be printed without data loss? --[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 14:12, 29 March 2011 (UTC)

Development talk:Themes 2.0 adding a settings page

2011-03-29T14:09:00Z

Libertymoodle: /* Printing problem */

The code segments on this page contain tags like <nowiki><div style="height:300px;overflow-y:scroll;"></nowiki> which adds scrollbars to the code blocks when viewed on the computer screen. No problem. But when you print the document the content in those scrolling blocks (divs) is chopped off. Can we remove these divs or make them bigger so that the docs can be printed without data loss?

Migration from MyISAM to InnoDB

2011-03-25T20:47:13Z

Libertymoodle: /* See also link */

{{stub}}
This page only applies to administrators using Moodle with a MySQL database.
It's about migrating [http://dev.mysql.com/doc/refman/5.1/en/storage-engines.html MySQL storage engine].

See [http://moodle.org/mod/forum/discuss.php?d=162871 Documentation for migration from MyISAM to InnoDB] for the current discussion which prompted the creation of this page. --[[User:Frank Ralf|Frank Ralf]] 11:41, 24 November 2010 (UTC)

== Difference between MyISAM and InnoDB ==
* read [http://tag1consulting.com/MySQL_Engines_MyISAM_vs_InnoDB]
* InnoDB is best for data integrity, not so good for searching large files, and uses up more CPU cycles and storage space than MyISAM equivalent
* InnoDB is much younger than MyISAM but is becoming increasingly attractive ... but because it is more complex, some utilities written for MyISAM like mysqlhotcopy may not work
* It is perfectly OK to select InnoDB for certain tables, and MyISAM for others (based on above criteria)

== MySQL Configuration ==
Before attempting to change the table type, you should:
* '''check InnoDB is enabled'''. Log in to MySQL and run the command [http://dev.mysql.com/doc/refman/5.1/en/show-engines.html SHOW ENGINES]. Make sure that support for InnoDB shows either "YES" or "DEFAULT".
* '''set innodb_file_per_table if required'''. [http://dev.mysql.com/doc/refman/5.1/en/innodb-multiple-tablespaces.html This setting] can be useful for large installations, but it only affects newly created tables and can't be applied retrospectively.

== Various Methods described in Moodle Forums (choose one)==
* run the innodb script as a webpage http://www.YOUR_MOODLE_SITE/admin/innodb.php (there might be timeout issues on large databases)
* use the CLI script in admin/cli/mysql_engine.php (requires access to shell, and the config.php must only have one moodle instance, but has no timeout issues)
* use PHPMyAdmin entering Structure view of a table and clicking Operations tab. Look for Storage Engine parameter. This is a tedious task due to the number of tables [http://moodle.org/mod/forum/discuss.php?d=162002]
* perform a database dump (e.g. mysqldump moodle_database > dump.SQL), use an editor or sed/perl/awk command to find/replace , replacing MyISAM with InnoDB. Finally, restore back in the server. (e.g. mysql < dump.SQL or equivalent)
* Follow the process detailed here - https://sites.google.com/site/moodlemayhem/tcea2011-moodle-server-setup-basics/moodleacidtrip

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=117913 New moodle.org] forum discussion

* [http://tag1consulting.com/MySQL_Engines_MyISAM_vs_InnoDB MySQL Engines: MyISAM vs. InnoDB] article by Tag1 Consulting

[[fr:Migration de MyISAM vers InnoDB]]

Development talk:Overview

2011-02-09T12:48:52Z

Libertymoodle: /* Comment */

Hm, I find the quality control section rather short. Seems to me that a link to a more thorough introduction about who the testers are, what do testers do exactly (what is the core process) and whom to contact to learn more would be appropriate? --[[User:Olli Savolainen|Olli Savolainen]] 07:30, 22 June 2009 (UTC)

It would be valuable to have information on this page about the concepts of "pulls" and "sprints" and all those new concepts. Or is this the wrong place? --[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 12:48, 9 February 2011 (UTC)

error/moodle/ddlexecuteerror

2011-02-07T08:20:34Z

Libertymoodle: /* Fix bullets */

{{Moodle_2.0}}

This error indicates that an error occurred when the Moodle installer tried to run a SQL statement that makes changes to the Moodle database structure. This error will normally only occur during a Moodle installation or upgrade.

To get more information about the error that caused this message you can enable the [[Debugging]] option in Moodle and then reattempt the Moodle installation. If the problem does occur again you will get a more detailed description of the problem. You can then use this information to report the problem to the Moodle developers via the Moodle [[Tracker]], which is the database for recording and managing Moodle bugs, improvements and feature requests.

==Technical Information==
This error message is constructed by the ''ddl_change_structure_exception'' class in \lib\ddllib.php. This is a function that is used to trap errors that occur during Moodle database changes.

The error can be triggered from one of two places in Moodle:

* The ''execute_sql()'' function in \lib\ddl\database_manager.php. This function is part of the database_manager class and is responsible for all database structure modifications.

* The ''query_end()'' function in \lib\dml\moodle_database.php which is called immediately after each database query. It is a "cleanup" routine that forms part of the the Moodle database interface.

==See also==
* [[Development:DDL functions]]
* Tracker issue: MDL-21874

error/moodle/ddlexecuteerror

2011-02-07T07:48:08Z

Libertymoodle: /* Description fix */

{{Moodle_2.0}}

This error indicates that an error occurred when the Moodle installer tried to run a SQL statement that makes changes to the Moodle database structure. This error will normally only occur during a Moodle installation or upgrade.

To get more information about the error that caused this message you can enable the [[Debugging]] option in Moodle and then reattempt the Moodle installation. If the problem does occur again you will get a more detailed description of the problem. You can then use this information to report the problem to the Moodle developers via the Moodle [[Tracker]], which is the database for recording and managing Moodle bugs, improvements and feature requests.

==Technical Information==
This error message is constructed by the ''ddl_change_structure_exception'' class in \lib\ddllib.php. This is a function that is used to trap errors that occur during Moodle database changes.

The error can be triggered from one of two places in Moodle:

- The ''execute_sql()'' function in \lib\ddl\database_manager.php. This function is part of the database_manager class and is responsible for all database structure modifications.

- The ''query_end()'' function in \lib\dml\moodle_database.php which is called immediately after each database query. It is a "cleanup" routine that forms part of the the Moodle database interface.

==See also==
* [[Development:DDL functions]]
* Tracker issue: MDL-21874

error/moodle/ddlexecuteerror

2011-02-07T07:44:43Z

Libertymoodle: /* Added error description */

{{Moodle_2.0}}

This error indicates that an error occurred when the Moodle installer tried to run a SQL statement that makes changes to the Moodle database structure. This error will normally only occur during a Moodle installation or upgrade.

To get more information about the error that caused this message you can enable the [[Debugging]] option in Moodle and then reattempt the Moodle installation. If the problem does occur again you will get a more detailed description of the problem. You can then use this information to report the problem to the Moodle developers via the Moodle [[Tracker]], which is the database for recording and managing Moodle bugs, improvements and feature requests.

==Technical Information==
This error message is constructed by the ''ddl_change_structure_exception'' class in \lib\ddllib.php. This is a PHP class used to trap errors that occur during database changes.

The error can be triggered from one of two places in Moodle:

- The ''execute_sql()'' function in \lib\ddl\database_manager.php. This function is part of the database_manager class and is responsible for all database structure modifications.

- The ''query_end()'' function in \lib\dml\moodle_database.php which is called immediately after each database query. It is a "cleanup" routine that forms part of the the Moodle database interface.

==See also==
* [[Development:DDL functions]]
* Tracker issue: MDL-21874

Course files

2011-01-31T14:38:33Z

Libertymoodle: /* See Also link */

{{Moodle 2.0}}This page explains the legacy "Course files" area in Moodle 2, and related topics.

It's useful for any teacher who wants to know how to add files to a Moodle 2.0 course (especially if you previously used Moodle 1.9 or earlier).

==Files in Moodle 1.9==

In versions of Moodle before 2.0 all the files uploaded into Moodle were stored in a physical directory on disk known as the "Course files" area.

This is where a teacher might upload files to be part of the course content, but this area also included everything students uploaded, such as assignments and forum attachments. These "activity files" were stored in a special folder called ''moddata'' in a certain structure that helped modules keep track of their own files.

===Typical Moodle 1.x workflows===

The course files area was accessed in two ways through the Moodle interface by teachers.

# Through the "Files" link in the Course Administration block, or
# When a file was required in other places, such as a resource, or attachment.

When publishing a file as a resource, say a PDF file, a teacher might:

# Upload it to their course files area along with all the other files they intend to use in the course
# Add a resource to the course
# Select the PDF from the course files

Students did not have direct access to read the course files area. All they could do was upload files from their desktop computer straight into activities.

===A less typical workflow===

# Use [[wikipedia:FTP|FTP]] to push files straight into the course files area
# Add resources to the course by selecting these files
# Update the resources later by updating the files directly via FTP

This meant expert users could update course content with files or HTML mini-sites without having to change anything in Moodle.

===Problems with the Moodle 1.x model===

* If the original file was deleted from course files area, or renamed, it would result in broken links everywhere where it was previously used
* Storing files on disk meant file names were restricted (eg file names in Japanese would break on some operating systems)
* All course files had to be readable by students (if they knew the URL) because Moodle had no way of telling what context you were viewing a file in (eg the same file might be in a HTML text in a forum and also in a resource). This meant that files stored in the course files area were not as secret as teachers thought they were.
* Files could not be reused in several courses - that had to be uploaded to each course files area
* Backups had to include ALL course files, just in case they were required, even if the backup only contained one activity
* Images and other media might look fine for teachers, but others would not see it (eg in course descriptions)
* When importing activities from one course to another, ALL course files were imported, as it was impossible to tell which files were needed

==Files in Moodle 2.0==

In Moodle 2.0 the files work a lot more like Web 2.0 systems, such as Facebook and Google Docs.

Each activity and each text has its own file area, and files are associated directly with the place it is used. For example, a file attached to a forum post is stored "with" the forum post, and becomes subject to exactly the same access restrictions.

The Files system is intimately connected with the Repository system, and a file picker which makes it easy to browse external and internal repositories for files, and then copy them into Moodle. Certain repositories also allow you to link directly to their media files. Repositories in general are the way of the future for content - most Web 2.0 systems are really repositories of data with various management interfaces.

A private files area is provided for each user to store a collection of files for their own use. This is useful for students as well as teachers, and makes it easy to re-use media across the Moodle site. Only you can access your own private files.

The course files area in Moodle 2.0 is [[wikipedia:Deprecation|deprecated]] and is not available by default due to the problems described above. When a site is upgraded from 1.9, all course files are migrated into new file areas and the old course files area is hidden from view.

Internally, files are stored in a "file pool" of blobs on disk with numbers for names. All the actual names and metadata are stored in a database.

===Typical Moodle 2.0 workflow===

# Edit a text or activity
# Use the filepicker to easily select the file from any local or remote repository

The file is then copied to Moodle and stored securely with the text or activity.

===More advanced Moodle 2.0 workflow===

# Edit a text or url resource
# Use the filepicker to easily select the file from any local or remote repository and select "link"

The file URL is then embedded into the text and when viewed, the media comes directly from the open repository.

===Why is it better?===

====Integrity====

If a forum post with attached files (eg images) is imported into another course, then the files move with it. Anyone in the new course will also see the files. This makes activities more portable and re-usable.

If two activities use the same file and one is deleted, then the other one is not affected.

There should be less problems with everything looking fine for teachers and not appearing for students.

====Security====

Access to files is governed the same way as the items that they attached to, which is what people expect. All files are now controlled by the settings in the Moodle interface, including roles and permissions.

====Re-usability====

It is now fast and easy to re-use files across Moodle. Using the file picker, a recently-used file may easily be chosen, or a file from any course a user has access to.

====Backups====

Backups of activities are small and accurate, because Moodle knows exactly what files to include. This is important for things like [[Community hubs]], where sharing of courses and parts of courses will become more common, and sharing every file in a course may be unacceptable.

====Internationalization====

There are no restrictions on file names - even files with names in Japanese may be used.

====Repositories====

The world is turning towards better management of files and less "dumping" of files into disks. There are many repository solutions out there that focus on better management of files, with versioning, workflow, metadata and other features.

===How to duplicate Moodle 1.x functionality in 2.0===

If you really want to mimic older workflows in 2.0 then there are some solutions, although none of them are exactly the same.

====FTP files into Moodle====

# One way to do this is via the [[admin/repository/filesystem|File system repository]]. This allows you to turn a directory on the server into a repository of files within the Moodle file picker. You can then use any server technology to access that directory from a desktop, such as FTP, [[wikipedia:Samba (software)|Samba]], [[wikipedia:AppleShare|Appleshare]] or [[wikipedia:WebDAV|WebDAV]].
# See the direct WebDAV plans below.

====Change a file once, have it update in many places====

# If you use an external repository that supports linking (such as Alfresco) then you get this behaviour for free. Files in the repository can not have exactly the same access control as Moodle, but they can implement their own access control, especially if you use some sort of single sign-on.
# If you enable the [[Legacy course files]] feature in Moodle 2.0 then you can also link directly to files there using the Course files repository in the file picker. Even HTML mini-sites work. The caveat is that it only works in places where you can '''link''' to files. So, for example, it won't work for a forum attachment or the 'resource' module. But it will work for the url module (new in 2.0) and any media embedded in HTML via the editor.

==Roadmap for future improvements==

Based on recent feedback, there are plans to improve the model in 2.0 with new features.

===File synchronization===

Instead of having to choose between linking to a course file or copying it to the current file area, we could add the option to 'Always use the latest version' of the file. This would re-copy the file to the destination whenever the source file changed. Initially this would be implemented just for the internal repositories but could also be used later for some external repositories as well (those not requiring the Moodle site to authenticate as the user).

This feature has the potential to maintain all the benefits of the 1.0 model without compromising the 2.0 model.

However this feature is complex to implement because:

* We need to cope with changing permissions in source and destination.
* We need to cope with cases like Assignment submissions (students shouldn't be able to update files after the due date, for example)
* We need some GUI solution to synchronize whole folders at once, such as a HTML mini-site.
* We need some in-GUI solution to report what the source file is for any given destination file.

===Linking ability to File system repository===

The File system repository currently does not allow linking to files. This is because the files are in a directory inside moodledata and are not exposed by any direct URL from the web.

To serve them to the web we'd have to have some script like ''/repository/filesystem/file.php'' to serve them as links, which would allow relative links like HTML mini-sites to work.

The problem with this is that we are back to the same issues as 1.9 course files (or even worse), with no access control on the files at all. Some people may not care about this, but the solution needs to make this very clear to users.

===WebDAV support for course files and user files===

This would effectively replace direct FTP access to the file system with WebDAV access to the "virtual" file system inside these file areas in Moodle. It would allow people to update files without going near the web GUI.

==See also==

* MDL-23306 META: Improve usability of new files structure
* [http://moodle.org/mod/forum/discuss.php?d=167471 Where is the Moodle 2.0 Course Backup Filearea] Using Moodle forum dicussion

[[Category:Teacher]] [[Category:Files]] [[fr:Fichiers de cours]]

Using the Microsoft SQL Server Driver for PHP

2011-01-28T09:13:06Z

Libertymoodle: /* Page formatting */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using the Microsoft SQL Server (MSSQL) RDBMS. The steps detailed below must be performed '''before''' installing Moodle itself.

First of all, the minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).

== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming that MSSQL is on the same server, otherwise
// use the actual name or IP address of your database server
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences,
// but NEVER leave this blank!
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, turn '''display_startup_errors''' to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Installing MSSQL for PHP

2011-01-26T15:01:58Z

Libertymoodle: /* Using the SQL Server 2005 Driver for PHP update */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using the SQL Server 2005 Driver for PHP from Microsoft on Windows ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] a new SQL Server 2005 Driver for PHP. This is a PHP extension that allows PHP scripts to read and write data on Microsoft SQL Server databases and it overcomes the problems with the native SQL Server extension that was previously bundled with PHP.

This Microsoft driver is the standard database layer for running Moodle 2 under Microsoft SQL Server databases. See [[Using the Microsoft SQL Server Driver for PHP]] the installation and configuration details.

This driver is only supported in Moodle 2.0 and up. You should use [https://docs.moodle.org/en/Installing_MSSQL_for_PHP#Using_FreeTDS_on_Windows FreeTDS] if you are installing an older version of Moodle.

See MDL-16497 and MDL-15093 for more background information.

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();

{| class="nicetable"
|-
! MSSQL Support
! enabled
|-
| Library version
| FreeTDS
|}

Once FreeTDS is correctly installed, don not forget to set it up following explanations in https://docs.moodle.org/en/FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Installing MSSQL for PHP

2011-01-26T14:54:08Z

Libertymoodle: /* MS SQL Server Driver update */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using the SQL Server 2005 Driver for PHP from Microsoft on Windows ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] a new SQL Server 2005 Driver for PHP. This is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts and it overcomes the problems with the native SQL Server extension that was previously included with PHP.

This driver is the standard database layer for running Moodle 2 under Microsoft SQL Server databases. See [[Using the Microsoft SQL Server Driver for PHP]] the installation and configuration details.

This driver is only supported in Moodle 2.0 and up. You should use FreeTDS if you are installing an older version of Moodle.

See MDL-16497 and MDL-15093 for more details.

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();

{| class="nicetable"
|-
! MSSQL Support
! enabled
|-
| Library version
| FreeTDS
|}

Once FreeTDS is correctly installed, don not forget to set it up following explanations in https://docs.moodle.org/en/FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Installing MSSQL for PHP

2011-01-26T13:51:22Z

Libertymoodle: /* Using the SQL Server 2005 Driver for PHP from Microsoft */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();

{| class="nicetable"
|-
! MSSQL Support
! enabled
|-
| Library version
| FreeTDS
|}

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] a new SQL Server 2005 Driver for PHP. This is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts and it overcomes the problems with the native SQL Server extension that was previously included with PHP.

This driver is the standard database layer for running Moodle 2 under Microsoft SQL Server databases. See [[Using the Microsoft SQL Server Driver for PHP]] the installation and configuration details.

This driver is only supported in Moodle 2.0 and up. You should use FreeTDS if you are installing an older version of Moodle.

==See also==
MDL-16497

MDL-15093

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

* [[Category:FAQ]]
* [[Category:Installation]]
* [[Category:Developer]]
* [[Category:XMLDB]]
* [[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T14:21:21Z

Libertymoodle: /* Typos */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using the Microsoft SQL Server (MSSQL) RDBMS. The steps detailed below must be performed '''before''' installing Moodle itself.

First of all, the minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).

== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, turn '''display_startup_errors''' to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T14:03:14Z

Libertymoodle: /* Typos */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using Microsoft SQL Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).
== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''
*MSSQL is usually installed with port 1433 as the default.

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, turn '''display_startup_errors''' to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T13:58:59Z

Libertymoodle: /* Typos */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using Microsoft SQL Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).
== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''
*MSSQL is usually installed with port 1433 as the default.

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T13:55:16Z

Libertymoodle: /* Typos */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using Microsoft SQL Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).
== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''
*MSSQL is usually installed with port 1433 as the default.

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]

extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]

extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T13:51:12Z

Libertymoodle: /* SQL Server driver instructions from Microsoft */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using Microsoft SQL Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).
== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''
*MSSQL is usually installed with port 1433 as the default.

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Using the Microsoft SQL Server Driver for PHP

2010-12-01T13:50:53Z

Libertymoodle: /* SQL Server driver instructions from Microsoft */

{{Moodle 2.0}}
== Using the SQL Server Driver for PHP from Microsoft ==

=1=
==2==
===3===
====4====

== Introduction ==
This short manual is for running Moodle 2.0 (and upwards) using Microsoft SQL Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

First of all, minimum required version of MSSQL has been stabilized to MSSQL 2005 (v.9).
== Installation overview ==
1. Install Microsoft SQL Server including SQL Server Management Studio. ([http://www.microsoft.com/sql/editions/express/default.mspx A free version, SQL Server Express Edition] is available for testing.)
:Make sure to choose mixed authentication (Windows and local accounts) to keep things simpler later. Define the "sa" account password when requested (it's the default System Administrator account which has full access to all databases by default).

2. Configure Windows for MSSQL.
:By default, MSSQL listens to port 1433 for incoming TCP/IP connections and this port needs to be opened in the firewall. This is explicitly configured in the firewall installed (either Windows Firewall in the Control Panel or the configuration interface for other firewalls). If the port was changed when MSSQL was installed, then specify the correct port number to open in the firewall.
:Confirm the TCP/IP protocol is enabled in: '''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''
*MSSQL is usually installed with port 1433 as the default.

3. Create and configure a new database.
:Open "SQL Server Management Studio" and create a new empty database.
*Execute the following command to enable Row Versioning:

<code>
USE MASTER
GO
ALTER DATABASE <your-database-name> SET READ_COMMITTED_SNAPSHOT ON
GO
</code>

4. Install PHP and a web server.
*PHP can be downloaded from [http://www.php.net/downloads.php www.php.net]
*If IIS is used as the web server, IIS 7.0 or later is recommended with [http://www.iis.net/download FastCGI and WinCache].

5. Install the SQL Server Driver for PHP.
:On the web server, install [http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=ccdf728b-1ea0-48a8-a84a-5052214caad9 SQL Server Driver for PHP] including all the pre-requisites listed on the download page. Note: it is critical to install the SQL Server Native Access Client version documented on the download page of the SQL Server Driver for PHP.
:Configure PHP to use the appropriate SQLSRV driver. In php.ini, set the following:

For PHP 5.2.4 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_52_nts_vc9.dll
</code>

For PHP 5.3.2 (or later)

<code>
[PHP_SQLSRV]
extension=php_sqlsrv_53_nts_vc9.dll
</code>

The Microsoft documentation for the SQL Server Driver for PHP is available at: http://msdn.microsoft.com/en-us/library/ee229548(v=SQL.10).aspx

6. Install and configure Moodle.
:Continue with the [[Installing Moodle|standard Moodle installation]].

7. The Moodle '''config.php''' should include lines like these:
<code php>
$CFG->dbtype = 'sqlsrv'; // Required
$CFG->dbhost = 'localhost'; // Assuming MSSQL is on the same server, otherwise use an IP address
$CFG->dbname = 'moodle'; // The name of the newly created Moodle database
$CFG->dbuser = 'yourusername'; // Usually the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = true;
$CFG->prefix = 'mdl_'; // The prefix can be changed per individual preferences, but NEVER leave this blank.
</code>

:If the config.php file doesn't exist, it will be generated as normal from the Moodle installer. Alternatively, use the config-dist.php file that comes with the Moodle package to create a custom config.php file.

8. Restart or start your web server.
:If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in the /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

9. Test the database connection.
:Try this PHP script, just add a text file called test.php from the example below and change ('localhost', 'db_user', 'db_password') to align with the config.php settings, and load from local host (http://localhost/test.php).

<code php>
<?php
$link = sqlsrv_connect($this->dbhost, array('UID' => 'db_user', 'PWD' => 'db_password'));
if($link === FALSE) {
echo 'Could not connect';
die('Could not connect: ' . sqlsrv_errors(SQLSRV_ERR_ALL));
}
echo 'Successful connection';
sqlsrv_close($link);
?>
</code>

10. Complete the rest of the Moodle installation as usual.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

[[Category:FAQ]]
[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Backup and restore FAQ

2010-11-28T12:08:59Z

Libertymoodle: /* Why are some courses being skipped update */

==How do I backup a course?==

See [[Course backup]] and [[Automated course backup]].

==How do I restore a course?==

See [[Restore]].

==How do I backup my site?==

See [[Site backup]].

==What is new in backup and restore in Moodle 2.0?==

See [[Backup 2.0]].

==Backup stops at Zipping backup==
Moodle 1.9 and lower use a PHP library to zip files that isn't very efficient and struggles to zip/unzip large files. You can use an external Zip binary to use a different process to handle your files - you can set this in ''Admin > Server > System Paths'' Moodle 2.0 uses new PHP zip functions so that specifying an external Zip binary isn't necessary see [[System_paths#Path_to_zip]] for help configuring an external zip binary.

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.
For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==The process ends with: "moodle xml not found at root level of zip file". What can I do?==
If you are restoring from a zip file backup make sure the moodle.xml file is at the root level. To ensure this:
#Unzip the backup file of the course (example: mycourse.zip)
#Once the file is unzipped, open the folder (example: mycourse).
#Select the folders within the mycourse folder AND the moodle.xml file and create a zip of those item (example: mycourse_new.zip)
#Upload the new zip file (example: mycourse_new.zip) and restore from that.

If the backup file is guaranteed to be correct, check paths to external files (zip, unzip). Incorrect settings also lead to this error message (see the Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=140355 moodle.xml not found in root...] and MDL-14812).

==The process ends with: "An error occurred while copying the zip file..."==

This problem is most likely caused by a permissions issue in the destination directory. Backup files are copied to "XXX/backupdata" under your dataroot directory (where XXX is the id of the course being backed up).

On Windows systems, if you have configured Moodle to use an external zip program then the IIS IUSR_computername user needs to have Execute access to cmd.exe so that it can run the zip program. See the Note in [https://docs.moodle.org/en/System_paths#Path_to_zip Path to zip] for more details.

The problem could also be caused by a disk being full, though this is far less likely.

To obtain precise information about what's happening, you can enable debug messages in ''Administration > Server > [[Debugging]]'' (select the maximum level - DEVELOPER) and/or check the web server error logs.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [http://repository.atlassian.com/atlassian-xml-cleaner/jars/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking (generally internal zip libraries, try to switch to external executables instead).
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==How can I restore pre 1.6 non-ISO-8859-1 backups to Moodle 1.6 (Unicode)?==

Any backup files with contents which are not 100% ISO-8859-1 will be a problem to restore to Moodle 1.6 (and upwards) running under Unicode. Instead, please try the following:

# Make a clean install of Moodle 1.5.x (the latest version available)
# Restore all your courses there (they should work if they were working originally)
# Upgrade your site to Moodle 1.6 and run the UTF-8 migration script
# Backup your courses again

This will produce a new set of backup files that will be 100% UTF-8 and you will be able to use them with Moodle 1.6 without any problems.

<span id="broken_html"></span>
==Restoring a course results in broken HTML tags. What can I do?==

'''Summary:''' Upgrade your libxml2 and PHP and you should be fine. It has been confirmed that the recent versions of libxml2 (2.7.3) and PHP (5.2.10) no longer have this problem.

'''Background:''' (may be obsoleted) This problem is due to a [http://bugs.php.net/bug.php?id=45996 PHP bug in libxml2 2.7.1] (the same bug reported with version 2.7.2 and 2.7.3). All HTML entities, such as >, < and " are removed when a course is restored.

To resolve the problem, you should use a different version of libxml2 such as 2.7.0 or 2.6.32 or compile PHP against libexpat instead of libxml2 or finally use PHP version >= 5.2.9 that solves this compatibility issue over the newer libxml2.

At Gentoo servers, you can use

echo ">dev-libs/libxml2-2.6.32" >> /etc/portage/package.mask

'''Update:''' This was fixed for libxml2 version 2.7.3 in PHP snapshot on 11/01/2009. You can use the following patch:

--- php-5.2.8/ext/xml/compat.c 2008/12/31 11:12:38 1.52
+++ php-5.2.8/ext/xml/compat.c 2009/01/11 12:00:30 1.53
@@ -482,6 +482,10 @@
parser->parser->charset = XML_CHAR_ENCODING_NONE;
#endif

+#if LIBXML_VERSION >= 20703
+ xmlCtxtUseOptions(parser->parser, XML_PARSE_OLDSAX);
+#endif
+
parser->parser->replaceEntities = 1;
parser->parser->wellFormed = 0;
if (sep != NULL) {

See the discussion [http://moodle.org/mod/forum/discuss.php?d=111321 Restoring makes webpages and labels in code] for further information.

==Why are some courses being skipped?==

From 1.6 onwards, course backups automatically skip courses which are unavailable to students and have not been changed in the last month.

The [http://moodle.org/mod/forum/discuss.php?d=80367#p714733 Hide courses excluded from automatic backup] discussion in the Using Moodle forum describes a way that you can disable or override this thirty day check. This could be useful if, for example, you wanted to change the period from thirty days to six months.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==How can I improve restore robustness and execution times?==

{{Moodle 1.9}}To improve restore robustness and execution times, particularly for medium to large course backups, try enabling the setting ''experimentalsplitrestore'' in ''Administration > Miscellaneous > [[Experimental]]''. (This setting is available in Moodle 1.9.5 onwards.)

MDL-18468 contains information about this Experimental Split Restore functionality and the improvements to course restore robustness and execution times that it introduced, particularly for medium to large course backups. It also explains why this is an 'Experimental' feature in Moodle 1.9.

==How can I backup and restore a course from a 1.9 site to a 2.0 site?==

The backup and restore process has been completely rewritten for Moodle 2.0. It is not currently possible to backup a course on a 1.9 site and restore it to a 2.0 site, however the functionality will be available in a forthcoming 2.0.x release (after the release of 2.0).

In the meantime, a workaround is to upgrade the 1.9 site to 2.0. PLEASE NOTE that Moodle 2 has yet to be released. There is a reason that it is yet to be released. For testing purposes, one could clone one's 1.9.x Moodle (leaving your production Moodle at 1.9.x) and then upgrade your clone to Moodle 2.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

[[Image:Moodle 2.0 Restore breaks.png|thumb|Error message in Moodle 2.0]]

This message is displayed when:

# Your target site has one xxxx user (xxxx being the username)
# The backup being restored also has one xxxx user
# After various comparisons, Moodle has detected that the xxxx user in 1. and the xxxx user in 2. aren't the same user.

If 1, 2 and 3 above happens, restore stops before performing any action as far as restoring that user will end associating "things" (create activities, posts, attempts... whatever...) to the xxxx user in the target site, when those "things" weren't performed by the same user at all.

Those checks and behaviour were introduced in Moodle 1.9.x and continue being valid under 2.0. Usually the xxxx user in the messages is the "admin" user (that exists in practically all Moodle installations).

There are two possible solutions to make both xxxx users in 1 and 2 to match (and avoid the conflict):

a) Modify the backup's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match with the ones in target site.<br />
b) Modify the '''target site''' and set the user ''email'' or ''firstaccess'' fields to match with the ones in backup's user.xml file.

Method a) is recommended so the restore process will match both xxxx users and every "thing" in the backup file belonging to xxxx will be associated to the already existing xxxx user in the target site.

== See also ==

*Using Moodle [http://moodle.org/mod/forum/view.php?f=128 Backup and Restore forum]
*[http://www.databasejournal.com/features/mysql/article.php/10897_3300511_2 databasejournal.com article on repairing database corruption in MySQL]

Moodle Docs:
* [[Site backup]]
* [[Moodle migration]]
* [[Beginning Administration FAQ]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=66708 Scheduled backup fails] including possible solution to "An error occurred while copying files".
*[http://moodle.org/mod/forum/discuss.php?d=99338 Restore stops]
*[http://moodle.org/mod/forum/discuss.php?d=125663 Major Backup and Restore Problem in 1.9.5] with ideas for solving "Course ID was incorrect (can't find it)" problem
*[http://moodle.org/mod/forum/discuss.php?d=137203 Restore does not continue]
*[http://moodle.org/mod/forum/discuss.php?d=142720 Trying to restore user 'admin' from backup file will cause conflict]

[[Category:FAQ]]
[[Category:Backup]]

[[es:FAQ Backup]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]

Development:Themes 2.0 creating your first theme

2010-11-02T16:12:51Z

Libertymoodle: /* Using images within CSS - changed DIV height to allow for printing. Still not perfect though */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
<div style="height:1780px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
'print' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>false),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>
</div>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<div style="height:1850px;overflow:auto;">
<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>
</div>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Development:Themes 2.0 creating your first theme

2010-11-02T16:05:32Z

Libertymoodle: /* The page footer - changed DIV height to allow printing of this doc */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
<div style="height:1780px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
'print' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>false),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>
</div>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<div style="height:1850px;overflow:auto;">
<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>
</div>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:400px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Development:Themes 2.0 creating your first theme

2010-11-02T15:55:33Z

Libertymoodle: /* Configuring our theme - increased DIV height to allow printing */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
<div style="height:1780px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
'print' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>false),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>
</div>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<div style="height:400px;overflow:auto;">
<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>
</div>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:400px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Development talk:Themes 2.0 creating your first theme

2010-11-02T15:55:00Z

Libertymoodle: /* Configuring Our Theme DIV height for printing */

Wow! Is the code for this theme available in a file, say in Modules and Plugins? Or did I miss it in my quick look. I can see my next project at work. --[[User:chris collman|chris collman]] 12:07, 6 April 2010 (UTC)

Hi Chris, the code in this tutorial isn't available anywhere the reason being that it is entirely based on the base theme :) check out ''theme/base/*'' you'll notice that what is in there is very close to the code I wrote for this tutorial. --[[User:Sam Hemelryk|Sam Hemelryk]] 01:33, 7 April 2010 (UTC)
::Hi Sam, I did not look, why get confused by reality and numb about :) I sort of got here by creating a 1.9.8 localhost that I could do screenshots for [[Standard themes]] and then tried my first complete install package of 2.0 in 3 months. My primary goal is to revamp the 'navigation' and organization of Category:Themes pages, your instructions are going to help me. Thanks for all your time and efforts. --[[User:chris collman|chris collman]] 11:26, 7 April 2010 (UTC)

Good crisp documentation!! Thank you Sam for this :) You ve made our lives easier with 2.0 themes!! ;)

Cheers!! --[[User:Navin Dutta|Navin Dutta]] 03:12, 13 April 2010 (UTC)

==Question about instruction==
Sam, your instructions say there will only be one layout php file called standard.php. What is the general.php file pointer doing in config.php under base? If I understand things, it should be pointed to the theme base (which has a general.php) or the file should be called standard.php. Is that correct?

It is snowing, so I thought I would see if I could follow your instructions and do something like standardlogo in 1.9 for fun. No doubt will crash and burn with this part time project over the next 2 years :) Thanks --[[User:chris collman|chris collman]] 13:12, 16 April 2010 (UTC)

== Broken :-( ==

Hello,

Thanks for the tutorial, but with - Moodle 2.0 Preview 2 (Build: 20100531) - I get the error 'Coding error detected, it must be fixed by a programmer: Trying to reference an unknown block region side-post' when trying to select the theme for modern browsers.

Update: I've made the changes required to solve the problem after reading: http://moodle.org/mod/forum/discuss.php?d=150190

Cheers,

Gareth

== Layouts ==

The need for the layout definitions is mentioned but not what they or what they do. This either needs explained or a link to where it is explained. It certainly isn't obvious --[[User:Howard Miller|Howard Miller]] 17:18, 12 July 2010 (UTC)

== Is this what??? ==

Sorry guys, I think this is confusing Please understand that I am not that technically literate so I need things said a lot clearer:

config.php
All of our settings will go here.
/style/
This directory will contain all of our stylesheets.
/style/excitement.css
All of our css will go in here.
/pix/
Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
/layout/
Our layout files will end up in this directory.
/layout/standard.php
This will be our one basic layout file.

There is a clear difference between a file and a directory - but the manner in which the above example is set up does not appear to make that distinction. Could it not be better put like:

Create the theme directory/folder, which we are calling "excitement". Into that directory/folder we create a file:
config.php
All of our settings will go here.
Then we create the directories/folders
/style/
This directory/folder will contain all of our stylesheets.
/pix/
Into this directory/folder we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
/layout/
Our layout files will end up in this directory/folder.

Into the style directory/folder we create a file:
excitement.css
Where we place All of our css rules.
And in the layout directory/folder we create a file:
standard.php
This will be our one basic layout file.

For me, not being that smart, this is a far more easily understood structure than has been shown.

== Configuring Our Theme ==
The DIV that contains the config.php code had a vertical scrollbar. This is because the DIV around the code had a height of 400. This is fine when you are reading this document on the computer, but when you print it a large part of the php ($THEME->layouts = array) is chopped off. I increased the DIV height to 1780 and it solves the printing problem. Is this ok?

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 15:54, 2 November 2010 (UTC)

LDAP authentication

2010-10-20T14:03:42Z

Libertymoodle: /* Using multiple LDAP Servers link */

{{Moodle 1.9}}
Location: Settings link in ''Administration > Users > [[Authentication]] > LDAP Server''

This document describes how to set up Lightweight Directory Access Protocol (LDAP) authentication in Moodle. We cover the basic, advanced and some trouble shooting sections to assist the user in the installation and administrating LDAP in Moodle.
==Table of Contents==
__TOC__
==Basic Scenario==
The simple and straightforward approach for most installations.

===Assumptions===

# Your Moodle site is located at '''http://your.moodle.site/'''
# You have configured your PHP installation with the LDAP extension. It is loaded and activated, and it shows when you go to '''http://your.moodle.site/admin/phpinfo.php''' (logged in as user 'admin').
# Your LDAP server has '''192.168.1.100''' as its IP address.
# You are not using LDAP with SSL (also known as LDAPS) in your settings. This might prevent certain operations from working (e.g., you cannot update data if you are using MS Active Directory -- MS-AD from here on --), but should be OK if you just want to authenticate your users.
# You don't want your users to change their passwords the first time they log in into Moodle.
# You are using a single domain as the source of your authentication data in case you are using MS-AD (more on this in the Appendices).
# You are using a top level distinguished name (DN) of '''dc=my,dc=organization,dc=domain''' as the root of your LDAP tree.
# You have a non-privileged LDAP user account you will use to bind to the LDAP server. This is not necessary with certain LDAP servers, but MS-AD requires this and it won't hurt if you use it even if your LDAP server doesn't need it. Make sure '''this account and its password don't expire''', and make this password as strong as possible. Remember you only need to type this password once, when configuring Moodle, so don't be afraid of making it as hard to guess as possible. Let's say this user account has a DN of '''cn=ldap-user,dc=my,dc=organization,dc=domain''', and password '''hardtoguesspassword'''.
# All of your Moodle users are in an organizational unit (OU) called '''moodleusers''', which is right under your LDAP root. That OU has a DN of '''ou=moodleusers,dc=my,dc=organization,dc=domain'''.
# You '''don't''' want your LDAP users' passwords to be stored in Moodle at all.

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Configuring Moodle authentication===

Log in as an admin user and go to Administration >> Users >> Authentication >> Manage authentication. In the table that appears, enable the "LDAP Server" authentication option (click on the closed eye to make it open) and then click on the associated 'Settings' link. You will get a page similar to this one:

[[Image:auth_ldap_config_screenshot.jpg|center]]

Now, you just have to fill in the values. Let's go step by step.

[[LDAP_authentication#Table of Contents|Table of Contents]]

====LDAP Server Settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Host URL
| As the IP of your LDAP server is 192.168.1.100, type "'''ldap://192.168.1.100'''" (without the quotes), or just "'''192.168.1.100'''" (some people have trouble connecting with the first syntax, specially on MS Windows servers).
|-
| Version
| Unless you are using a really old LDAP server, '''version 3''' is the one you should choose.
|-
| LDAP Encoding
| Specify encoding used by LDAP server. Most probably utf-8.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Bind settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Hide passwords
| As you '''don't''' want to store the users's password in Moodle's database, choose '''Yes''' here.
|-
| Distinguished Name
| This is the distinguished name of the bind user defined above. Just type "'''cn=ldap-user,dc=my,dc=organization,dc=domain'''" (without the quotes).
|-
| Password
| This is the bind user password defined above. Type "'''hardtoguesspassword'''" (without the quotes).
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====User lookup settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| User type
| Choose:
* '''Novel Edirectory''' if your LDAP server is running Novell's eDdirectory.
* '''posixAccount (rfc2307)''' if your LDAP server is running a RFC-2307 compatible LDAP server (choose this is your server is running OpenLDAP, including Mac OS X server).
* '''posixAccount (rfc2307bis)''' if your LDAP server is running a RFC-2307bis compatible LDAP server.
* '''sambaSamAccount (v.3.0.7)''' if your LDAP server is running with SAMBA's 3.x LDAP schema extension and you want to use it.
* '''MS ActiveDirectory''' if your LDAP server is running Microsoft's Active Directory (MS-AD)
|-
| Contexts
| The DN of the context (container) where all of your Moodle users are found. Type '''ou=moodleusers,dc=my,dc=organization,dc=domain''' here.

On a Mac OS X Server, this is usually '''cn=users,dc=my,dc=organization,dc=domain'''.
|-
| Search subcontexts
| If you have any sub organizational units (subcontexts) hanging from '''ou=moodleusers,dc=my,dc=organization,dc=domain''' and you want Moodle to search there too, set this to '''yes'''. Otherwise, set this to '''no'''.
|-
| Dereference aliases
| Sometimes your LDAP server will tell you that the real value you are searching for is in fact in another part of the LDAP tree (this is called an alias). If you want Moodle to 'dereference' the alias and fetch the real value from the original location, set this to '''yes'''. If you don't want Moodle to dereference it, set this to '''no'''. If you are using MS-AD, set this to '''no'''.
|-
| User attribute
| The attribute used to name/search users in your LDAP tree. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in</u>.

By the way, it's usually '''cn''' (Novell eDirectory and MS-AD) or '''uid''' (RFC-2037, RFC-2037bis and SAMBA 3.x LDAP extension), but if you are using MS-AD you could use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.
|-
| Member attribute
| The attribute used to list the members of a given group. This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>

By the way, the usual values are '''member''' and '''memberUid'''.
|-
| Member attribute uses dn
| Whether the member attribute contains distinguished names (1) or not (0).This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Object class
| The type of LDAP object used to search for users. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
* If you leave it blank, the filter "(objectClass=*)" will be used.
* If you provide "objectClass=some-string", then it will provide "(objectClass=some-string)" as the filter.
* If you provide a value that does not start with "(", it is assumed to be a value that should be set to "objectClass". So if you provide "some-string", then it will provide "(objectClass=some-string)" as the filter.
* If you provide a string that starts with a "(", then it will pass that as is. So if you provide "(&(objectClass=user)(enabledMoodleUser=1))", then it will pass that as the filter.

Here are the default values for each of the ''ldap_user_type'' values:
* '''User''' for Novel eDirectory
* '''posixAccount''' for RFC-2037 and RFC-2037bis
* '''sambaSamAccount''' for SAMBA 3.0.x LDAP extension
* '''user''' for MS-AD
If you get an error about a problem with updating the ldap server (even if you have specified not to write changes back to the ldap server) try setting the ldap object class to * - see http://moodle.org/mod/forum/discuss.php?d=70566 for a discussion on this problem
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Force change password====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Force change password
| Set this to ''Yes'' if you want to force your users to change their password on the first login into Moodle. Otherwise, set this to ''no''. Bear in mind the password they are forced to change is the one stored in your LDAP server.

<u>As you don't want your users to change their passwords in their first login, leave this set to ''No''</u>
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use it's own standard password change page, everytime users want to change their passwords.
* Setting this to ''No'' makes Moodle use the the page specified in the field called "Password change URL" (see below).

Bear in mind that changing your LDAP passwords from Moodle might require a LDAPS connection (this is actually a requirement for MS-AD). In addition to that, the bind user specified above must have the rights needed to change other users' passwords.

Also, code for changing passwords from Moodle for anything but Novell eDirectory and Active Directory is almost not tested, so this may or may not work for other LDAP servers.
|-
| Password Format
| Specify how the new password is encrypted before sending it to the LDAP server: Plain text, MD5 hash or SHA-1 hash. MS-AD uses plain text, for example.
|-
| Password change URL
| Here you can specify a location at which your users can recover or change their username/password if they've forgotten it. This will be provided to users as a button on the login page and their user page. if you leave this blank the button will not be printed.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====LDAP password expiration settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Expiration
|
* Setting this to ''No'' will make Moodle not to check if the password of the user has expired or not.
* Setting this to ''LDAP'' will make Moodle check if the LDAP password of the user has expired or not, and warn her a number of days before the password expires.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

<u>So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.</u>
|-
| Expiration warning
| This value sets how many days in advance of password expiration the user is warned that her password is about to expire.
|-
| Expiration attribute.
| The LDAP user attribute used to check password expiration. This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Grace logins
| This setting is specific to Novell eDirectory. If set to ''Yes'', enable LDAP gracelogin support. After password has expired the user can login until gracelogin count is 0.

<u>So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.</u>
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

<u>So you don't need to fill this in.</u>
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Enable user creation====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Create users externally
| New (anonymous) users can self-create user accounts on the external LDAP server and confirm them via email. If you enable this, remember to also configure module-specific options for user creation and to fill in some instructions in ''auth_instructions'' field in Administration >> Users >> Authentication >> Manage authentication. Otherwise the new users won't be able to self-create new accounts.

As of now, only Novell eDirectory and MS-AD can create users externally.
|-
| Context for new users
| Specify the context where users are created. This context should be different from other users' contexts to prevent security issues.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Course creation====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Creators
| The DN of the group that contains all of your Moodle creators. This is typically a posixGroup with a "memberUid" attribute for each user you want to be a creator. If your group is called ''creators'', type '''cn=creators,ou=moodleusers,dc=my,dc=organization,dc=domain''' here. Each memberUid attribute contains the CN of a user who is authorized to be a creator. Do not use the user's full DN (e.g., not '''memberUid: cn=JoeTeacher,ou=moodleusers,dc-my,dc=organizations,dc=domain''', but rather '''memberUid: JoeTeacher''').

In eDirectory, the objectClass for a group is (by default) not '''posixGroup''' but '''groupOfNames,''' whose member attribute is '''member,''' not '''memberUid,''' and whose value is the full DN of the user in question. Although you can probably modify Moodle's code to use this field, a better solution is just to add a new '''objectClass''' attribute of '''posixGroup''' to your creators group and put the CNs for each creator in a '''memberUid''' attribute.

In MS Active Directory, you will need to create a security group for your creators to be part of and then add them all. If your ldap context above is 'ou=staff,dc=my,dc=org' then your group should then be 'cn=creators,ou=staff,dc=my,dc=org'. If some of the users are from other contexts and have been added to the same security group, you'll have to add these as separate contexts after the first one using the same format.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Cron synchronization script====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Removed ext user
| Specify what to do with internal user account during mass synchronization when user was removed from external source. Only suspended users are automatically revived if they reappear in ext source.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====NTLM SSO====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Enable
| If you want to use NTLM SSO (see details at [[NTLM_authentication]]), choose ''Yes'' here. Otherwise, choose ''No''.
|-
| Subnet
| Specify the subnets of the clients that will use NTLM SSO (see details at [[NTLM_authentication]]).
|-
| MS IE Fast Path?
| If all of you clients (or most of them) are using MS Internet Explorer, you can set this option to bypasses certain steps of the SSO login and speed up login times. This only works with MS Internet Explorer, but deals with other browsers in a sensible way (they are automatically sent to the plain login page).
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Data Mapping====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| First name
| The name of the attribute that holds the first name of your users in your LDAP server. This is usually '''givenName''' or '''displayName'''

<u>This setting is optional</u>
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

<u>This setting is optional</u>
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

<u>This setting is optional</u>
|-
| City/town
| The name of the attribute that holds the city/town of your users in your LDAP server. This is usully '''l''' (lowercase L) or '''localityName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Country
| The name of the attribute that holds the country of your users in your LDAP server. This is usully '''c''' or '''countryName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Language
| '''preferredLanguage'''

<u>This setting is optional</u>
|-
| Description
| '''description'''

<u>This setting is optional</u>
|-
| Webpage
| <u>This setting is optional</u>
|-
| ID Number
|

<u>This setting is optional</u>
|-
| Institution
|

<u>This setting is optional</u>
|-
| Department
| The name of the attribute that holds the department name of your users in your LDAP server. This is usully '''departmentNumber''' (for posixAccount and maybe eDirectory) or '''department''' (for MS-AD).

<u>This setting is optional</u>
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

<u>This setting is optional</u>
|-
| Phone 2
| The name of the attribute that holds an additional telephone number of your users in your LDAP server. This can be '''homePhone''', '''mobile''', '''pager''', '''facsimileTelephoneNumber''' or even others.

<u>This setting is optional</u>
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

<u>This setting is optional</u>
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using cron===
There is a script located at /auth/ldap/auth_ldap_sync_users.php which will create or suspend/delete (see the setting above) all LDAP accounts automatically. Ideally, this is called from the command line once a day during a quiet time using exactly the same procedure as the standard [[Cron|cron]] job (so you will end up with two cron entries). It is important, however, to make sure that all of the above LDAP settings are working properly before you try this, as well as backing up your database and moodledata folders. Poor LDAP configuration could lead to users being wrongly deleted.

If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, this is because by default, MS AD only sends back 1000 users at a time. Follow the instructions [http://support.microsoft.com/kb/315071 here] to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Active Directory help==
[[Active Directory]] is Microsoft's directory service. It is included in Windows 2000 Server and later versions of their operating system. For more information about subjects below, '''[[Active Directory|please go here]]'''.

*Warning: The PHP LDAP module does not seem to be present
*LDAP-module cannot connect any LDAP servers
*Getting correct CNs for Contexts and Creators
*Getting the right user_attribute
*Installing ldp.exe Server Tool
*Example Active Directory Configuration
*Child Domains and the Global Catalog in MS Active Directory
*Enabling the Global Catalog
*Active Directory with Moodle 1.8
*MS Active Directory + SSL

==Advanced Scenarios - Multiple servers or locations==
For larger installations with multiple LDAP servers, or multiple locations (contexts) in a LDAP tree.

===Using multiple LDAP Servers===
Entering more than one name in the ldap_host_url field can provide some sort of resilience to your system. Simply use the syntax :
ldap://my.first.server ; ldap://my.second.server ; ...

Of course, this will only work if all the servers share the same directory information, using a replication or synchronization mecanism once introduced in eDirectory and now generalized to the main LDAP-compatible directories.

There is one drawback in Moodle 1.5 - 1.6 implementation of LDAP authentication : the auth_ldap_connect() function processes the servers sequentially, not in a round robin mode. Thus, if the primary server fails, you will have to wait for the connection to time out before switching to the following one.

See also: [http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers - Our students are on separate domain] discussion on the Using Moodle forum.

===Using multiple user locations (contexts) in your LDAP tree===
There is no need to use multiple user locations if your directory tree is flat, i.e. if all user accounts reside in a '''ou=people,dc=my,dc=organization,dc=domain''' or '''ou=people,o=myorg''' container.

At the opposite, if you use the ACL mecanism to delegate user management, there are chances that your users will be stored in containers like '''ou=students,ou=dept1,o=myorg''' and '''ou=students,ou=dept2,o=myorg''' ...

Then there is an alternative :
* Look at the '''o=myorg''' level with the ldap_search_sub attribute set to '''yes'''.
* Set the ldap_context to '''ou=students,ou=dept1,o=myorg ; ou=students,ou=dept2,o=myorg'''.

Choosing between these two solutions supposes some sort of benchmarking, as the result depends heavily on the structure of your directory tree '''and''' on your LDAP software indexing capabilities. Simply note that there is a probability in such deep trees that two users share the same ''common name'' (cn), while having different ''distinguished names''. Then only the second solution will have a deterministic result (returning allways the same user).

===Using LDAPS (LDAP + SSL)===
====Enabling LDAPS on the LDAP server side====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on the client side (Moodle server)====

* If you are running Moodle on MS Windows, you need to tell PHP's OpenLDAP extension to disable SSL server certificate checking. You must create a directory called ''C:\OpenLDAP\sysconf''. In this directory, create a file called ''ldap.conf'' with the following content (If you are using certain versions of PHP 5.3.x you may need to place the file at other locations, [http://bugs.php.net/bug.php?id=48866 see PHP bug #48866]):

TLS_REQCERT never

* If you are running Moodle on Linux or any other Unix-like operating system, and you want to disable SSL server certificate checking, you need to edit the OpenLDAP client configuration file (usually /etc/ldap.conf or /etc/ldap/ldap.conf or even /etc/openldap/ldap.conf) and make sure you have a line like the following one:

TLS_REQCERT never

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

If you have the certificate of the LDAPS server as a file and want to check the certificate for the connection, copy the certificate file to an arbitary directory (e.g. /etc/ldap/certificate.pem) on your client and change the content of the ''ldap.conf'' as follows:

TLS_REQCERT demand
TLS_CACERT /etc/ldap/certificate.pem

When the requested server certificate is bad or not provided, the connection to the LDAPS server is immediately terminated.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==
===ldap auth_user_create() only suports Novell===

After configuring user authentication with ldap I realized ldap only support edir (Novell) when combining ldap an email user confirmation. For example in my case (I use openldap) I have the following error after filling the user form:

auth: ldap auth_user_create() does not support selected usertype:"rfc2307" (..yet)

=== Setting Resource Limits RedHat Directory Server ===

Operational attributes can be set for the bind user DN using the command-line.
One can simply use ldapmodify to add the following attributes:

{| border="1" cellspacing="0" cellpadding="5"
! Attribute Name
! Description
|-
| nsLookThroughLimit
| Specifies how many entries are examined for a search operation. Giving this attribute a value of -1 indicates that there is no limit.
|-
| nsSizeLimit
| Specifies the maximum number of entries the server returns to a client application in response to a search operation. Giving this attribute a value of -1 indicates that there is no limit.
|-
| nsTimeLimit
| Specifies the maximum time the server spends processing a search operation. Giving this attribute a value of -1 indicates that there is no time limit.
|-
| nsIdleTimeout
| Specifies the time a connection to the server can be idle before the connection is dropped. The value is given in seconds. Giving this attribute a value of -1 indicates that there is no limit.
|}

<pre> LDAP Console Command-Line

ldapmodify -h redhat_dir_server -p 389 -D "cn=directory manager" -w secretpwd

dn: uid=MoodleAdmin,ou=system,dc=myschool,dc=edu
changetype: modify
add:nsSizeLimit
nsSizeLimit: 1000
</pre>

[[LDAP_authentication#Table of Contents|Table of Contents]]

==See also==

* [[NTLM_authentication]]
* [[Active_Directory]]
* [[LDAP enrolment]]
* [http://download.moodle.org/download.php/docs/en/how-to_guides/ldap_auth_and_enrolment_set-up.pdf LDAP auth and enrolment set-up guide] (PDF 227KB)

Using Moodle:
* [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* [http://moodle.org/mod/forum/discuss.php?d=32168 PHP LDAP module does not seem to be present] forum discussion
* [http://moodle.org/mod/forum/discuss.php?d=140901 Syncronisation with AUTH_LDAP_SYNC_USERS.PHP produces fewer accounts than it should] forum discussion
* [http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers] forum discussion

[[Category:Authentication]]

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[zh:LDAP认证]]
[[de:Authentifizierung über LDAP]]

Active Directory

2010-10-20T14:02:35Z

Libertymoodle: /* See also: Using multiple LDAP servers */

Microsoft's Active Directory (AD) provides a variety of network directory services including Lightweight Directory Access Protocol (LDAP) like functions. It is included in Windows 2000 Server and later versions of their operating system. The focus of this page will be with the [[LDAP authentication]] functions.

==Trouble shooting AD and LDAP authentication==
===Warning: The PHP LDAP module does not seem to be present. Please ensure it is installed and enabled.===
This usually means that the main ldap dll or one of the supporting dlls are missing.
Let's start with the main one itself.
Browse to <nowiki>http://(moodleserver)/admin/phpinfo.php</nowiki> and examine the "Configuration File (php.ini) Path" field to determine which php.ini is being used and open it with an editor. Find the line 'extension=php_ldap.dll' and take out the semi-colon if it is there. That semi-colon will stop it loading the module all together!
While you have that file open, search for 'extension_dir' and note which folder it is set to. Open that folder and ensure the php_ldap.dll file is in there. If it isn't then put it in there.
If that still hasn't fixed it you are missing a supporting dll, but you don't get told that. To see what dlls are missing open the Command Prompt and navigate to the php directory and execute the following line 'php -m'. You should get some error messages now. Ugly, but at least they give you information! Find the dlls listed and copy them to the php directory. You may now need to restart the apache/httpd service. Run 'php -m' again and you should be error free and the message in Moodle should be gone now.

===LDAP-module cannot connect any LDAP servers===
LDAP-module cannot connect any LDAP servers:
Server: 'ldap://my.ldap.server/'
Connection: 'Resource id #26' Bind result: ''
Getting this message when you are trying to log in is a result of incorrect details for the Bind user, or the user account having insufficient permissions in Active Directory. The best way to test and resolve this is use ldp.exe to test binding until it suceeds. There are instructions on installing ldp.exe below.
Open the program and Connect to AD, giving the server name, then from the Connection menu choose Bind. Enter the details you think are correct and you will probably find that an error is returned. Try adjusting the accounts priveleges or another account until you are returned an "Authenticated as" message.
Once you are sure your account can be used to bind to AD, check that the DN of that users name is correct. Expand the tree on the left until you find the user you used to bind. Right click on that item and choose Copy DN. Go to the User Authentication page in Moodle and paste the value into the ldap_bind_dn field. Add the password and you can now feel safe your user is binding sucessfully.

===Getting correct CNs for Contexts and Creators===
For those not familiar with AD this could be very confusing, and not that easy for some who are familiar with it. Again, ldp.exe is your friend. There are instructions on installing ldp.exe below.
Open it up and expand the tree on the left until you find the group or user you want to use and right click on it and select Copy DN. Go back to the Moodle User Authentication page and paste that value into either ldap_contexts or ldap_creators.

===Getting the right user_attribute===
By default, Moodle uses an accounts cn (full name) to verify against, but most networks don't use a full given name for logon as it's too easy to guess and you can easily have two people with the same name. If this is the case for you too you need to tell Moodle to look at another field for the logon id.
In ldp.exe navigate the tree on the left to find a user account, preferably your own. Double-click the item in the tree and full-details will be loaded into the screen on the right. Look down the details until you find your logon id and note the item listed against it. For me, and a lot of people, it is sAMAccountName. Copy this name and paste it into the ldap_user_attribute on the Moodle User Authentication page.
There are instructions on installing ldp.exe below.

===Installing ldp.exe Server Tool===
ldp.exe comes as part of the Server Tools on most versions of Windows Server. Find your Windows Server installation disc and find a folder on it called Support\Tools. In there will be a SupTools.msi which will install the server tools if run. You should now have a folder under Program Files called Support Tools, in which will be ldp.exe. ldp.exe is also available in the Windows XP Support Tools, which you can download from Microsoft [http://www.microsoft.com/downloads/details.aspx?FamilyId=49AE8576-9BB9-4126-9761-BA8011FABF38&displaylang=en here]. Alternatively, a single download of ldp.exe is available [http://www.computerperformance.co.uk/w2k3/utilities/ldp.htm here].

===Example Active Directory Configuration===
Below is an example configuration for Active Directory. As detailed above, the values may vary based on your local Active Directory configuration, but should provide a good starting point for most cases.

ldap_host_url = ldap://ads.example.com
ldap_version = 3
ldap_preventpassindb = yes
ldap_bind_dn = bind-user@example.com
ldap_bind_pw = bind-password
ldap_user_type = MS ActiveDirectory
ldap_contexts = ou=moodleusers,dc=example,dc=com
ldap_user_attribute = sAMAccountName

Note that the ldap_bind_dn value should work in either the CN=bin-user,CN=Users,DC=example,DC=com format as shown in the main instructions or the bind-user@example.com format shown in this example.

==Global Catalogs==
Moodle currently only has limited support for multiple domain controllers; specifically it expects each of the LDAP servers listed to contain identical sets of information. If you have users in multiple domains this presents an issue. One solution when working with MS-AD is to use the Global Catalog. The Global Catalog is designed to be a read-only, partial representation of an entire MS-AD forest, designed for searching the entire directory when the domain of the required object is not known.

===Enabling the Global Catalog===

The Global Catalog is available on Windows 2000 and Windows 2003 Active Directory servers. To enable, open the ‘Active Directory Sites and Services’ MMC (Microsoft Management Console) snap-in. Extend ‘Sites’ and then the name of the Site containing the active directory forest you wish to use. Expand the server you wish to enable the Global Catalog on, right click ‘NTDS settings’ and select the ‘Properties’ tab. To enable, simply click the ‘Global Catalog’ checkbox. Under a Windows 2000 server it is necessary to restart the server (although it won’t prompt you to); under Windows 2003 server it is not necessary to restart the server. In either case you will generally have to wait for the AD forest to replicate before the Global Catalog offers a representation of the entire AD forest. Changes made in Active Directory will also be subject to a short delay due to the latency involved with replication. If your AD servers are firewalled port 3268 will need to be opened for Global Catalog servers.
If your organisation uses Microsoft Exchange then it its highly likely that at least one Domain Controller will already have Global Catalog enabled – Exchange 2000 and 2003 rely on the Global Catalog for address information, users also access the Global Catalog when using the GAL (Global Address List)

===Child Domains===
If your organisation has a main domain example.org, staff and students are contained in two child domains staff.example.org and students.example.org. The 3 domains (example.org, staff.example.org and students.example.org) each have a domain controller (dc01, dc02 and dc03 respectively.) Each domain controller contains a full, writable, representation of only the objects that belong to its domain. However, assuming that the Global Catalog has been enabled (see below) on one of the domain controllers (for example dc01) a query to the Global Catalog would reveal matching objects from all three domains. The Global Catalog is automatically maintained through replication across the active directory forest, it can also be enabled on multiple servers (if, for example, you need redundancy / load balancing.)

To make use of this in Moodle to allow logins from multiple domains is simple. The Global Catalog runs on port 3268 as opposed to 389 for standard LDAP queries. As a result, still assuming the Global Catalog is running on dc01, the ''''ldap_host_url'''' would be ''ldap://dc01.example.org:3268''. The rest of the settings are the same as for other MS-AS Auth setups.

You should use the ''''ldap_contexts'''' setting to indicate the locations of individuals you wish to grant access. To extend the example above a little: In the example.org domain users are all in the'' 'Users' ''OU, in the staff.example.org domain users are in two OUs at the root of the domain,'' 'Support Staff' ''and'' 'Teaching Staff' '', and in the students.example.org domain students are in an OU indicating the year that they enrolled, all of which are under the'' 'Students' ''OU. As a result our ''''ldap_contexts'''' setting may look a little like this:'' 'OU=Users,DC=example,DC=org; OU=Support Staff,DC=staff,DC=example,DC=org; OU=Teaching Staff,DC=staff,DC=example,DC=org; OU=Students,DC=students,DC=example,DC=org''.' The ''''ldap_search_sub'''' option should be set to'' 'Yes' ''to allow moodle to search within the child OUs.

Its worth noting that the Global Catalog only contains a partial representation of the attributes of each object, as defined in the Partial Attribute Set supplied by Microsoft. However common information likely to be of use to a general Moodle installation (Forename, Surname, Email Address, sAMAccountName etc) is included in the set. For specific needs the schema can be altered to remove or add various attributes - see Microsoft [http://support.microsoft.com/kb/248717 KB248717] for more information.

In most cases the Global Catalog is read-only, update queries must be made over the standard LDAP ports to the domain controller that holds the object in question (in our example, updating a student's details would require an LDAP query to the students.example.org domain controller - dc03, it would not be possible to update details by querying the Global Catalog.) The exception to this would be in an environment where there is only a single domain in the active directory forest; in this case the Global Catalog holds a writable full set of attributes for each object in the domain. However, for the purposes of Moodle authorisation, there would be no need to use the Global Catalog in this case.

===MaxPageSize setting===
Modifying the number of Active Directory objects to search:

By default Active Directory only allows searches returning a limited number of objects per search. Since there is currently no Page control support in PHP 5.2.x which would enable smaller page searches you may need to modify your MaxPageSize setting to make sure LDAP Client searches can return enough user objects to support the number of authenticating users.

If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, follow the instructions [http://support.microsoft.com/kb/315071 here] to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.

== Active Directory with Moodle 1.8==
There is an issue with the PHP ldap options that are required for Active Directory access in version 1.8 of Moodle.

Using moodle on a LAMP platform with authentication to Active Directory may give some errors.

Check this bug [http://tracker.moodle.org/browse/MDL-10921 MDL-10921] or this post http://moodle.org/mod/forum/discuss.php?d=78316 for further information.

==MS Active Directory + SSL ==

If the Certificate Authority is not installed you'll have to install it first as follows:
# Click '''Start''' -> '''Control Panel''' -> '''Add or Remove programs.'''
# Click '''Add/Remove Windows Components''' and select '''Certificate Services.'''
# Follow the procedure provided to install the '''Certificate Authority'''. Enterprise level is a good choice.

Verify that SSL has been enabled on the server by installing suptools.msi from Windows installation cd's \Support\tools directory. After support tools installation:
# Select '''Start''' -> '''Run''', write '''ldp''' in the Open field.
# From the ldp window select '''Connection''' -> '''Connect''' and supply valid hostname and port number '''636'''. Also select the SSL check box.

If successful, you should get information about the connection.

See [[LDAP_authentication#Enabling_LDAPS_on_the_client_side_.28Moodle_server.29|Enabling LDAPS on the client side (Moodle server)]] for details on the client side configuration.

==See also==
*[[LDAP authentication]] in Moodle
*[http://en.wikipedia.org/wiki/Directory_service Directory services] overview in Wikipedia
*[http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol LDAP] in Wikipedia
*[http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers - Our students are on separate domain] Using Moodle forum discussion

[[ja:Active Directory]]

LDAP authentication

2010-10-20T14:00:43Z

Libertymoodle: /* Multiple LDAP servers See Also link */

{{Moodle 1.9}}
Location: Settings link in ''Administration > Users > [[Authentication]] > LDAP Server''

This document describes how to set up Lightweight Directory Access Protocol (LDAP) authentication in Moodle. We cover the basic, advanced and some trouble shooting sections to assist the user in the installation and administrating LDAP in Moodle.
==Table of Contents==
__TOC__
==Basic Scenario==
The simple and straightforward approach for most installations.

===Assumptions===

# Your Moodle site is located at '''http://your.moodle.site/'''
# You have configured your PHP installation with the LDAP extension. It is loaded and activated, and it shows when you go to '''http://your.moodle.site/admin/phpinfo.php''' (logged in as user 'admin').
# Your LDAP server has '''192.168.1.100''' as its IP address.
# You are not using LDAP with SSL (also known as LDAPS) in your settings. This might prevent certain operations from working (e.g., you cannot update data if you are using MS Active Directory -- MS-AD from here on --), but should be OK if you just want to authenticate your users.
# You don't want your users to change their passwords the first time they log in into Moodle.
# You are using a single domain as the source of your authentication data in case you are using MS-AD (more on this in the Appendices).
# You are using a top level distinguished name (DN) of '''dc=my,dc=organization,dc=domain''' as the root of your LDAP tree.
# You have a non-privileged LDAP user account you will use to bind to the LDAP server. This is not necessary with certain LDAP servers, but MS-AD requires this and it won't hurt if you use it even if your LDAP server doesn't need it. Make sure '''this account and its password don't expire''', and make this password as strong as possible. Remember you only need to type this password once, when configuring Moodle, so don't be afraid of making it as hard to guess as possible. Let's say this user account has a DN of '''cn=ldap-user,dc=my,dc=organization,dc=domain''', and password '''hardtoguesspassword'''.
# All of your Moodle users are in an organizational unit (OU) called '''moodleusers''', which is right under your LDAP root. That OU has a DN of '''ou=moodleusers,dc=my,dc=organization,dc=domain'''.
# You '''don't''' want your LDAP users' passwords to be stored in Moodle at all.

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Configuring Moodle authentication===

Log in as an admin user and go to Administration >> Users >> Authentication >> Manage authentication. In the table that appears, enable the "LDAP Server" authentication option (click on the closed eye to make it open) and then click on the associated 'Settings' link. You will get a page similar to this one:

[[Image:auth_ldap_config_screenshot.jpg|center]]

Now, you just have to fill in the values. Let's go step by step.

[[LDAP_authentication#Table of Contents|Table of Contents]]

====LDAP Server Settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Host URL
| As the IP of your LDAP server is 192.168.1.100, type "'''ldap://192.168.1.100'''" (without the quotes), or just "'''192.168.1.100'''" (some people have trouble connecting with the first syntax, specially on MS Windows servers).
|-
| Version
| Unless you are using a really old LDAP server, '''version 3''' is the one you should choose.
|-
| LDAP Encoding
| Specify encoding used by LDAP server. Most probably utf-8.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Bind settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Hide passwords
| As you '''don't''' want to store the users's password in Moodle's database, choose '''Yes''' here.
|-
| Distinguished Name
| This is the distinguished name of the bind user defined above. Just type "'''cn=ldap-user,dc=my,dc=organization,dc=domain'''" (without the quotes).
|-
| Password
| This is the bind user password defined above. Type "'''hardtoguesspassword'''" (without the quotes).
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====User lookup settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| User type
| Choose:
* '''Novel Edirectory''' if your LDAP server is running Novell's eDdirectory.
* '''posixAccount (rfc2307)''' if your LDAP server is running a RFC-2307 compatible LDAP server (choose this is your server is running OpenLDAP, including Mac OS X server).
* '''posixAccount (rfc2307bis)''' if your LDAP server is running a RFC-2307bis compatible LDAP server.
* '''sambaSamAccount (v.3.0.7)''' if your LDAP server is running with SAMBA's 3.x LDAP schema extension and you want to use it.
* '''MS ActiveDirectory''' if your LDAP server is running Microsoft's Active Directory (MS-AD)
|-
| Contexts
| The DN of the context (container) where all of your Moodle users are found. Type '''ou=moodleusers,dc=my,dc=organization,dc=domain''' here.

On a Mac OS X Server, this is usually '''cn=users,dc=my,dc=organization,dc=domain'''.
|-
| Search subcontexts
| If you have any sub organizational units (subcontexts) hanging from '''ou=moodleusers,dc=my,dc=organization,dc=domain''' and you want Moodle to search there too, set this to '''yes'''. Otherwise, set this to '''no'''.
|-
| Dereference aliases
| Sometimes your LDAP server will tell you that the real value you are searching for is in fact in another part of the LDAP tree (this is called an alias). If you want Moodle to 'dereference' the alias and fetch the real value from the original location, set this to '''yes'''. If you don't want Moodle to dereference it, set this to '''no'''. If you are using MS-AD, set this to '''no'''.
|-
| User attribute
| The attribute used to name/search users in your LDAP tree. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in</u>.

By the way, it's usually '''cn''' (Novell eDirectory and MS-AD) or '''uid''' (RFC-2037, RFC-2037bis and SAMBA 3.x LDAP extension), but if you are using MS-AD you could use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.
|-
| Member attribute
| The attribute used to list the members of a given group. This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>

By the way, the usual values are '''member''' and '''memberUid'''.
|-
| Member attribute uses dn
| Whether the member attribute contains distinguished names (1) or not (0).This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Object class
| The type of LDAP object used to search for users. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
* If you leave it blank, the filter "(objectClass=*)" will be used.
* If you provide "objectClass=some-string", then it will provide "(objectClass=some-string)" as the filter.
* If you provide a value that does not start with "(", it is assumed to be a value that should be set to "objectClass". So if you provide "some-string", then it will provide "(objectClass=some-string)" as the filter.
* If you provide a string that starts with a "(", then it will pass that as is. So if you provide "(&(objectClass=user)(enabledMoodleUser=1))", then it will pass that as the filter.

Here are the default values for each of the ''ldap_user_type'' values:
* '''User''' for Novel eDirectory
* '''posixAccount''' for RFC-2037 and RFC-2037bis
* '''sambaSamAccount''' for SAMBA 3.0.x LDAP extension
* '''user''' for MS-AD
If you get an error about a problem with updating the ldap server (even if you have specified not to write changes back to the ldap server) try setting the ldap object class to * - see http://moodle.org/mod/forum/discuss.php?d=70566 for a discussion on this problem
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Force change password====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Force change password
| Set this to ''Yes'' if you want to force your users to change their password on the first login into Moodle. Otherwise, set this to ''no''. Bear in mind the password they are forced to change is the one stored in your LDAP server.

<u>As you don't want your users to change their passwords in their first login, leave this set to ''No''</u>
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use it's own standard password change page, everytime users want to change their passwords.
* Setting this to ''No'' makes Moodle use the the page specified in the field called "Password change URL" (see below).

Bear in mind that changing your LDAP passwords from Moodle might require a LDAPS connection (this is actually a requirement for MS-AD). In addition to that, the bind user specified above must have the rights needed to change other users' passwords.

Also, code for changing passwords from Moodle for anything but Novell eDirectory and Active Directory is almost not tested, so this may or may not work for other LDAP servers.
|-
| Password Format
| Specify how the new password is encrypted before sending it to the LDAP server: Plain text, MD5 hash or SHA-1 hash. MS-AD uses plain text, for example.
|-
| Password change URL
| Here you can specify a location at which your users can recover or change their username/password if they've forgotten it. This will be provided to users as a button on the login page and their user page. if you leave this blank the button will not be printed.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====LDAP password expiration settings====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Expiration
|
* Setting this to ''No'' will make Moodle not to check if the password of the user has expired or not.
* Setting this to ''LDAP'' will make Moodle check if the LDAP password of the user has expired or not, and warn her a number of days before the password expires.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

<u>So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.</u>
|-
| Expiration warning
| This value sets how many days in advance of password expiration the user is warned that her password is about to expire.
|-
| Expiration attribute.
| The LDAP user attribute used to check password expiration. This option takes a default value based on the ''User type'' value you choosed above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Grace logins
| This setting is specific to Novell eDirectory. If set to ''Yes'', enable LDAP gracelogin support. After password has expired the user can login until gracelogin count is 0.

<u>So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.</u>
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

<u>So you don't need to fill this in.</u>
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Enable user creation====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Create users externally
| New (anonymous) users can self-create user accounts on the external LDAP server and confirm them via email. If you enable this, remember to also configure module-specific options for user creation and to fill in some instructions in ''auth_instructions'' field in Administration >> Users >> Authentication >> Manage authentication. Otherwise the new users won't be able to self-create new accounts.

As of now, only Novell eDirectory and MS-AD can create users externally.
|-
| Context for new users
| Specify the context where users are created. This context should be different from other users' contexts to prevent security issues.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Course creation====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Creators
| The DN of the group that contains all of your Moodle creators. This is typically a posixGroup with a "memberUid" attribute for each user you want to be a creator. If your group is called ''creators'', type '''cn=creators,ou=moodleusers,dc=my,dc=organization,dc=domain''' here. Each memberUid attribute contains the CN of a user who is authorized to be a creator. Do not use the user's full DN (e.g., not '''memberUid: cn=JoeTeacher,ou=moodleusers,dc-my,dc=organizations,dc=domain''', but rather '''memberUid: JoeTeacher''').

In eDirectory, the objectClass for a group is (by default) not '''posixGroup''' but '''groupOfNames,''' whose member attribute is '''member,''' not '''memberUid,''' and whose value is the full DN of the user in question. Although you can probably modify Moodle's code to use this field, a better solution is just to add a new '''objectClass''' attribute of '''posixGroup''' to your creators group and put the CNs for each creator in a '''memberUid''' attribute.

In MS Active Directory, you will need to create a security group for your creators to be part of and then add them all. If your ldap context above is 'ou=staff,dc=my,dc=org' then your group should then be 'cn=creators,ou=staff,dc=my,dc=org'. If some of the users are from other contexts and have been added to the same security group, you'll have to add these as separate contexts after the first one using the same format.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Cron synchronization script====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Removed ext user
| Specify what to do with internal user account during mass synchronization when user was removed from external source. Only suspended users are automatically revived if they reappear in ext source.
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====NTLM SSO====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| Enable
| If you want to use NTLM SSO (see details at [[NTLM_authentication]]), choose ''Yes'' here. Otherwise, choose ''No''.
|-
| Subnet
| Specify the subnets of the clients that will use NTLM SSO (see details at [[NTLM_authentication]]).
|-
| MS IE Fast Path?
| If all of you clients (or most of them) are using MS Internet Explorer, you can set this option to bypasses certain steps of the SSO login and speed up login times. This only works with MS Internet Explorer, but deals with other browsers in a sensible way (they are automatically sent to the plain login page).
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

====Data Mapping====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| First name
| The name of the attribute that holds the first name of your users in your LDAP server. This is usually '''givenName''' or '''displayName'''

<u>This setting is optional</u>
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

<u>This setting is optional</u>
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

<u>This setting is optional</u>
|-
| City/town
| The name of the attribute that holds the city/town of your users in your LDAP server. This is usully '''l''' (lowercase L) or '''localityName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Country
| The name of the attribute that holds the country of your users in your LDAP server. This is usully '''c''' or '''countryName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Language
| '''preferredLanguage'''

<u>This setting is optional</u>
|-
| Description
| '''description'''

<u>This setting is optional</u>
|-
| Webpage
| <u>This setting is optional</u>
|-
| ID Number
|

<u>This setting is optional</u>
|-
| Institution
|

<u>This setting is optional</u>
|-
| Department
| The name of the attribute that holds the department name of your users in your LDAP server. This is usully '''departmentNumber''' (for posixAccount and maybe eDirectory) or '''department''' (for MS-AD).

<u>This setting is optional</u>
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

<u>This setting is optional</u>
|-
| Phone 2
| The name of the attribute that holds an additional telephone number of your users in your LDAP server. This can be '''homePhone''', '''mobile''', '''pager''', '''facsimileTelephoneNumber''' or even others.

<u>This setting is optional</u>
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

<u>This setting is optional</u>
|}

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using cron===
There is a script located at /auth/ldap/auth_ldap_sync_users.php which will create or suspend/delete (see the setting above) all LDAP accounts automatically. Ideally, this is called from the command line once a day during a quiet time using exactly the same procedure as the standard [[Cron|cron]] job (so you will end up with two cron entries). It is important, however, to make sure that all of the above LDAP settings are working properly before you try this, as well as backing up your database and moodledata folders. Poor LDAP configuration could lead to users being wrongly deleted.

If you find that the script is not running through all of your users properly and you have MS Active Directory + over 1000 users, this is because by default, MS AD only sends back 1000 users at a time. Follow the instructions [http://support.microsoft.com/kb/315071 here] to set the MaxPageSize setting to a number higher than your total number of users (both now and in future) to fix it. This is a forest-wide setting.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Active Directory help==
[[Active Directory]] is Microsoft's directory service. It is included in Windows 2000 Server and later versions of their operating system. For more information about subjects below, '''[[Active Directory|please go here]]'''.

*Warning: The PHP LDAP module does not seem to be present
*LDAP-module cannot connect any LDAP servers
*Getting correct CNs for Contexts and Creators
*Getting the right user_attribute
*Installing ldp.exe Server Tool
*Example Active Directory Configuration
*Child Domains and the Global Catalog in MS Active Directory
*Enabling the Global Catalog
*Active Directory with Moodle 1.8
*MS Active Directory + SSL

==Advanced Scenarios - Multiple servers or locations==
For larger installations with multiple LDAP servers, or multiple locations (contexts) in a LDAP tree.

===Using multiple LDAP Servers===
Entering more than one name in the ldap_host_url field can provide some sort of resilience to your system. Simply use the syntax :
ldap://my.first.server ; ldap://my.second.server ; ...

Of course, this will only work if all the servers share the same directory information, using a replication or synchronization mecanism once introduced in eDirectory and now generalized to the main LDAP-compatible directories.

There is one drawback in Moodle 1.5 - 1.6 implementation of LDAP authentication : the auth_ldap_connect() function processes the servers sequentially, not in a round robin mode. Thus, if the primary server fails, you will have to wait for the connection to time out before switching to the following one.

See also: [http://moodle.org/mod/forum/discuss.php?d=17198#p111090 Using multiple LDAP servers - Our students are on separate domain] discussion on the Using Moodle forum.

===Using multiple user locations (contexts) in your LDAP tree===
There is no need to use multiple user locations if your directory tree is flat, i.e. if all user accounts reside in a '''ou=people,dc=my,dc=organization,dc=domain''' or '''ou=people,o=myorg''' container.

At the opposite, if you use the ACL mecanism to delegate user management, there are chances that your users will be stored in containers like '''ou=students,ou=dept1,o=myorg''' and '''ou=students,ou=dept2,o=myorg''' ...

Then there is an alternative :
* Look at the '''o=myorg''' level with the ldap_search_sub attribute set to '''yes'''.
* Set the ldap_context to '''ou=students,ou=dept1,o=myorg ; ou=students,ou=dept2,o=myorg'''.

Choosing between these two solutions supposes some sort of benchmarking, as the result depends heavily on the structure of your directory tree '''and''' on your LDAP software indexing capabilities. Simply note that there is a probability in such deep trees that two users share the same ''common name'' (cn), while having different ''distinguished names''. Then only the second solution will have a deterministic result (returning allways the same user).

===Using LDAPS (LDAP + SSL)===
====Enabling LDAPS on the LDAP server side====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on the client side (Moodle server)====

* If you are running Moodle on MS Windows, you need to tell PHP's OpenLDAP extension to disable SSL server certificate checking. You must create a directory called ''C:\OpenLDAP\sysconf''. In this directory, create a file called ''ldap.conf'' with the following content (If you are using certain versions of PHP 5.3.x you may need to place the file at other locations, [http://bugs.php.net/bug.php?id=48866 see PHP bug #48866]):

TLS_REQCERT never

* If you are running Moodle on Linux or any other Unix-like operating system, and you want to disable SSL server certificate checking, you need to edit the OpenLDAP client configuration file (usually /etc/ldap.conf or /etc/ldap/ldap.conf or even /etc/openldap/ldap.conf) and make sure you have a line like the following one:

TLS_REQCERT never

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

If you have the certificate of the LDAPS server as a file and want to check the certificate for the connection, copy the certificate file to an arbitary directory (e.g. /etc/ldap/certificate.pem) on your client and change the content of the ''ldap.conf'' as follows:

TLS_REQCERT demand
TLS_CACERT /etc/ldap/certificate.pem

When the requested server certificate is bad or not provided, the connection to the LDAPS server is immediately terminated.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==
===ldap auth_user_create() only suports Novell===

After configuring user authentication with ldap I realized ldap only support edir (Novell) when combining ldap an email user confirmation. For example in my case (I use openldap) I have the following error after filling the user form:

auth: ldap auth_user_create() does not support selected usertype:"rfc2307" (..yet)

=== Setting Resource Limits RedHat Directory Server ===

Operational attributes can be set for the bind user DN using the command-line.
One can simply use ldapmodify to add the following attributes:

{| border="1" cellspacing="0" cellpadding="5"
! Attribute Name
! Description
|-
| nsLookThroughLimit
| Specifies how many entries are examined for a search operation. Giving this attribute a value of -1 indicates that there is no limit.
|-
| nsSizeLimit
| Specifies the maximum number of entries the server returns to a client application in response to a search operation. Giving this attribute a value of -1 indicates that there is no limit.
|-
| nsTimeLimit
| Specifies the maximum time the server spends processing a search operation. Giving this attribute a value of -1 indicates that there is no time limit.
|-
| nsIdleTimeout
| Specifies the time a connection to the server can be idle before the connection is dropped. The value is given in seconds. Giving this attribute a value of -1 indicates that there is no limit.
|}

<pre> LDAP Console Command-Line

ldapmodify -h redhat_dir_server -p 389 -D "cn=directory manager" -w secretpwd

dn: uid=MoodleAdmin,ou=system,dc=myschool,dc=edu
changetype: modify
add:nsSizeLimit
nsSizeLimit: 1000
</pre>

[[LDAP_authentication#Table of Contents|Table of Contents]]

==See also==

* [[NTLM_authentication]]
* [[Active_Directory]]
* [[LDAP enrolment]]
* [http://download.moodle.org/download.php/docs/en/how-to_guides/ldap_auth_and_enrolment_set-up.pdf LDAP auth and enrolment set-up guide] (PDF 227KB)

Using Moodle:
* [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* [http://moodle.org/mod/forum/discuss.php?d=32168 PHP LDAP module does not seem to be present] forum discussion
* [http://moodle.org/mod/forum/discuss.php?d=140901 Syncronisation with AUTH_LDAP_SYNC_USERS.PHP produces fewer accounts than it should] forum discussion
* [http://moodle.org/mod/forum/discuss.php?d=17198 Using multiple LDAP servers] forum discussion

[[Category:Authentication]]

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[zh:LDAP认证]]
[[de:Authentifizierung über LDAP]]

blocks/configurable reports/

2010-10-18T06:08:45Z

Libertymoodle: /* See Also link */

== Installation ==

# Download the Configurable Reports installation file and unzip it to the '''\blocks''' directory in your Moodle folder.
# Login to Moodle as Administrator and click Notifications under Site Administration.

For more information see [[Installing contributed modules or plugins]]

== Overview ==

This block is a Moodle custom reports builder.

It is designed in a modular way to allow developers to create new plugins in less than an hour.

'''Who can create custom reports?'''

Anyone with block, managereports or manageownreports permissions at SITE level or COURSE level.

'''What type of reports can I create?'''

- Courses reports, with information regarding courses.

- Users reports, with information regarding users and their activity in a course.

- Custom SQL Reports, custom SQL queries. This block can use the same SQL queries that [http://moodle.org/mod/data/view.php?d=13&rid=2884 Tim Hunt's Custom SQL queries] plugin.

Note for developers: You can create your own type of reports.

'''Who can view the reports?'''

When you create a report you can select which users can view it.

The reports are displayed in a block in the course or site frontpage.

== Creating a report ==

This is a very simple process.

If you are going to create a report for a course, you have to add the block in the course and click in the "Manage reports" link.

On the other hand, for site reports, add the block in the frontpage and click in the "Manage reports" link.

You must enter a name, an optional description, and you have to choose the type of report, pagination and exports formats.

Depending on the report choosen, there will be more or less tabs. These are the tabs for the courses and users report:

'''Columns''': Here you can choose the differents columns of your report depending on the type of report. (Course Name, User firstname, etc..)

'''Conditions''': Here you can define the conditions (i.e, only courses from this category, only users from Spain, etc.)

'''Ordering''': Here you can choose how to order the report using fields and directions.

'''Filters''': Here you can choose which filters will be displayed.

'''Template''': You can modify the report's layout by creating a template.

'''Permissions''': Here you can choose who can view a report.

'''Calculations''': Here you can add calculations for columns, i.e: average of number of users enrolled in courses

'''Plots''': Here you can add graphs to your report based on the report columns and values.

'''View report''': Self explanatory

== Tutorial ==

=== Creating a users' report ===

Requirements: ''Users from Spain, but no from Madrid, in this course. This report can be viewed only by users from Spain. A filter based on the user's city must be displayed. A pie plot showing the users' cities is required. A calculation table showing the total forum post views is required. The report must be order by users' lastname.''

Let's see how easy it is!

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports"

Click on "Add report"

Enter a name, a description and choose "Users report" as Type of Report

The report will be saved and you will be redirected to the first Tab named "Columns".

'''Adding Columns'''

Here you can define the report table properties, width, align, cell padding, cell spacing, etc..
Add a Column called "User profile field"

Choose the field "firstname" and enter a name for the column in the text field. You can leave blank the rest of elements.

Repit the process above for the lastname and city fields.

Add a Column called "User module actions".

Choose a module from the list, in this example, a forum.

'''Adding Conditions'''

Click on the Conditions Tab.

Add a Condition named "User field Condition".

Choose the column "Country", the Operator "=", and enter the value "ES" (this is the international code for Spain as Moodle stores it).

Add a Condition named "User field Condition".

Choose the column "city", the Operator "<>", and enter the value "Madrid".

Add a Condition named "Users in current report course".

These are the main conditions of the reports. Note that at the bottom there is a text box called condition, with this text:

"c2 and c1 and c3"

Here you can define a logic condition, in this case, we don't need to edit this condition but you can create complex expressions like:

(c1 and c2) or (c4 and c3)

'''Adding Ordering'''

Click on the Ordering Tab.

Add a ordering named "User field ordering".

Choose the column "Lastname" and the ordering "ASC" (Ascending).

'''Adding Filters'''

Click on the Filters Tab.

Add a filter named "User field filter".

Choose city.

'''Adding Permissions'''

Click on the Permissions Tab.

Choose "User field Value".

Choose the column "Country", and enter the value "ES".

Here you can add more permissions and a logic condition to be achieved.

'''Adding Calculations'''

Click on the Calculations tab.

Choose Sum.

Choose the column "User module actions".

'''Adding Plots'''

Click on the Plots tab.

Choose "Pie".

Choose the colum "City" as Name and Value.

Finally, add a few users in Moodle with the country Spain, and different cities, Madrid, Barcelona, Seville etc. and test the report.

You can download the report in differents formats (ods and xls), remember to check these options in the report page.

[[blocks/custom_reports/#Users_report | See screenshot]]

=== Creating a SQL Report ===

You can find a lot of SQL Reports here: [[ad-hoc contributed reports]]

Since this block supports Tim Hunt's CustomSQL Queries Reports, you can use any query.

Remember to add a "Time filter" if you are going to use reports with time tokens.

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports".

Click on "Add report

Enter a name, description, choose "SQL" as Type of Report

The report will be saved and you redirect to the firs Tab named "Custom SQL"

Add this query (''Courses activity''):

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to Calculations Tab

Add a Sum calculation, choose the hits column

Go to Plot

Add a Pie graph, choosing coursename as Name and hits as value

So, here you have, a report with a Graph and calculations based on a SQL Query.

You can add a Course filter, is very easy:

Go to filters, choose Courses

Edit the Custom SQL query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Note that we are adding a token called: %%FILTER_COURSES:l.courseid%%

Go to View report, and you will see a Courses Filter, choose a Course and click on Add, here you have a report filtered.

You cand add also, and Starttime and endtime filter

Go to filters, choose Stard / End date filter

Go to Custom SQL tab, this is the new query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
%%FILTER_STARTTIME:l.time:>%% %%FILTER_ENDTIME:l.time:<%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to View report, now you can filter by time also

[[blocks/custom_reports/#SQL_report | See screenshot]]

== Advanced options ==

=== Templates ===

You can customize the report output using a template.

Just enable the Template option in the same name tab.

This is an example html code for displaying a list of users:

Header:

<code html4strict>
<p align="center"><b>##reportname##</b></p>
<table width="60%" align="center">
<tr>
<td>
</code>

Record:

<code html4strict>
<table width="100%">
<tr>
<td><img src="http://yourmoodle.com/user/pix.php/[[id]]/f1.jpg"></td>
<td><h2>[[Firstname]] [[Lastname]]</h2>
City: [[City]]
</td>
</tr>
</table>
<br>
</code>

Footer:

<code html4strict>
</td>
<td valign="top">
##graphs##
<br /><br />
##exportoptions##
</td>
</table>
</code>

=== Embedded reports ===

A embedded report consists in a report's set of columns that are embeeded in other report.

You can embed a user report into a course report, in this case, the resulting rows will be expanded duplicating each row for each user.

Imaging you have a courses report, you can embed a user report, every row of the course report will be cloned for each user.

To embed a report just add a "Other report" column, a list of your reports will be showed.

Inside a course report you can embed a user report and the other way.

== Developers documentation ==

It's very easy to create new report types, components and plugins.

'''Report''': A report plugin is a folder located at /report.
This folder contains a .class.php file with the child - class of the report_base.

You only need to modify a few methos to add a new report type.
Please, take a look to any of the current reports. The SQL report is an example of a non-typical report,
meanwhile the users and courses reports are standard reports.

The best way to create a report is duplicate an existing one.

'''Component''': A component is part of a report, a component may be used by more than one report.
The main Component is the component Columns, that is used to add the columns of a report.

Others components are filters, permissions, plot, calculations..

The best way to create a component is duplicate an existing one.

'''Plugin''': A plugin is a component module. The component column has a few of plugins (coursefield, userfield, etc..)
A plugins works usually for an unique report, but there are plugins that works for more than one report.
The best way to create a plugin is duplicate an existing one.

== Credits ==

Juan Leyva [http://moodle.org/user/view.php?id=49568&course=1 Moodle profile]

[http://twitter.com/jleyvadelgado Follow me in Twitter]

[[Category:Contributed code]]

== Screenshots ==

=== Users report ===
[[Image:block_custom_reports_sample_user_report.png|600px]]

=== SQL report ===
[[Image:block_custom_reports_sample_sql_report.png|600px]]

== See Also ==

CONTRIB-2386

[http://tracker.moodle.org/browse/CONTRIB/component/10753 Block: Configurable reports] Tracker component

[http://moodle.org/mod/data/view.php?rid=4283 Modules & Plugins] database entry

[[es:blocks/configurable_reports/]]

blocks/configurable reports/

2010-10-18T06:04:22Z

Libertymoodle: /* See Also link */

== Installation ==

# Download the Configurable Reports installation file and unzip it to the '''\blocks''' directory in your Moodle folder.
# Login to Moodle as Administrator and click Notifications under Site Administration.

For more information see [[Installing contributed modules or plugins]]

== Overview ==

This block is a Moodle custom reports builder.

It is designed in a modular way to allow developers to create new plugins in less than an hour.

'''Who can create custom reports?'''

Anyone with block, managereports or manageownreports permissions at SITE level or COURSE level.

'''What type of reports can I create?'''

- Courses reports, with information regarding courses.

- Users reports, with information regarding users and their activity in a course.

- Custom SQL Reports, custom SQL queries. This block can use the same SQL queries that [http://moodle.org/mod/data/view.php?d=13&rid=2884 Tim Hunt's Custom SQL queries] plugin.

Note for developers: You can create your own type of reports.

'''Who can view the reports?'''

When you create a report you can select which users can view it.

The reports are displayed in a block in the course or site frontpage.

== Creating a report ==

This is a very simple process.

If you are going to create a report for a course, you have to add the block in the course and click in the "Manage reports" link.

On the other hand, for site reports, add the block in the frontpage and click in the "Manage reports" link.

You must enter a name, an optional description, and you have to choose the type of report, pagination and exports formats.

Depending on the report choosen, there will be more or less tabs. These are the tabs for the courses and users report:

'''Columns''': Here you can choose the differents columns of your report depending on the type of report. (Course Name, User firstname, etc..)

'''Conditions''': Here you can define the conditions (i.e, only courses from this category, only users from Spain, etc.)

'''Ordering''': Here you can choose how to order the report using fields and directions.

'''Filters''': Here you can choose which filters will be displayed.

'''Template''': You can modify the report's layout by creating a template.

'''Permissions''': Here you can choose who can view a report.

'''Calculations''': Here you can add calculations for columns, i.e: average of number of users enrolled in courses

'''Plots''': Here you can add graphs to your report based on the report columns and values.

'''View report''': Self explanatory

== Tutorial ==

=== Creating a users' report ===

Requirements: ''Users from Spain, but no from Madrid, in this course. This report can be viewed only by users from Spain. A filter based on the user's city must be displayed. A pie plot showing the users' cities is required. A calculation table showing the total forum post views is required. The report must be order by users' lastname.''

Let's see how easy it is!

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports"

Click on "Add report"

Enter a name, a description and choose "Users report" as Type of Report

The report will be saved and you will be redirected to the first Tab named "Columns".

'''Adding Columns'''

Here you can define the report table properties, width, align, cell padding, cell spacing, etc..
Add a Column called "User profile field"

Choose the field "firstname" and enter a name for the column in the text field. You can leave blank the rest of elements.

Repit the process above for the lastname and city fields.

Add a Column called "User module actions".

Choose a module from the list, in this example, a forum.

'''Adding Conditions'''

Click on the Conditions Tab.

Add a Condition named "User field Condition".

Choose the column "Country", the Operator "=", and enter the value "ES" (this is the international code for Spain as Moodle stores it).

Add a Condition named "User field Condition".

Choose the column "city", the Operator "<>", and enter the value "Madrid".

Add a Condition named "Users in current report course".

These are the main conditions of the reports. Note that at the bottom there is a text box called condition, with this text:

"c2 and c1 and c3"

Here you can define a logic condition, in this case, we don't need to edit this condition but you can create complex expressions like:

(c1 and c2) or (c4 and c3)

'''Adding Ordering'''

Click on the Ordering Tab.

Add a ordering named "User field ordering".

Choose the column "Lastname" and the ordering "ASC" (Ascending).

'''Adding Filters'''

Click on the Filters Tab.

Add a filter named "User field filter".

Choose city.

'''Adding Permissions'''

Click on the Permissions Tab.

Choose "User field Value".

Choose the column "Country", and enter the value "ES".

Here you can add more permissions and a logic condition to be achieved.

'''Adding Calculations'''

Click on the Calculations tab.

Choose Sum.

Choose the column "User module actions".

'''Adding Plots'''

Click on the Plots tab.

Choose "Pie".

Choose the colum "City" as Name and Value.

Finally, add a few users in Moodle with the country Spain, and different cities, Madrid, Barcelona, Seville etc. and test the report.

You can download the report in differents formats (ods and xls), remember to check these options in the report page.

[[blocks/custom_reports/#Users_report | See screenshot]]

=== Creating a SQL Report ===

You can find a lot of SQL Reports here: [[ad-hoc contributed reports]]

Since this block supports Tim Hunt's CustomSQL Queries Reports, you can use any query.

Remember to add a "Time filter" if you are going to use reports with time tokens.

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports".

Click on "Add report

Enter a name, description, choose "SQL" as Type of Report

The report will be saved and you redirect to the firs Tab named "Custom SQL"

Add this query (''Courses activity''):

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to Calculations Tab

Add a Sum calculation, choose the hits column

Go to Plot

Add a Pie graph, choosing coursename as Name and hits as value

So, here you have, a report with a Graph and calculations based on a SQL Query.

You can add a Course filter, is very easy:

Go to filters, choose Courses

Edit the Custom SQL query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Note that we are adding a token called: %%FILTER_COURSES:l.courseid%%

Go to View report, and you will see a Courses Filter, choose a Course and click on Add, here you have a report filtered.

You cand add also, and Starttime and endtime filter

Go to filters, choose Stard / End date filter

Go to Custom SQL tab, this is the new query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
%%FILTER_STARTTIME:l.time:>%% %%FILTER_ENDTIME:l.time:<%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to View report, now you can filter by time also

[[blocks/custom_reports/#SQL_report | See screenshot]]

== Advanced options ==

=== Templates ===

You can customize the report output using a template.

Just enable the Template option in the same name tab.

This is an example html code for displaying a list of users:

Header:

<code html4strict>
<p align="center"><b>##reportname##</b></p>
<table width="60%" align="center">
<tr>
<td>
</code>

Record:

<code html4strict>
<table width="100%">
<tr>
<td><img src="http://yourmoodle.com/user/pix.php/[[id]]/f1.jpg"></td>
<td><h2>[[Firstname]] [[Lastname]]</h2>
City: [[City]]
</td>
</tr>
</table>
<br>
</code>

Footer:

<code html4strict>
</td>
<td valign="top">
##graphs##
<br /><br />
##exportoptions##
</td>
</table>
</code>

=== Embedded reports ===

A embedded report consists in a report's set of columns that are embeeded in other report.

You can embed a user report into a course report, in this case, the resulting rows will be expanded duplicating each row for each user.

Imaging you have a courses report, you can embed a user report, every row of the course report will be cloned for each user.

To embed a report just add a "Other report" column, a list of your reports will be showed.

Inside a course report you can embed a user report and the other way.

== Developers documentation ==

It's very easy to create new report types, components and plugins.

'''Report''': A report plugin is a folder located at /report.
This folder contains a .class.php file with the child - class of the report_base.

You only need to modify a few methos to add a new report type.
Please, take a look to any of the current reports. The SQL report is an example of a non-typical report,
meanwhile the users and courses reports are standard reports.

The best way to create a report is duplicate an existing one.

'''Component''': A component is part of a report, a component may be used by more than one report.
The main Component is the component Columns, that is used to add the columns of a report.

Others components are filters, permissions, plot, calculations..

The best way to create a component is duplicate an existing one.

'''Plugin''': A plugin is a component module. The component column has a few of plugins (coursefield, userfield, etc..)
A plugins works usually for an unique report, but there are plugins that works for more than one report.
The best way to create a plugin is duplicate an existing one.

== Credits ==

Juan Leyva [http://moodle.org/user/view.php?id=49568&course=1 Moodle profile]

[http://twitter.com/jleyvadelgado Follow me in Twitter]

[[Category:Contributed code]]

== Screenshots ==

=== Users report ===
[[Image:block_custom_reports_sample_user_report.png|600px]]

=== SQL report ===
[[Image:block_custom_reports_sample_sql_report.png|600px]]

== See Also ==

CONTRIB-2386

[http://tracker.moodle.org/browse/CONTRIB/component/10753 Block: Configurable reports] Tracker component

[http://moodle.org/mod/data/view.php?d=13&rid=4283&filter=1 Modules & Plugins] database entry

[[es:blocks/configurable_reports/]]

blocks/configurable reports/

2010-10-15T07:10:12Z

Libertymoodle: /* Added See Also */

== Installation ==

# Download the Configurable Reports installation file and unzip it to the '''\blocks''' directory in your Moodle folder.
# Login to Moodle as Administrator and click Notifications under Site Administration.

For more information see [[Installing contributed modules or plugins]]

== Overview ==

This block is a Moodle custom reports builder.

It is designed in a modular way to allow developers to create new plugins in less than an hour.

'''Who can create custom reports?'''

Anyone with block, managereports or manageownreports permissions at SITE level or COURSE level.

'''What type of reports can I create?'''

- Courses reports, with information regarding courses.

- Users reports, with information regarding users and their activity in a course.

- Custom SQL Reports, custom SQL queries. This block can use the same SQL queries that [http://moodle.org/mod/data/view.php?d=13&rid=2884 Tim Hunt's Custom SQL queries] plugin.

Note for developers: You can create your own type of reports.

'''Who can view the reports?'''

When you create a report you can select which users can view it.

The reports are displayed in a block in the course or site frontpage.

== Creating a report ==

This is a very simple process.

If you are going to create a report for a course, you have to add the block in the course and click in the "Manage reports" link.

On the other hand, for site reports, add the block in the frontpage and click in the "Manage reports" link.

You must enter a name, an optional description, and you have to choose the type of report, pagination and exports formats.

Depending on the report choosen, there will be more or less tabs. These are the tabs for the courses and users report:

'''Columns''': Here you can choose the differents columns of your report depending on the type of report. (Course Name, User firstname, etc..)

'''Conditions''': Here you can define the conditions (i.e, only courses from this category, only users from Spain, etc.)

'''Ordering''': Here you can choose how to order the report using fields and directions.

'''Filters''': Here you can choose which filters will be displayed.

'''Template''': You can modify the report's layout by creating a template.

'''Permissions''': Here you can choose who can view a report.

'''Calculations''': Here you can add calculations for columns, i.e: average of number of users enrolled in courses

'''Plots''': Here you can add graphs to your report based on the report columns and values.

'''View report''': Self explanatory

== Tutorial ==

=== Creating a users' report ===

Requirements: ''Users from Spain, but no from Madrid, in this course. This report can be viewed only by users from Spain. A filter based on the user's city must be displayed. A pie plot showing the users' cities is required. A calculation table showing the total forum post views is required. The report must be order by users' lastname.''

Let's see how easy it is!

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports"

Click on "Add report"

Enter a name, a description and choose "Users report" as Type of Report

The report will be saved and you will be redirected to the first Tab named "Columns".

'''Adding Columns'''

Here you can define the report table properties, width, align, cell padding, cell spacing, etc..
Add a Column called "User profile field"

Choose the field "firstname" and enter a name for the column in the text field. You can leave blank the rest of elements.

Repit the process above for the lastname and city fields.

Add a Column called "User module actions".

Choose a module from the list, in this example, a forum.

'''Adding Conditions'''

Click on the Conditions Tab.

Add a Condition named "User field Condition".

Choose the column "Country", the Operator "=", and enter the value "ES" (this is the international code for Spain as Moodle stores it).

Add a Condition named "User field Condition".

Choose the column "city", the Operator "<>", and enter the value "Madrid".

Add a Condition named "Users in current report course".

These are the main conditions of the reports. Note that at the bottom there is a text box called condition, with this text:

"c2 and c1 and c3"

Here you can define a logic condition, in this case, we don't need to edit this condition but you can create complex expressions like:

(c1 and c2) or (c4 and c3)

'''Adding Ordering'''

Click on the Ordering Tab.

Add a ordering named "User field ordering".

Choose the column "Lastname" and the ordering "ASC" (Ascending).

'''Adding Filters'''

Click on the Filters Tab.

Add a filter named "User field filter".

Choose city.

'''Adding Permissions'''

Click on the Permissions Tab.

Choose "User field Value".

Choose the column "Country", and enter the value "ES".

Here you can add more permissions and a logic condition to be achieved.

'''Adding Calculations'''

Click on the Calculations tab.

Choose Sum.

Choose the column "User module actions".

'''Adding Plots'''

Click on the Plots tab.

Choose "Pie".

Choose the colum "City" as Name and Value.

Finally, add a few users in Moodle with the country Spain, and different cities, Madrid, Barcelona, Seville etc. and test the report.

You can download the report in differents formats (ods and xls), remember to check these options in the report page.

[[blocks/custom_reports/#Users_report | See screenshot]]

=== Creating a SQL Report ===

You can find a lot of SQL Reports here: [[ad-hoc contributed reports]]

Since this block supports Tim Hunt's CustomSQL Queries Reports, you can use any query.

Remember to add a "Time filter" if you are going to use reports with time tokens.

First of all, install the block.

Go to the course where the report will be created.

Add an instance of the Custom Reports block.

Click on "Manage reports".

Click on "Add report

Enter a name, description, choose "SQL" as Type of Report

The report will be saved and you redirect to the firs Tab named "Custom SQL"

Add this query (''Courses activity''):

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to Calculations Tab

Add a Sum calculation, choose the hits column

Go to Plot

Add a Pie graph, choosing coursename as Name and hits as value

So, here you have, a report with a Graph and calculations based on a SQL Query.

You can add a Course filter, is very easy:

Go to filters, choose Courses

Edit the Custom SQL query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Note that we are adding a token called: %%FILTER_COURSES:l.courseid%%

Go to View report, and you will see a Courses Filter, choose a Course and click on Add, here you have a report filtered.

You cand add also, and Starttime and endtime filter

Go to filters, choose Stard / End date filter

Go to Custom SQL tab, this is the new query:

<code sql>
SELECT COUNT(l.id) hits, l.course courseId, c.fullname coursename
FROM prefix_log l INNER JOIN prefix_course c ON l.course = c.id
%%FILTER_COURSES:l.course%%
%%FILTER_STARTTIME:l.time:>%% %%FILTER_ENDTIME:l.time:<%%
GROUP BY courseId
ORDER BY hits DESC
</code>

Go to View report, now you can filter by time also

[[blocks/custom_reports/#SQL_report | See screenshot]]

== Advanced options ==

=== Templates ===

You can customize the report output using a template.

Just enable the Template option in the same name tab.

This is an example html code for displaying a list of users:

Header:

<code html4strict>
<p align="center"><b>##reportname##</b></p>
<table width="60%" align="center">
<tr>
<td>
</code>

Record:

<code html4strict>
<table width="100%">
<tr>
<td><img src="http://yourmoodle.com/user/pix.php/[[id]]/f1.jpg"></td>
<td><h2>[[Firstname]] [[Lastname]]</h2>
City: [[City]]
</td>
</tr>
</table>
<br>
</code>

Footer:

<code html4strict>
</td>
<td valign="top">
##graphs##
<br /><br />
##exportoptions##
</td>
</table>
</code>

=== Embedded reports ===

A embedded report consists in a report's set of columns that are embeeded in other report.

You can embed a user report into a course report, in this case, the resulting rows will be expanded duplicating each row for each user.

Imaging you have a courses report, you can embed a user report, every row of the course report will be cloned for each user.

To embed a report just add a "Other report" column, a list of your reports will be showed.

Inside a course report you can embed a user report and the other way.

== Developers documentation ==

It's very easy to create new report types, components and plugins.

'''Report''': A report plugin is a folder located at /report.
This folder contains a .class.php file with the child - class of the report_base.

You only need to modify a few methos to add a new report type.
Please, take a look to any of the current reports. The SQL report is an example of a non-typical report,
meanwhile the users and courses reports are standard reports.

The best way to create a report is duplicate an existing one.

'''Component''': A component is part of a report, a component may be used by more than one report.
The main Component is the component Columns, that is used to add the columns of a report.

Others components are filters, permissions, plot, calculations..

The best way to create a component is duplicate an existing one.

'''Plugin''': A plugin is a component module. The component column has a few of plugins (coursefield, userfield, etc..)
A plugins works usually for an unique report, but there are plugins that works for more than one report.
The best way to create a plugin is duplicate an existing one.

== Credits ==

Juan Leyva [http://moodle.org/user/view.php?id=49568&course=1 Moodle profile]

[http://twitter.com/jleyvadelgado Follow me in Twitter]

[[Category:Contributed code]]

== Screenshots ==

=== Users report ===
[[Image:block_custom_reports_sample_user_report.png|600px]]

=== SQL report ===
[[Image:block_custom_reports_sample_sql_report.png|600px]]

== See Also ==

CONTRIB-2386

[http://tracker.moodle.org/browse/CONTRIB/component/10753 Block: Configurable report] Tracker component

[[es:blocks/configurable_reports/]]

Development talk:Developer FAQ

2010-10-05T11:19:40Z

Libertymoodle: /* Book question */

The link "the documentation for datalib.php" appears to be broken. I believe that it should link to http://phpdocs.moodle.org/moodlecore/_lib---datalib.php.html instead of http://moodle.sourceforge.net/dhawes-phpdoc/moodlecore/_lib_datalib_php.html I'm not sure though because the file is empty. Hopefully someone else knows now to fix this.

===Is there any information on creating a new module or plugin?===
This section contains a link to the 'Moodle 1.9 Extension Development' book by Jonathan Moore and Michael Churchward. Is this book still relevant to Moodle 2 or does Moodle 2 make it out-of-date? In other words, can you use it to develop modules or plugins for Moodle 2, considering that Moodle 2 is such a big upgrade and so much of the Moodle 2 core code has changed significantly?
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 11:19, 5 October 2010 (UTC)

Installing Oracle for PHP

2010-09-29T09:25:47Z

Libertymoodle: /* New Related links */

* http://www.oracle.com/technology/pub/notes/technote_php_instant.html
* http://moodle.org/mod/forum/discuss.php?d=65488#p308002 (with attached html document)
* http://es.php.net/oci8

----

'''Important Note:''' Don't forget to enable this variable in your php.ini (or .htaccess) file:

(else, all your data will be escaped following MySQL rules, that are incorrect for Oracle)

magic_quotes_sybase = On

== Broken versions of OCI8 driver ==

PHP v5.2.4 (and perhaps v5.2.3 as well) have shipped with a bug in the OCI8 driver that leaks statement handles. The version of the OCI8 driver with the bug is v1.2.4. Possible workarounds:

* Upgrade to PHP v5.2.5 or later
* Downgrade to PHP v5.2.1 (reported to work)
* Downgrade only the oci8 driver to the one included in PHP 5.2.1 (it worked for us -- iarenaza)
* If you are on linux and/or can compile PECL extensions, install an older OCI8 driver (v1.2.3 seems to work) from the PECL repository http://pecl.php.net/package/oci8

More information at
* http://bugs.php.net/bug.php?id=42496 -- tracking the PHP OCI8 bug
* http://tracker.moodle.org/browse/MDL-11429 -- diagnostics on the Moodle side

== Installing Moodle on Windows with Oracle Express Edition ==

=== Introduction ===
This section explains how to install Moodle with Oracle Express Edition on Windows. I'm using it for '''debugging''' purpose. It's definitively not a production environment. The goal is to setup easily and quickly a Moodle/Windows/Oracle environment.

=== Install Oracle ===
Download Oracle Express Edition on [http://www.oracle.com/technology/products/database/xe/index.html Oracle web site].<br />
You will also need the Instant client [http://www.oracle.com/technology/software/tech/oci/instantclient/htdocs/winsoft.html from here] (free account sign up needed). Copy everything from the unzipped folder into apache/bin. <br />
Install both.<br />
Access to the oracle console (http://127.0.0.1:8080/apex). Login: SYS Password: the_one_you_entered_during_the_installation<br />
Create a new user and give it all rights (including DBA).<br />
Note: Oracle Express Edition 10g is limited at one database called 'XE'.

=== Set up your oracle extension ===
This document does not explain how to setup apache/php for Oracle. You can have more information on [http://www.oracle.com/technology/tech/php/htdocs/php-oracle-tutorial.html Oracle Documentation]. On my own machine I used my WAMP installation ([http://www.en.wampserver.com/ Wampserver 2.0]) which allowed me to activate all oracle extensions in few clicks (php_oci8, php_oracle, php_pdo_oci, php_pdo_oci8).

=== Install Moodle ===
On the database setup page:<br />
Driver: Oracle oci8<br />
Host: empty the field<br />
Database: //localhost:1521/XE<br />
User: the user that you created<br />
Password: the password you gave to the user<br />

== Related links ==
* [http://lewiscarr.co.uk/node/4 Installing ORACLE drivers with PHP]
*[[Installing MSSQL for PHP]]
*[[PHP]]
*[http://moodle.org/mod/forum/discuss.php?d=134729#p588963 Can i install Moodle with Oracle database]
*[http://moodle.org/mod/forum/discuss.php?d=65488 Who uses Oracle]
*[https://docs.moodle.org/en/Step-by-step_Install_Guide_for_Solaris_10_with_Oracle_10 Step by step Install Guide for Solaris 10 with Oracle 10]
*[http://learningischange.com/2009/05/29/install-moodle-on-an-oracle-database-in-25-minutes-or-less/ Install Moodle on an Oracle Database (in 25 minutes or less)]. The related Using Moodle forum discussion is [http://moodle.org/mod/forum/discuss.php?d=124629 here].
*[http://www.mguhlin.org/2009/05/moodle-on-oracle-database.html Moodle on Oracle Database] discussion on Miguel Guhlin's blog

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

admin/environment/php extension/intl

2010-09-14T14:08:51Z

Libertymoodle: /* Formatting */

The Internationalization extension (Intl) is a wrapper for the ICU library, a set of C/C++ and Java libraries that provide Unicode and Globalization support for software applications. It enables PHP programmers to perform UCA-conformant collation and date/time/number/currency formatting in their scripts.

To enable this extension add the following line to your php.ini file:

<code>
extension=php_intl.dll
</code>

And then set the ''intl.default_locale'' and ''intl.error_level'' directives in your php.ini file.

<code>
[intl]

intl.default_locale = en_utf8

intl.error_level = E_WARNING
</code>

The ''intl.error_level'' directive is optional.

==See also==

[http://www.php.net/manual/en/intro.intl.php INTL Introduction]

[http://www.php.net/manual/en/book.intl.php PHP Internationalization Functions]

[https://docs.moodle.org/en/Table_of_locales Table of locales] lists the locales that you can use.

admin/environment/php extension/intl

2010-09-14T14:03:31Z

Libertymoodle: /* Typos */

The Internationalization extension (Intl) is a wrapper for the ICU library, a set of C/C++ and Java libraries that provide Unicode and Globalization support for software applications. It enables PHP programmers to perform UCA-conformant collation and date/time/number/currency formatting in their scripts.

To enable this extension add the following line to your php.ini file:

<code>
extension=php_intl.dll
</code>

And then set the ''intl.default_locale'' and ''intl.error_level'' directives in your php.ini file.

The ''intl.error_level'' directive is optional.

<code>
[intl]

intl.default_locale = en_utf8

intl.error_level = E_WARNING
</code>

==See also==

[http://www.php.net/manual/en/intro.intl.php INTL Introduction]

[http://www.php.net/manual/en/book.intl.php PHP Internationalization Functions]

[https://docs.moodle.org/en/Table_of_locales Table of locales] lists the locales that you can use.