MoodleDocs - User contributions [en]

Universal Office Converter (unoconv)

2016-07-15T04:56:24Z

Lameze: /* Installing unoconv on Windows */

{{Environment}}
==What is unoconv?==

"unoconv" is a command line program that is used to convert between different office document file formats. It uses an instance of [http://libreoffice.org LibreOffice] to do the conversion and is used by the [[Assignment activity]] to convert documents to pdf so that they can be annotated. If unoconv is not installed - the only impact is that the assignment activities will only allow annotations when students upload a pdf document.

The steps required to install unoconv are different depending on the operating system that you have installed Moodle on.

== Installing unoconv on Linux ==
The required version of unoconv is at least 0.7. Depending on your flavour of linux, this may be available in your package manager and you can install it directly with:

===Ubuntu 16.04 LTS===

<pre>
apt-get install unoconv
</pre>

If your package manager contains an older version of the package, you will have to find a newer version and install it manually ([https://packages.debian.org/stretch/unoconv Debian Testing]). Unoconv itself is just a python script, so it has few dependencies.

Potential problems:
* On some systems the apache user home directory is set to a non existent folder. This can cause unoconv to fail. There are 2 solutions to this - one is to make a (writable) home directory for the apache user (like /home/www-data). The other is to run a unoconv listener (described below) as another user other than the apache user (someone with a valid, writable home directory).
* If you are still running 14.04LTS then unoconv won't work as shipped. This might not be the most efficient route but it worked by first installing unoconv (version 0.6) from the package manager as above. You will then need to grab unoconv 0.7 from Github (https://github.com/dagwieers/unoconv), then upgrade to the latest libreoffice using the PPA (https://launchpad.net/~libreoffice/+archive/ubuntu/ppa). Point moodle at the Github version of unoconv. You need to modify the Python unoconv file by changing 'python' in the first line to 'python3'. You also need to change the permissions on the directory /var/www so that the user www-data can write to it (www-data needs to write to its home directory which it cannot do by default).

===CentOS / RedHat===
<pre>
yum install openoffice*
yum install libreoffice-pyuno
git clone https://github.com/dagwieers/unoconv.git
cd unoconv
# copy
cp unoconv /usr/bin
# or link unoconv to /usr/bin
ln -s ./unoconv /usr/bin/unoconv
</pre>
Make sure it is properly configured:
http://your-moodle/admin/search.php?query=unoconv

== Installing unoconv on OS X ==
Download and install LibreOffice for Mac. Unfortunately - newer versions of LibreOffice are not currently compatible with unoconv for mac and you will have to install LibreOffice 4.2 (Direct download link - https://downloadarchive.documentfoundation.org/libreoffice/old/4.2.5.2/mac/x86_64/LibreOffice_4.2.5.2_MacOS_x86-64.dmg).

Get the latest version of the unoconv python script. One way to do this is with http://brew.sh/ brew.
<pre>
brew install unoconv
</pre>

If you haven't done it already - install ghostscript. One way to install ghostscript is also with http://brew.sh/ brew
<pre>
brew install ghostscript
</pre>

Set the paths to unoconv and ghostscript in Moodle (''Site administration > Server > System paths''). If you used brew, they will both be installed to /usr/local/bin.

LibreOffice needs write access to the current users home directory to create some temporary files. When unoconv is run as the webserver user (_www) it does not normally have this permission.

There are some ways to get around this - one way is just to give the "_www" user write access to /Library/WebServer.

Another solution is to convince LibreOffice that this users home directory is somewhere else. This can be done by inserting this code into the top of the unoconv python script.
Code to insert:
<pre>
# Set home to a writable folder.
os.environ['HOME'] = '/tmp/'
</pre>

This needs to be inserted at line 36 immediately after the line "exitcode = 0"

== Installing unoconv on Windows ==
Download and install LibreOffice for windows.

Download the latest version of the unoconv script from https://github.com/dagwieers/unoconv/releases (download the zip version).

From the downloaded zip file - extract the one file "unoconv-0.7\unoconv" (no file extension). This is the unoconv script - none of the other files in the package are required.

Rename the downloaded script to C:\unoconv\unoconv.py

Create a batch file C:\unoconv\unoconv.bat with these contents:

<pre>
@"C:\Program Files\LibreOffice 5\program\python.exe" c:\unoconv\unoconv.py %*
</pre>

Set paths in Moodle.

Login as admin and go to ''Site administration > Server > System paths''

Set pathtogs setting to your ghostscript installation binary, (C:\gs\bin\gswin32.exe)

Set pathtounoconv to the batch file created above (C:\unoconv\unoconv.bat)

Test ghostscript and unoconv are working correctly in the admin test pages "Site administration > Plugins > Activity modules > Assignment > Feedback plugins > Annotate PDF".

== Run a unoconv listener ==
Unoconv utilises a client/server process when converting documents. By default, when there is no running server process - each time unoconv runs it will start a server process, send its request and shut down the server process when the request is complete. The drawback of this mode is that if 2 requests are submitted simultaneously - this can cause the first request to shutdown the server process when the second request is still in progress - and the second conversion request fails. A more robust way to configure unoconv is to start a server process at boot time, and/or run a script to monitor it and restart it if it crashes.

To start a unoconv listener at boot time - you need a start up script. Different operating systems and Linux distributions use different startup scripts - but here are some examples of startup scripts for different systems.

[[mod/assign/feedback/editpdf/testunoconv/upstart | Upstart script for Ubuntu based systems]]

[[mod/assign/feedback/editpdf/testunoconv/launchd | Launchd script for OS X]]

[[mod/assign/feedback/editpdf/testunoconv/initd | Init script for Debian]]

== Offload processing to a different server ==
Processing office documents can put increased load on your webserver, which may impact on the responsiveness of your site. If you are installing unoconv on a large site you may want to consider running unoconv on a server that is not also serving web requests.

How to do this:

Install unoconv on each webservers and the remote server following the installation instructions above.

Make sure unoconv is started at boot time on the remote server with the "--listener" argument and is monitored and restarted if it exits (see Debian init script for an example of how to do this).

Open the firewall port 2002 between the moodle webservers and the machine running unoconv.

Share the moodle data root between the webservers and the machine running unoconv. This folder must be mounted at the same path on all servers.

Install a wrapper for unoconv on the webservers that forwards the requests to the remote server. Example:
<pre>
#!/bin/bash
# Wrapper script for unoconv to forward processing.
# Install to /usr/bin/unoconv-remote with 755 permissions
/usr/bin/unoconv --server=<ip of remote server> "$@"
</pre>

Configure the path to unoconv in the Moodle admin settings to point to this wrapper script.

==Additional resources==
The unoconv [https://github.com/dagwieers/unoconv documentation] site has additional information on installation of unoconv and troubleshooting tips.

==See also==

* [https://moodle.org/mod/forum/discuss.php?d=335310 Is the unoconv installation a security risk?] forum discussion

[[Category:Site administration]]
[[Category:Assignment]]

[[es:mod/assign/feedback/editpdf/testunoconv]]

PHP

2016-03-29T02:15:21Z

Lameze:

{{Installing Moodle}}
PHP is the scripting language in which Moodle is developed. It is integrated with your web server. The web server detects php pages (by their extension) and sends them to PHP for execution. PHP must be installed and configured properly for Moodle to work effectively (or at all).

==PHP Settings==
Check these settings in your php.ini or .htaccess file (if you're using Apache). For settings which use ON/OFF as their values, you can substitute 1 for ON and 0 for OFF if you prefer. If you change php.ini, don't forget to restart the server.
* ''register_globals'' '''MUST''' be OFF - (Feature removed as of PHP 5.4. PHP 5.4 is a minimum requirement of Moodle 2.7)
* ''safe_mode'' needs to be OFF - (Feature removed as of PHP 5.4. PHP 5.4 is a minimum requirement of Moodle 2.7)
* ''memory_limit'' should be at least 64M (although some functions may not work if this low). 128M is recommended. Large systems may need an even higher setting.
* ''session.save_handler'' needs to be set to FILES.
* ''magic_quotes_gpc'' should be OFF - (Feature removed as of PHP 5.4. PHP 5.4 is a minimum requirement of Moodle 2.7)
* ''magic_quotes_runtime'' needs to be OFF.
* ''file_uploads'' needs to be ON.
* ''session.auto_start'' needs to be OFF.
* ''session.bug_compat_warn'' needs to be OFF - (Feature removed as of PHP 5.4. PHP 5.4 is a minimum requirement of Moodle 2.7)
* The temp folder must be defined and writeable by your webserver user
* Check the error display/logging section. Make sure the settings are appropriate for your server use.
* ''post_max_size'' and ''upload_max_filesize'' restrict the maximum file size that can be uploaded.
* Check the ''[mail function]'' and database section (for your chosen database) to make sure they match your server configuration.

==HTTP_RAW_POST_DATA errors==
Some users are experiencing $HTTP_RAW_POST_DATA related errors, when establishing connection between MNET servers or making AJAX web services requests.
<pre>
Request for server name returned empty response

line 134 of /mnet/lib.php: call to debugging()
line 115 of /admin/mnet/peers.php: call to mnet_get_public_key()
</pre>

These errors are affecting users running moodle on PHP 5.6 version and it's a PHP bug on the '''always_populate_raw_post_data''' setting the default value to 0.

To avoid the error messages above, please change the value following setting on your php.in:
* '''always_populate_raw_post_data''' should be changed to '''-1'''.

For more information about this bug, see: https://bugs.php.net/bug.php?id=66763

==Finding the correct php.ini==
Sometimes it is not obvious where the php.ini file is located or you may even find more than one. To be certain run 'phpinfo' - see below. The path of the php.ini file is a few lines down in the top section.

Note that if you are using command-line (CLI) PHP for running cron (or anything else) it may be configured with a ''different'' php.ini file. To check, run the following command:
<pre>
php -i | grep php.ini
</pre>

==PHP Extensions and libraries==
The following PHP extensions are required or recommended (some, e.g. iconv, ctype and tokenizer are now included in PHP by default). Others will need to be installed or selected.
* The '''iconv''' extension is required.
* The '''mbstring''' extension is recommended.
* The '''curl''' extension is required (required for networking and web services).
* The '''openssl''' extension is recommended (required for networking and web services).
* The '''tokenizer''' extension is recommended.
* The '''xmlrpc''' extension is recommended (required for networking and web services).
* The '''soap''' extension is recommended (required for web services).
* The '''ctype''' extension is required.
* The '''zip''' extension is required.
* The '''gd''' extension is recommended (required for manipulating images).
* The '''simplexml''' extension is required.
* The '''spl''' extension is required.
* The '''pcre''' extension is required.
* The '''dom''' extension is required.
* The '''xml''' extension is required.
* The '''intl''' extension is recommended.
* The '''json''' extension is required.
* '''The appropriate extension for your chosen database is also required.'''

* Other PHP extensions may be required to support optional Moodle functionality, especially external authentication and/or enrolment (e.g. LDAP extension for LDAP authentication and the sockets extension for Chat server).

==Installing (missing) extensions==

This depends on how PHP was installed on your machine and what access you have. Here are some possibilities:
* If this is a hosted server you are likely to have to ask the administrator or hosting company.
* If PHP was compiled from source you will need to recompile, changing the 'configure' settings - see [[Compiling PHP from source]].
* If it was installed using packages (typically Linux) you can install the required package (see your Linux distribution's documentation)
* If you are using Windows you just need to uncomment the appropriate DLL files in php.ini

After making any changes or additions, don't forget to re-start your web server.

== .htaccess files ==

If you don't have access to the php.ini file or there are conflicting requirements with other PHP applications on the same server you may be able to change PHP settings in an .htaccess file. This should be placed in the 'root' of your Moodle installation (i.e. the same place as the config.php file).

'''The file isn't always called .htaccess and may not work at all. Contact your server administrator to be sure'''

Settings are made by adding lines in one of two formats:
* php_value ''name value''
* php_flag ''name on/off''

Examples:
* '''php_value memory_limit 128M'''
* '''php_flag register_globals off'''

==PHP info==

The phpinfo display contains information about the configuration of your PHP installation. This is useful for checking:
* that your PHP installation meets Moodle's system requirements.
* the values that are currently applied to your server's PHP install, e.g. File upload limits
* that you have installed the required modules needed for Moodle to work, e.g. the LDAP module for LDAP authentication.

=== Displaying phpinfo in Moodle===

An administrator can find PHP info in ''Settings > Site administration > Server > PHP info''.

=== Displaying phpinfo outside of Moodle ===

To view the phpinfo information:
* Create a file called info.php using your text editor, containing this single line:

<code php>
<?php phpinfo(); ?>
</code>

* Save this file as info.php
* Upload this file into the root web accessible folder on your server.
* Now open this file in your browser. For example <nowiki>http://<server-name>/info.php</nowiki>.

==See also==

*[[Compiling PHP from source]]
* [https://docs.moodle.org/dev/Moodle_and_PHP7 Moodle and PHP7] in the developers documentation
*http://www.php.net/ - the PHP web site
*http://php.iis.net/ - Microsoft PHP Installer for IIS

[[de:PHP-Versionen für Moodle]]
[[es:PHP]]

CAS server (SSO) authentication

2015-11-03T07:00:16Z

Lameze:

{{Authentication}}
Location: Settings link in ''Settings > Site administration > Plugins > Authentication > Manage authentication''

== Overview ==

CAS is "Single Sign-on for the Web" and is developed by [http://www.ja-sig.org/products/cas/ JA-SIG] in an open-source, collaborative manner. CAS is very beneficial in environments where a number of different web applications share a set of common users. If all the web applications were "CASified" a user would log in once and would then be able to move between the various web applications without ever having to present authentication credentials again. CAS is similar to the [[Shibboleth]] authentication mechanism, but it is vastly simpler to set up and lacks a number of broader features like federated trust and authorization infrastructure.

The details for how CAS works are [http://www.jasig.org/cas/cas2-architecture well documented], but CAS essentially works by configuring a web application (moodle.example.com) to not do authentication itself, but to instead forward unauthenticated users to a "CAS Server" (cas.example.com) which will then return an authentication token to the original web application (moodle.example.com). Moodle can extract the username from the token and then use its internal authorization mechanisms (roles, enrollments, capabilities) and user attributes (name, picture, etc.). The advantage is that the moodle.example.com service never has to handle passwords and that users, once they've authenticated the first time, can move seamlessly to another web application without having to present their credentials again.

== Configuration ==

Assuming that you already have a working CAS server, configuration is fairly straightforward through the web interface.

One caveat for those converting from LDAP or other authentication mechanisms:

* For any user that you wish to authenticate with CAS but which already has been using Moodle, and thus has an entry in the Moodle database, you will need to change the value of the "auth" field for the user in the mdl_user table. So, if they used LDAP before, but now you wish for them to use CAS and their username is "foobar" you'll need to edit the database with some SQL something like: <code>UPDATE mdl_user SET auth='cas' where auth='ldap' and username='foobar';</code> Without this change the user will constantly be presented with a failed login message, but otherwise no clue as to why login failed even though their credentials were accepted by the CAS server.

===Setting up regular automatic synchronisation using schedule task===
There is a default scheduled task to synchronize your moodle with a CAS server. The task '''CAS users sync job (\auth_cas\task\sync_task)''' is responsible for create, update user information, suspend and delete all CAS accounts automatically.
The scheduled task can be enabled and configured on Site Administration > Server > Scheduled tasks by clicking on the gear icon. Select the desired frequency of running and enable the task, un-checking the Disabled checkbox.
It is important, however, to make sure that all of the above CAS settings are working properly before you try this, as well as backing up your database and moodledata folders. Poor CAS configuration could lead to users being wrongly deleted.

[[fr:Utiliser un serveur CAS (SSO)]]
[[de:CAS-Server]]
[[es:Servidor CAS (SSO)]]

LDAP authentication

2015-11-03T06:19:23Z

Lameze: /* Setting up regular automatic synchronisation using schedule task */

{{Authentication}}
Location: Settings link in ''Site administration > Plugins > Authentication > Manage authentication''

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 > Plugins > 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:LDAPserversettings.png|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
|-
| Don't cache 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. So unless you need something special, you don't need to fill this in.

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 (and have to, if you intend to use NTLM SSO) use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.

'''Correction''': With MS-AD '''sAMAccountName''' should be used anyway. With default value ('''cn''') AD users will have to login with full name / password (Username: '''John Doe''', Password: '''john's_pass'''). If you want to enable your users to login with domain username instead (Username: '''johnd''' Password: '''john's_pass'''), you should use '''sAMAccountName'''. Sadly, but logging in with DOMAIN\user or user@domain.com will not work anyway.

Note: You may wish to consider allowing extended characters in usernames in ''Administration > Site administration > Security > [[Site policies]]''.
|-
| 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. So unless you need something special, you don't need to fill this in.

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. So unless you need something special, you don't need to fill this in.
|-
| 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. So unless you need something special, you don't need to fill this in.
* If you leave it blank, the default value based on the ''User type'' selected above will be used (see below)
* 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.

'''Note''': In the last case, that feature can be used on interactive logins,

Here are the default values for each of the ''ldap_user_type'' values:
* '''(objectClass=user)''' for Novel eDirectory
* '''(objectClass=posixAccount)''' for RFC-2037 and RFC-2037bis
* '''(objectClass=sambaSamAccount)''' for SAMBA 3.0.x LDAP extension
* '''(objectClass=user)''' for MS-AD
* '''(objectClass=*)''' for Default
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
| '''NOTE: This setting is only used when creating your users with the LDAP sync users task. It's not used if your users are created as part of their first login to moodle'''.

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.

As you don't want your users to change their passwords in their first login, leave this set to ''No''
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its 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 them a number of days before the password expires. When the password has expired, a "Your password has expired" message is displayed, and if the user is able to change their password from Moodle, they are offered the option to do so.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.
|-
| 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. So unless you need something special, you don't need to fill this in.
|-
| 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.

So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

So you don't need to fill this in.
|}

[[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.

Only Novell eDirectory and MS-AD can create users externally (prior to Moodle 2.x). From Moodle 2.0 on, you can also create users in RFC-2307 compliant servers.
|-
| 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'''

This setting is optional
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

This setting is optional
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

This setting is optional
|-
| 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).

This setting is optional
|-
| 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).

This setting is optional
|-
| Language
| '''preferredLanguage'''

This setting is optional
|-
| Description
| '''description'''

This setting is optional
|-
| Webpage
| This setting is optional
|-
| ID Number
|

This setting is optional
|-
| Institution
|

This setting is optional
|-
| 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).

This setting is optional
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

This setting is optional
|-
| 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.

This setting is optional
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

This setting is optional
|}

=====Custom User profile fields=====
Custom Profile Fields are now supported.

Any user profile fields created in ''Site administration > Users > Accounts > User profile fields'' should now automatically show up at the end of the Data mapping field list after the '''Address''' field. See example: [[File:ldapcustomuserprofilefields.jpg]]

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using schedule task===
There is a default scheduled task to synchronize your moodle with a LDAP server. The task '''LDAP users sync job (\auth_ldap\task\sync_task)''' is responsible for create, update user information, suspend and delete all LDAP accounts automatically.
The scheduled task can be enabled and configured on Site Administration > Server > Scheduled tasks by clicking on the gear icon. Select the desired frequency of running and enable the task, un-checking the Disabled checkbox.
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 over 1000 users in each LDAP container, this is because by default some LDAP stores such as MS AD only send back 1000 users at a time and PHP versions prior to 5.4 did not implement paged support for LDAP results. If you upgrade to PHP 5.4 or higher then Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions [http://support.microsoft.com/kb/315071 here] to set the Active Directory 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.

===Making your LDAP directory connection resilient===
* 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, if using eDirectory you would need to ensure your servers have viability of all relevant tree partitions, or if using Active Directory the servers are holding the same information you need though replication - see notes on a multi-domain environment if this applies.

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 a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more then one domain you will want to configure Moodle to look at your Global Catalog server. Specifically your top level domain Global Catalog server. Here is a simple example of this kind of Active Directory layout:

my.domain.ca (Root AD Domain)
| - dc1.my.domain.ca (Domain Controller)
| - dc2.my.domain.ca (Domain Controller)
|
| - - students.my.domain.ca (Sub AD Domain)
| - - - dc1.students.my.domain.ca (Domain Controller)
| - - - dc2.students.my.domain.ca (Domain Controller)
|
| - - faculty.my.domain.ca (Sub AD Domain)
| - - - dc1.faculty.my.domain.ca (Domain Controller)
| - - - dc2.faculty.my.domain.ca (Domain Controller)

In this example we have our top level domain (my.domain.ca) and two sub-domains. One sub-domain is for faculty accounts (faculty.my.domain.ca) and the other is for student accounts (students.my.domain.ca). Listed under each of those are two domain controllers.

Using the above example you'll want to use the following for accessing the Global Catalog over SSL:

ldaps://my.domain.ca:3269/

If you prefer to access your global catalog over a non-SSL connection you'll want to use:

ldap://my.domain.ca:3268/

We found if you didn't configure things this way you'd get errors like:

[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_search() [<a href='function.ldap-search'>function.ldap-search</a>]: Search: Partial results and referral received in /xxx/xxx/moodle20/lib/ldaplib.php on line 241, referer: http://moodle.my.domain.ca/moodle20/login/index.php
[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_first_entry(): supplied argument is not a valid ldap result resource in /xxx/xxx/moodle20/lib/ldaplib.php on line 248, referer: http://moodle.my.domain.ca/moodle20/login/index.php

===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 over SSL)===
====Enabling LDAPS on your directory server====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on your Moodle server====
Enabling LDAPS on your server can be tricky and often it is hard to pinpoint where things are going wrong. There are also differences between Windows and Linux and even different versions and distributions of Linux.

'''If you have not done so already you will need to decide upon your approach to establishing an SSL connection to your directory server:'''

* SSL connection with unverified self-signed certificate.

You can generate your own SSL certificate, and then instruct your Moodle server to ignore the fact that it is not valid. This setup is not as secure as others since you cannot be sure the server you are connecting to is not fake.

* SSL connection with trusted self-signed certificate.

You can generate your own SSL certificate on your directory server, and then specifically trust this certificate by installing it on your Moodle server.

* SSL connection with verified certificate from Internet-trusted certificate authority (CA)

In this approach the LDAP server has an installed certificate from an Internet-based CA, this means that your directory server would have an Internet address & host name. Your Moodle server must be trusting the certificate authority and have Internet access. This approach is not often used as it usually incurs a cost for the certificate, and it requires your directory server and Moodle server to be exposed to the Internet.

==Linux servers==
'''These instructions are for establishing a link using a trusted self-signed certificate.'''

''Note: written for a Red Hat Enterprise Linux 6 server, other Linux distributions may differ, especially in the location of the SSL certificates and OpenLdap config files, but the core principals are the same.''

To check that your directory server is online and accepting SSL connections on your LDAPS port (636), you can use try:
openssl s_client –connect <ldap server ip address>:636

Get your directory server’s certificate (.crt) and upload to Moodle server's ssl certificate directory, on RHEL6 this is at '''/etc/ssl/certs'''

Convert your ‘DER’ X509 certificate into a ‘PEM’ public key certificate.
openssl x509 -in my_server_certificate.cer -inform DER -out my_server_certificate.pem -outform PEM

Create certificate hashes using c_rehash
c_rehash
''If c_rehash is not installed install with: yum install /usr/bin/c_rehash''

Ensure you are able to access your LDAPS server by a DNS name, this may mean adding an entry to your host file (/etc/hosts)
<ldap server ip address> my_server.mydomain.school

Verify your certificate to check that it is installed correctly
openssl verify -verbose -CApath /etc/ssl/certs /etc/ssl/certs/my_server_certificate.pem
/etc/ssl/certs/my_server_certificate.pem: OK

You should now be able to connect to your LDAPS server over SSL without any errors
openssl s_client –connect <ldap server DNS name>:636

Edit your OpenLDAP config, on RHEL6 this is located at '''/etc/openldap/ldap.conf'''
# Define location of a CA Cert
TLS_CACERT /etc/ssl/certs/my_server_certificate.pem
TLS_CACERTDIR /etc/ssl/certs

Finally, you may or may not need to restart Apache, before configuring Moodle to use ldaps://<server DNS name>
httpd -k restart

==Windows servers==
'''These instructions are for establishing a link using an unverified self-signed certificate'''

You can tell PHP's OpenLDAP extension to disable SSL server certificate checking to do this you must create a directory called ''''C:\OpenLDAP\sysconf\'''' In this directory, create a file called ''ldap.conf'' with the following content:

TLS_REQCERT never

''(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])''

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==

=== 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

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[de:LDAP-Server]]

LDAP authentication

2015-11-03T06:18:40Z

Lameze: /* Force change password */

{{Authentication}}
Location: Settings link in ''Site administration > Plugins > Authentication > Manage authentication''

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 > Plugins > 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:LDAPserversettings.png|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
|-
| Don't cache 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. So unless you need something special, you don't need to fill this in.

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 (and have to, if you intend to use NTLM SSO) use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.

'''Correction''': With MS-AD '''sAMAccountName''' should be used anyway. With default value ('''cn''') AD users will have to login with full name / password (Username: '''John Doe''', Password: '''john's_pass'''). If you want to enable your users to login with domain username instead (Username: '''johnd''' Password: '''john's_pass'''), you should use '''sAMAccountName'''. Sadly, but logging in with DOMAIN\user or user@domain.com will not work anyway.

Note: You may wish to consider allowing extended characters in usernames in ''Administration > Site administration > Security > [[Site policies]]''.
|-
| 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. So unless you need something special, you don't need to fill this in.

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. So unless you need something special, you don't need to fill this in.
|-
| 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. So unless you need something special, you don't need to fill this in.
* If you leave it blank, the default value based on the ''User type'' selected above will be used (see below)
* 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.

'''Note''': In the last case, that feature can be used on interactive logins,

Here are the default values for each of the ''ldap_user_type'' values:
* '''(objectClass=user)''' for Novel eDirectory
* '''(objectClass=posixAccount)''' for RFC-2037 and RFC-2037bis
* '''(objectClass=sambaSamAccount)''' for SAMBA 3.0.x LDAP extension
* '''(objectClass=user)''' for MS-AD
* '''(objectClass=*)''' for Default
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
| '''NOTE: This setting is only used when creating your users with the LDAP sync users task. It's not used if your users are created as part of their first login to moodle'''.

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.

As you don't want your users to change their passwords in their first login, leave this set to ''No''
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its 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 them a number of days before the password expires. When the password has expired, a "Your password has expired" message is displayed, and if the user is able to change their password from Moodle, they are offered the option to do so.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.
|-
| 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. So unless you need something special, you don't need to fill this in.
|-
| 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.

So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

So you don't need to fill this in.
|}

[[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.

Only Novell eDirectory and MS-AD can create users externally (prior to Moodle 2.x). From Moodle 2.0 on, you can also create users in RFC-2307 compliant servers.
|-
| 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'''

This setting is optional
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

This setting is optional
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

This setting is optional
|-
| 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).

This setting is optional
|-
| 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).

This setting is optional
|-
| Language
| '''preferredLanguage'''

This setting is optional
|-
| Description
| '''description'''

This setting is optional
|-
| Webpage
| This setting is optional
|-
| ID Number
|

This setting is optional
|-
| Institution
|

This setting is optional
|-
| 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).

This setting is optional
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

This setting is optional
|-
| 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.

This setting is optional
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

This setting is optional
|}

=====Custom User profile fields=====
Custom Profile Fields are now supported.

Any user profile fields created in ''Site administration > Users > Accounts > User profile fields'' should now automatically show up at the end of the Data mapping field list after the '''Address''' field. See example: [[File:ldapcustomuserprofilefields.jpg]]

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using schedule task===
There is a default scheduled task to synchronize your moodle with a LDAP server. The task '''LDAP users sync job \auth_ldap\task\sync_task''' is responsible for create, update user information, suspend and delete all LDAP accounts automatically.
The scheduled task can be enabled and configured on Site Administration > Server > Scheduled tasks by clicking on the gear icon. Select the desired frequency of running and enable the task, un-checking the Disabled checkbox.
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 over 1000 users in each LDAP container, this is because by default some LDAP stores such as MS AD only send back 1000 users at a time and PHP versions prior to 5.4 did not implement paged support for LDAP results. If you upgrade to PHP 5.4 or higher then Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions [http://support.microsoft.com/kb/315071 here] to set the Active Directory 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.

===Making your LDAP directory connection resilient===
* 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, if using eDirectory you would need to ensure your servers have viability of all relevant tree partitions, or if using Active Directory the servers are holding the same information you need though replication - see notes on a multi-domain environment if this applies.

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 a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more then one domain you will want to configure Moodle to look at your Global Catalog server. Specifically your top level domain Global Catalog server. Here is a simple example of this kind of Active Directory layout:

my.domain.ca (Root AD Domain)
| - dc1.my.domain.ca (Domain Controller)
| - dc2.my.domain.ca (Domain Controller)
|
| - - students.my.domain.ca (Sub AD Domain)
| - - - dc1.students.my.domain.ca (Domain Controller)
| - - - dc2.students.my.domain.ca (Domain Controller)
|
| - - faculty.my.domain.ca (Sub AD Domain)
| - - - dc1.faculty.my.domain.ca (Domain Controller)
| - - - dc2.faculty.my.domain.ca (Domain Controller)

In this example we have our top level domain (my.domain.ca) and two sub-domains. One sub-domain is for faculty accounts (faculty.my.domain.ca) and the other is for student accounts (students.my.domain.ca). Listed under each of those are two domain controllers.

Using the above example you'll want to use the following for accessing the Global Catalog over SSL:

ldaps://my.domain.ca:3269/

If you prefer to access your global catalog over a non-SSL connection you'll want to use:

ldap://my.domain.ca:3268/

We found if you didn't configure things this way you'd get errors like:

[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_search() [<a href='function.ldap-search'>function.ldap-search</a>]: Search: Partial results and referral received in /xxx/xxx/moodle20/lib/ldaplib.php on line 241, referer: http://moodle.my.domain.ca/moodle20/login/index.php
[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_first_entry(): supplied argument is not a valid ldap result resource in /xxx/xxx/moodle20/lib/ldaplib.php on line 248, referer: http://moodle.my.domain.ca/moodle20/login/index.php

===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 over SSL)===
====Enabling LDAPS on your directory server====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on your Moodle server====
Enabling LDAPS on your server can be tricky and often it is hard to pinpoint where things are going wrong. There are also differences between Windows and Linux and even different versions and distributions of Linux.

'''If you have not done so already you will need to decide upon your approach to establishing an SSL connection to your directory server:'''

* SSL connection with unverified self-signed certificate.

You can generate your own SSL certificate, and then instruct your Moodle server to ignore the fact that it is not valid. This setup is not as secure as others since you cannot be sure the server you are connecting to is not fake.

* SSL connection with trusted self-signed certificate.

You can generate your own SSL certificate on your directory server, and then specifically trust this certificate by installing it on your Moodle server.

* SSL connection with verified certificate from Internet-trusted certificate authority (CA)

In this approach the LDAP server has an installed certificate from an Internet-based CA, this means that your directory server would have an Internet address & host name. Your Moodle server must be trusting the certificate authority and have Internet access. This approach is not often used as it usually incurs a cost for the certificate, and it requires your directory server and Moodle server to be exposed to the Internet.

==Linux servers==
'''These instructions are for establishing a link using a trusted self-signed certificate.'''

''Note: written for a Red Hat Enterprise Linux 6 server, other Linux distributions may differ, especially in the location of the SSL certificates and OpenLdap config files, but the core principals are the same.''

To check that your directory server is online and accepting SSL connections on your LDAPS port (636), you can use try:
openssl s_client –connect <ldap server ip address>:636

Get your directory server’s certificate (.crt) and upload to Moodle server's ssl certificate directory, on RHEL6 this is at '''/etc/ssl/certs'''

Convert your ‘DER’ X509 certificate into a ‘PEM’ public key certificate.
openssl x509 -in my_server_certificate.cer -inform DER -out my_server_certificate.pem -outform PEM

Create certificate hashes using c_rehash
c_rehash
''If c_rehash is not installed install with: yum install /usr/bin/c_rehash''

Ensure you are able to access your LDAPS server by a DNS name, this may mean adding an entry to your host file (/etc/hosts)
<ldap server ip address> my_server.mydomain.school

Verify your certificate to check that it is installed correctly
openssl verify -verbose -CApath /etc/ssl/certs /etc/ssl/certs/my_server_certificate.pem
/etc/ssl/certs/my_server_certificate.pem: OK

You should now be able to connect to your LDAPS server over SSL without any errors
openssl s_client –connect <ldap server DNS name>:636

Edit your OpenLDAP config, on RHEL6 this is located at '''/etc/openldap/ldap.conf'''
# Define location of a CA Cert
TLS_CACERT /etc/ssl/certs/my_server_certificate.pem
TLS_CACERTDIR /etc/ssl/certs

Finally, you may or may not need to restart Apache, before configuring Moodle to use ldaps://<server DNS name>
httpd -k restart

==Windows servers==
'''These instructions are for establishing a link using an unverified self-signed certificate'''

You can tell PHP's OpenLDAP extension to disable SSL server certificate checking to do this you must create a directory called ''''C:\OpenLDAP\sysconf\'''' In this directory, create a file called ''ldap.conf'' with the following content:

TLS_REQCERT never

''(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])''

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==

=== 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

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[de:LDAP-Server]]

LDAP authentication

2015-11-03T06:17:38Z

Lameze: /* User lookup settings */

{{Authentication}}
Location: Settings link in ''Site administration > Plugins > Authentication > Manage authentication''

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 > Plugins > 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:LDAPserversettings.png|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
|-
| Don't cache 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. So unless you need something special, you don't need to fill this in.

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 (and have to, if you intend to use NTLM SSO) use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.

'''Correction''': With MS-AD '''sAMAccountName''' should be used anyway. With default value ('''cn''') AD users will have to login with full name / password (Username: '''John Doe''', Password: '''john's_pass'''). If you want to enable your users to login with domain username instead (Username: '''johnd''' Password: '''john's_pass'''), you should use '''sAMAccountName'''. Sadly, but logging in with DOMAIN\user or user@domain.com will not work anyway.

Note: You may wish to consider allowing extended characters in usernames in ''Administration > Site administration > Security > [[Site policies]]''.
|-
| 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. So unless you need something special, you don't need to fill this in.

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. So unless you need something special, you don't need to fill this in.
|-
| 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. So unless you need something special, you don't need to fill this in.
* If you leave it blank, the default value based on the ''User type'' selected above will be used (see below)
* 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.

'''Note''': In the last case, that feature can be used on interactive logins,

Here are the default values for each of the ''ldap_user_type'' values:
* '''(objectClass=user)''' for Novel eDirectory
* '''(objectClass=posixAccount)''' for RFC-2037 and RFC-2037bis
* '''(objectClass=sambaSamAccount)''' for SAMBA 3.0.x LDAP extension
* '''(objectClass=user)''' for MS-AD
* '''(objectClass=*)''' for Default
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
| '''NOTE: This setting is only used when creating your users with the cli/sync_users.php script. It's not used if your users are created as part of their first login to moodle'''.

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.

As you don't want your users to change their passwords in their first login, leave this set to ''No''
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its 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 them a number of days before the password expires. When the password has expired, a "Your password has expired" message is displayed, and if the user is able to change their password from Moodle, they are offered the option to do so.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.
|-
| 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. So unless you need something special, you don't need to fill this in.
|-
| 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.

So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

So you don't need to fill this in.
|}

[[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.

Only Novell eDirectory and MS-AD can create users externally (prior to Moodle 2.x). From Moodle 2.0 on, you can also create users in RFC-2307 compliant servers.
|-
| 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'''

This setting is optional
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

This setting is optional
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

This setting is optional
|-
| 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).

This setting is optional
|-
| 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).

This setting is optional
|-
| Language
| '''preferredLanguage'''

This setting is optional
|-
| Description
| '''description'''

This setting is optional
|-
| Webpage
| This setting is optional
|-
| ID Number
|

This setting is optional
|-
| Institution
|

This setting is optional
|-
| 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).

This setting is optional
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

This setting is optional
|-
| 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.

This setting is optional
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

This setting is optional
|}

=====Custom User profile fields=====
Custom Profile Fields are now supported.

Any user profile fields created in ''Site administration > Users > Accounts > User profile fields'' should now automatically show up at the end of the Data mapping field list after the '''Address''' field. See example: [[File:ldapcustomuserprofilefields.jpg]]

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using schedule task===
There is a default scheduled task to synchronize your moodle with a LDAP server. The task '''LDAP users sync job \auth_ldap\task\sync_task''' is responsible for create, update user information, suspend and delete all LDAP accounts automatically.
The scheduled task can be enabled and configured on Site Administration > Server > Scheduled tasks by clicking on the gear icon. Select the desired frequency of running and enable the task, un-checking the Disabled checkbox.
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 over 1000 users in each LDAP container, this is because by default some LDAP stores such as MS AD only send back 1000 users at a time and PHP versions prior to 5.4 did not implement paged support for LDAP results. If you upgrade to PHP 5.4 or higher then Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions [http://support.microsoft.com/kb/315071 here] to set the Active Directory 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.

===Making your LDAP directory connection resilient===
* 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, if using eDirectory you would need to ensure your servers have viability of all relevant tree partitions, or if using Active Directory the servers are holding the same information you need though replication - see notes on a multi-domain environment if this applies.

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 a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more then one domain you will want to configure Moodle to look at your Global Catalog server. Specifically your top level domain Global Catalog server. Here is a simple example of this kind of Active Directory layout:

my.domain.ca (Root AD Domain)
| - dc1.my.domain.ca (Domain Controller)
| - dc2.my.domain.ca (Domain Controller)
|
| - - students.my.domain.ca (Sub AD Domain)
| - - - dc1.students.my.domain.ca (Domain Controller)
| - - - dc2.students.my.domain.ca (Domain Controller)
|
| - - faculty.my.domain.ca (Sub AD Domain)
| - - - dc1.faculty.my.domain.ca (Domain Controller)
| - - - dc2.faculty.my.domain.ca (Domain Controller)

In this example we have our top level domain (my.domain.ca) and two sub-domains. One sub-domain is for faculty accounts (faculty.my.domain.ca) and the other is for student accounts (students.my.domain.ca). Listed under each of those are two domain controllers.

Using the above example you'll want to use the following for accessing the Global Catalog over SSL:

ldaps://my.domain.ca:3269/

If you prefer to access your global catalog over a non-SSL connection you'll want to use:

ldap://my.domain.ca:3268/

We found if you didn't configure things this way you'd get errors like:

[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_search() [<a href='function.ldap-search'>function.ldap-search</a>]: Search: Partial results and referral received in /xxx/xxx/moodle20/lib/ldaplib.php on line 241, referer: http://moodle.my.domain.ca/moodle20/login/index.php
[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_first_entry(): supplied argument is not a valid ldap result resource in /xxx/xxx/moodle20/lib/ldaplib.php on line 248, referer: http://moodle.my.domain.ca/moodle20/login/index.php

===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 over SSL)===
====Enabling LDAPS on your directory server====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on your Moodle server====
Enabling LDAPS on your server can be tricky and often it is hard to pinpoint where things are going wrong. There are also differences between Windows and Linux and even different versions and distributions of Linux.

'''If you have not done so already you will need to decide upon your approach to establishing an SSL connection to your directory server:'''

* SSL connection with unverified self-signed certificate.

You can generate your own SSL certificate, and then instruct your Moodle server to ignore the fact that it is not valid. This setup is not as secure as others since you cannot be sure the server you are connecting to is not fake.

* SSL connection with trusted self-signed certificate.

You can generate your own SSL certificate on your directory server, and then specifically trust this certificate by installing it on your Moodle server.

* SSL connection with verified certificate from Internet-trusted certificate authority (CA)

In this approach the LDAP server has an installed certificate from an Internet-based CA, this means that your directory server would have an Internet address & host name. Your Moodle server must be trusting the certificate authority and have Internet access. This approach is not often used as it usually incurs a cost for the certificate, and it requires your directory server and Moodle server to be exposed to the Internet.

==Linux servers==
'''These instructions are for establishing a link using a trusted self-signed certificate.'''

''Note: written for a Red Hat Enterprise Linux 6 server, other Linux distributions may differ, especially in the location of the SSL certificates and OpenLdap config files, but the core principals are the same.''

To check that your directory server is online and accepting SSL connections on your LDAPS port (636), you can use try:
openssl s_client –connect <ldap server ip address>:636

Get your directory server’s certificate (.crt) and upload to Moodle server's ssl certificate directory, on RHEL6 this is at '''/etc/ssl/certs'''

Convert your ‘DER’ X509 certificate into a ‘PEM’ public key certificate.
openssl x509 -in my_server_certificate.cer -inform DER -out my_server_certificate.pem -outform PEM

Create certificate hashes using c_rehash
c_rehash
''If c_rehash is not installed install with: yum install /usr/bin/c_rehash''

Ensure you are able to access your LDAPS server by a DNS name, this may mean adding an entry to your host file (/etc/hosts)
<ldap server ip address> my_server.mydomain.school

Verify your certificate to check that it is installed correctly
openssl verify -verbose -CApath /etc/ssl/certs /etc/ssl/certs/my_server_certificate.pem
/etc/ssl/certs/my_server_certificate.pem: OK

You should now be able to connect to your LDAPS server over SSL without any errors
openssl s_client –connect <ldap server DNS name>:636

Edit your OpenLDAP config, on RHEL6 this is located at '''/etc/openldap/ldap.conf'''
# Define location of a CA Cert
TLS_CACERT /etc/ssl/certs/my_server_certificate.pem
TLS_CACERTDIR /etc/ssl/certs

Finally, you may or may not need to restart Apache, before configuring Moodle to use ldaps://<server DNS name>
httpd -k restart

==Windows servers==
'''These instructions are for establishing a link using an unverified self-signed certificate'''

You can tell PHP's OpenLDAP extension to disable SSL server certificate checking to do this you must create a directory called ''''C:\OpenLDAP\sysconf\'''' In this directory, create a file called ''ldap.conf'' with the following content:

TLS_REQCERT never

''(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])''

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==

=== 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

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[de:LDAP-Server]]

LDAP authentication

2015-11-03T06:10:54Z

Lameze: /* Setting up regular automatic synchronisation using cron */

{{Authentication}}
Location: Settings link in ''Site administration > Plugins > Authentication > Manage authentication''

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 > Plugins > 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:LDAPserversettings.png|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
|-
| Don't cache 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. So unless you need something special, you don't need to fill this in.

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 (and have to, if you intend to use NTLM SSO) use '''sAMAccountName''' (the pre-Windows 2000 logon account name) if you need too.

'''Correction''': With MS-AD '''sAMAccountName''' should be used anyway. With default value ('''cn''') AD users will have to login with full name / password (Username: '''John Doe''', Password: '''john's_pass'''). If you want to enable your users to login with domain username instead (Username: '''johnd''' Password: '''john's_pass'''), you should use '''sAMAccountName'''. Sadly, but logging in with DOMAIN\user or user@domain.com will not work anyway.

Note: You may wish to consider allowing extended characters in usernames in ''Administration > Site administration > Security > [[Site policies]]''.
|-
| 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. So unless you need something special, you don't need to fill this in.

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. So unless you need something special, you don't need to fill this in.
|-
| 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. So unless you need something special, you don't need to fill this in.
* If you leave it blank, the default value based on the ''User type'' selected above will be used (see below)
* 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.

'''Note''': In the last case, there are two different places where that feature can be used:
* on interactive logins,
* on bulk account syncing, via auth/ldap/cli/sync_users.php

Here are the default values for each of the ''ldap_user_type'' values:
* '''(objectClass=user)''' for Novel eDirectory
* '''(objectClass=posixAccount)''' for RFC-2037 and RFC-2037bis
* '''(objectClass=sambaSamAccount)''' for SAMBA 3.0.x LDAP extension
* '''(objectClass=user)''' for MS-AD
* '''(objectClass=*)''' for Default
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
| '''NOTE: This setting is only used when creating your users with the cli/sync_users.php script. It's not used if your users are created as part of their first login to moodle'''.

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.

As you don't want your users to change their passwords in their first login, leave this set to ''No''
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its 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 them a number of days before the password expires. When the password has expired, a "Your password has expired" message is displayed, and if the user is able to change their password from Moodle, they are offered the option to do so.

Current code only deals with Novell eDirectory LDAP server and MS-AD.

So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.
|-
| 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. So unless you need something special, you don't need to fill this in.
|-
| 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.

So unless you have Novell eDirectory server and want to allow gracelogin support, choose ''No'' here.
|-
| Grace login attribute
| This setting is currently not used in the code (and is specific to Novell eDirectory).

So you don't need to fill this in.
|}

[[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.

Only Novell eDirectory and MS-AD can create users externally (prior to Moodle 2.x). From Moodle 2.0 on, you can also create users in RFC-2307 compliant servers.
|-
| 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'''

This setting is optional
|-
| Surname
| The name of the attribute that holds the surname of your users in your LDAP server. This is usually '''sn'''.

This setting is optional
|-
| Email address
| The name of the attribute that holds the email address of your users in your LDAP server. This is usually '''mail'''.

This setting is optional
|-
| 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).

This setting is optional
|-
| 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).

This setting is optional
|-
| Language
| '''preferredLanguage'''

This setting is optional
|-
| Description
| '''description'''

This setting is optional
|-
| Webpage
| This setting is optional
|-
| ID Number
|

This setting is optional
|-
| Institution
|

This setting is optional
|-
| 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).

This setting is optional
|-
| Phone 1
| The name of the attribute that holds the telephone number of your users in your LDAP server. This is usually '''telephoneNumber'''.

This setting is optional
|-
| 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.

This setting is optional
|-
| Address
| The name of the attribute that holds the street address of your users in your LDAP server. This is usully '''streetAddress''' or '''street'.

This setting is optional
|}

=====Custom User profile fields=====
Custom Profile Fields are now supported.

Any user profile fields created in ''Site administration > Users > Accounts > User profile fields'' should now automatically show up at the end of the Data mapping field list after the '''Address''' field. See example: [[File:ldapcustomuserprofilefields.jpg]]

[[LDAP_authentication#Table of Contents|Table of Contents]]

===Setting up regular automatic synchronisation using schedule task===
There is a default scheduled task to synchronize your moodle with a LDAP server. The task '''LDAP users sync job \auth_ldap\task\sync_task''' is responsible for create, update user information, suspend and delete all LDAP accounts automatically.
The scheduled task can be enabled and configured on Site Administration > Server > Scheduled tasks by clicking on the gear icon. Select the desired frequency of running and enable the task, un-checking the Disabled checkbox.
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 over 1000 users in each LDAP container, this is because by default some LDAP stores such as MS AD only send back 1000 users at a time and PHP versions prior to 5.4 did not implement paged support for LDAP results. If you upgrade to PHP 5.4 or higher then Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions [http://support.microsoft.com/kb/315071 here] to set the Active Directory 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.

===Making your LDAP directory connection resilient===
* 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, if using eDirectory you would need to ensure your servers have viability of all relevant tree partitions, or if using Active Directory the servers are holding the same information you need though replication - see notes on a multi-domain environment if this applies.

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 a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more then one domain you will want to configure Moodle to look at your Global Catalog server. Specifically your top level domain Global Catalog server. Here is a simple example of this kind of Active Directory layout:

my.domain.ca (Root AD Domain)
| - dc1.my.domain.ca (Domain Controller)
| - dc2.my.domain.ca (Domain Controller)
|
| - - students.my.domain.ca (Sub AD Domain)
| - - - dc1.students.my.domain.ca (Domain Controller)
| - - - dc2.students.my.domain.ca (Domain Controller)
|
| - - faculty.my.domain.ca (Sub AD Domain)
| - - - dc1.faculty.my.domain.ca (Domain Controller)
| - - - dc2.faculty.my.domain.ca (Domain Controller)

In this example we have our top level domain (my.domain.ca) and two sub-domains. One sub-domain is for faculty accounts (faculty.my.domain.ca) and the other is for student accounts (students.my.domain.ca). Listed under each of those are two domain controllers.

Using the above example you'll want to use the following for accessing the Global Catalog over SSL:

ldaps://my.domain.ca:3269/

If you prefer to access your global catalog over a non-SSL connection you'll want to use:

ldap://my.domain.ca:3268/

We found if you didn't configure things this way you'd get errors like:

[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_search() [<a href='function.ldap-search'>function.ldap-search</a>]: Search: Partial results and referral received in /xxx/xxx/moodle20/lib/ldaplib.php on line 241, referer: http://moodle.my.domain.ca/moodle20/login/index.php
[Thu May 26 15:23:53 2011] [error] [client 192.168.xxx.xxx] PHP Warning: ldap_first_entry(): supplied argument is not a valid ldap result resource in /xxx/xxx/moodle20/lib/ldaplib.php on line 248, referer: http://moodle.my.domain.ca/moodle20/login/index.php

===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 over SSL)===
====Enabling LDAPS on your directory server====

* [[Active_Directory#MS_Active_Directory_.2B_SSL|Enabling LDAPS on MS Active Directory ]]

====Enabling LDAPS on your Moodle server====
Enabling LDAPS on your server can be tricky and often it is hard to pinpoint where things are going wrong. There are also differences between Windows and Linux and even different versions and distributions of Linux.

'''If you have not done so already you will need to decide upon your approach to establishing an SSL connection to your directory server:'''

* SSL connection with unverified self-signed certificate.

You can generate your own SSL certificate, and then instruct your Moodle server to ignore the fact that it is not valid. This setup is not as secure as others since you cannot be sure the server you are connecting to is not fake.

* SSL connection with trusted self-signed certificate.

You can generate your own SSL certificate on your directory server, and then specifically trust this certificate by installing it on your Moodle server.

* SSL connection with verified certificate from Internet-trusted certificate authority (CA)

In this approach the LDAP server has an installed certificate from an Internet-based CA, this means that your directory server would have an Internet address & host name. Your Moodle server must be trusting the certificate authority and have Internet access. This approach is not often used as it usually incurs a cost for the certificate, and it requires your directory server and Moodle server to be exposed to the Internet.

==Linux servers==
'''These instructions are for establishing a link using a trusted self-signed certificate.'''

''Note: written for a Red Hat Enterprise Linux 6 server, other Linux distributions may differ, especially in the location of the SSL certificates and OpenLdap config files, but the core principals are the same.''

To check that your directory server is online and accepting SSL connections on your LDAPS port (636), you can use try:
openssl s_client –connect <ldap server ip address>:636

Get your directory server’s certificate (.crt) and upload to Moodle server's ssl certificate directory, on RHEL6 this is at '''/etc/ssl/certs'''

Convert your ‘DER’ X509 certificate into a ‘PEM’ public key certificate.
openssl x509 -in my_server_certificate.cer -inform DER -out my_server_certificate.pem -outform PEM

Create certificate hashes using c_rehash
c_rehash
''If c_rehash is not installed install with: yum install /usr/bin/c_rehash''

Ensure you are able to access your LDAPS server by a DNS name, this may mean adding an entry to your host file (/etc/hosts)
<ldap server ip address> my_server.mydomain.school

Verify your certificate to check that it is installed correctly
openssl verify -verbose -CApath /etc/ssl/certs /etc/ssl/certs/my_server_certificate.pem
/etc/ssl/certs/my_server_certificate.pem: OK

You should now be able to connect to your LDAPS server over SSL without any errors
openssl s_client –connect <ldap server DNS name>:636

Edit your OpenLDAP config, on RHEL6 this is located at '''/etc/openldap/ldap.conf'''
# Define location of a CA Cert
TLS_CACERT /etc/ssl/certs/my_server_certificate.pem
TLS_CACERTDIR /etc/ssl/certs

Finally, you may or may not need to restart Apache, before configuring Moodle to use ldaps://<server DNS name>
httpd -k restart

==Windows servers==
'''These instructions are for establishing a link using an unverified self-signed certificate'''

You can tell PHP's OpenLDAP extension to disable SSL server certificate checking to do this you must create a directory called ''''C:\OpenLDAP\sysconf\'''' In this directory, create a file called ''ldap.conf'' with the following content:

TLS_REQCERT never

''(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])''

Now you should be able to use '''ldaps://''' when connecting to your LDAP server.

[[LDAP_authentication#Table of Contents|Table of Contents]]

==Appendices==

=== 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

[[es:LDAP_authentication]]
[[fr:Utiliser un serveur LDAP]]
[[ja:LDAP認証]]
[[de:LDAP-Server]]

Nginx

2015-03-26T09:07:29Z

Lameze:

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== FastCGI ===
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
</pre>

=== Slasharguments ===

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always '''enabled'''.

If you disable this '''slasharguments''' setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.
'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Some users are experiencing issues with relative links on Ngix web server as reported on the forum discussion:
[https://moodle.org/mod/forum/discuss.php?d=83445]

Those issues can be easily fixed by adding the following configuration to the nginx.conf:
'''nginx.conf location:'''
<pre>
location ~ \.php(.*)$ {
include fastcgi_params;
fastcgi_index index.php;
if (!-e $request_filename) {
rewrite ^(.*\.php)(/)(.*)$ $1?file=/$3 last;
}
fastcgi_param SCRIPT_FILENAME /var/moodle_www/html$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9000;
fastcgi_read_timeout 250s;
}
</pre>

== See also ==

* https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
* https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Nginx

2015-03-26T09:06:13Z

Lameze: /* Slasharguments */

{{Installing Moodle}}[[Nginx]] [engine x] is an HTTP and reverse proxy server, as well as a mail proxy server, written by Igor Sysoev. The nginx project started with a strong focus on high concurrency, high performance and low memory usage. It is licensed under the 2-clause BSD-like license and it runs on Linux, BSD variants, Mac OS X, Solaris, AIX, HP-UX, as well as on other *nix flavors. It also has a proof of concept port for Microsoft Windows.

''The following is community-contributed documentation on Nginx configuration. Amendmends and additions are welcome.''

== Nginx configuration ==

=== FastCGI ===
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
</pre>

=== Slasharguments ===

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always '''enabled'''.

If you disable this '''slasharguments''' setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.
'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Some users are experiencing issues with relative links on Ngix web server as reported on the forum discussion:
[https://moodle.org/mod/forum/discuss.php?d=83445]

Those issues can be easily fixed by adding the following configuration to the nginx.conf:
'''nginx.conf location:'''
<pre>
location ~ \.php(.*)$ {
include fastcgi_params;
fastcgi_index index.php;
if (!-e $request_filename) {
rewrite ^(.*\.php)(/)(.*)$ $1?file=/$3 last;
}
fastcgi_param SCRIPT_FILENAME /var/moodle_www/html$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9000;
fastcgi_read_timeout 250s;
}
</pre>

If you are using Fast CGI use the following parameters:
<pre>
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;

fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;

fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;

fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;
<pre>

== See also ==

* https://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm
* https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]

Apache

2015-03-26T08:56:50Z

Lameze: /* Slasharguments */

{{Installing Moodle}}
'''This article refers to the 'Apache HTTP server''''

The Apache HTTP server is the software that (along with the PHP scripting language) 'runs' Moodle. Note that there are alternatives (e.g. IIS on Windows) but the Apache HTTP Server is very popular on all platforms.

== Installing Apache ==
Installers are available for most platforms from http://httpd.apache.org/download.cgi. The official installation instructions are here: http://httpd.apache.org/docs/2.0/install.html. If you are running Linux then you are recommended to use the packaged version if you can. For example in Debian/Ubuntu it is simply:
<pre>
sudo apt-get install apache2
</pre>

See the documentation for your particular platform for the instructions. Apache is straightforward to build from source if you have to and the PHP documentation contains an article on building both Apache and PHP together - although you should rarely need to do that.

==Performance==

See [[Performance recommendations]]

==Slasharguments==

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always '''enabled'''.

If you disable this '''slasharguments''' setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.
'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

A common issue regarding SCORM packages reported on support forums:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

A common problem on Apache web server is the '''File not found''' error after uploading a file. For further instructions to fix this issue can be found here:
* [[Installation_FAQ#Uploaded_files_give_.22File_not_found.22|File not found error on uploaded files]]

If you are getting those errors, you need to enable slasharguments on your Apache web server. This can be easily configured by simply adding the following directive on httpd.conf or .htaccess :

AcceptPathInfo on

==SSL==

Moodle has an option to enable login pages to force the HTTPS protocol. This is recommended but requires that your web server is configured for SSL. It is possible to run the whole site over HTTPS (typically by configuring Apache to rewrite all http:// URLs to <nowiki>https://</nowiki>) but as this disables caching, there is a considerable performance hit. Only do this if you have a very good reason.

'''WARNING: Before switching on login over HTTPS, make very sure that HTTPS is working (just change the http:// to https:// in any Moodle URL). If not, you may lock yourself out'''

You have two options for obtaining an SSL certificate:
* generate a self-signed certificate. This is fine on (say) an Intranet but unsuitable for the public internet (except perhaps for testing). The user has no assurance that the certificate is legitimate.
* purchase a certificate from a vendor. There is a surprising range of prices and value-added services available. Some hosting companies even provide free certificates.

Below are instructions for install of a self-signed certificate. If you purchase a certificate you will normally receive instructions for installing it

===Debian and Apache2===

1. generate a certification:
<pre>
apache2-ssl-certificate
</pre>

for debian etch, apache2-ssl-certificate is no longer available, use make-ssl-cert instead:
<pre>
make-ssl-cert /usr/share/ssl-cert/ssleay.cnf /etc/apache2/ssl/apache.pem
</pre>
2. edit /etc/apache2/ports.conf:
<pre>
Listen 80
Listen 443
</pre>
3. copy /etc/apache)2/sites-available/default to /etc/apache2/sites-available/default-ssl, and change /etc/apache2/sites-available/default:
<pre>
NameVirtualHost *:80
<VirtualHost *:80>
...
</VirtualHost>
</pre>
and also /etc/apache2/sites-available/default-ssl:
<pre>
NameVirtualHost *:443
<VirtualHost *:443>
...
SSLEngine on
SSLCertificateFile /etc/apache2/ssl/apache.pem
...
</VirtualHost>
</pre>
4. symbolic link the ssl file:
<pre>
a2ensite default-ssl
</pre>
5. don't forget to symbolic link the ssl module:
<pre>
a2enmod ssl
</pre>
6. restart apache and '''test the connection''' (e.g. https://localhost/):
<pre>
/etc/init.d/apache2 restart
</pre>

== See also ==

* [http://httpd.apache.org/ The Apache HTTP Server Project homepage]
* [http://en.wikipedia.org/wiki/Apache_HTTP_Server Wikipedia article on the Apache HTTP Server]
* [http://httpd.apache.org/docs/2.0/misc/perf-tuning.html Apache Performance Tuning article at the official homepage]
* [https://els.earlham.edu/cayaraa/weblog/1468.html Making Moodle work with SSL]
* [http://www.krufix.de/ Using the same Moodle twice in local network and Internet via SSL-Proxy] (in German)

[[pl:Apache]]
[[ja:Apache]]
[[de:Apache]]

SCORM FAQ

2015-03-26T08:47:27Z

Lameze: /* slash arguments warning when I add/update SCORM objects in my course */

{{SCORM}}
==What is SCORM?==

SCORM was developed as a result of collaboration in the public and private sectors. The President of the United States, Bill Clinton issued an Executive Order that created an agency (ADL) to oversee the standard for developing and distributing online learning. All Federal agencies are mandated to use programs that meet those standards. SCORM is one result of that order.

There's a really simple "What is SCORM" introduction here: http://moodle.org/mod/forum/discuss.php?d=3757#p18828

A slightly more detailed introduction here: http://www.rusticisoftware.com/resources/whatisscorm/What%20Is%20SCORM.ht

==Should I make my Moodle courses as SCORM or use Moodle's features?==
It depends how you intend to use it. If you are planning on exporting and using in another LMS then SCORM would make this easier. If you want something shiny, then a SCORM package can fit the bill. However, reporting and grading work better in Moodle and for many educators the standard features do the job perfectly and do not require learning a new program. There is a useful form post discussing the pros and cons of SCORM in Moodle here: http://moodle.org/mod/forum/discuss.php?d=200242

==SCORM Information==

Advanced Distributed Learning (ADL) is the organization that wrote the SCORM standard. You can download documentation and samples form ADL's Web site. Documentation for SCORM 1.2 in several languages is available [http://www.adlnet.gov/Technologies/scorm/SCORMSDocuments/Forms/AllItems.aspx?RootFolder=%2fTechnologies%2fscorm%2fSCORMSDocuments%2fPrevious%20Versions%2fSCORM%201.2%2fDocumentation%20Suite%20(SCORM%201.2)&FolderCTID=0x0120007F801FCD5325044C89D91240519482D7&View={4D6DFFDE-3CFC-4DD9-A21A-4B687728824A} here].

Philip Hutchison provides an AS3 and JavaScript wrapper, as well as a sample package:
http://pipwerks.com/downloads/

==SCORM Package Contents==

A SCORM package must contains in the root of zip a file named imsmanifest.xml which defines SCORM course structure, resource location and many other things. Other files used in the package, such as HTML files, XML files, multimedia files, and JavaScript for the SCORM API must be listed in this file. The LMS parses the manifest, and provides the files listed there to the content package during runtime.

==AICC Package Contents==

An AICC package is defined by several files (from 4 to 7) with defined extensions as follows:

* CRS - Course Description file (mandatory)
* AU - Assignable Unit file (mandatory)
* DES - Descriptor file (mandatory)
* CST - Course Structure file (mandatory)
* ORE - Objective Relationship file (optional)
* PRE - Prerequisites file (optional)
* CMP - Completition Requirements file (optional)

==Basic Troubleshooting==

* Make sure you are running Moodle 2.1 or higher, a large number of SCORM related bugs are present in previous versions.
*Make sure you (and your users) have JavaScript enabled. SCORM requires JavaScript.
* Make sure your SCORM object is SCORM compliant - check it in an external SCORM player like [https://docs.moodle.org/en/Tools_for_creating_SCORM_content#Reload Reload] to see if it works there.
* Upload a copy of your SCORM object to a [http://en.wikipedia.org/wiki/File_hosting_service File Hosting Service] and post a message asking for help in the forums, linking to your SCORM object explaining exactly what you expect to happen, and what is happening instead.
* Read Dan Marsden's blog post [http://danmarsden.com/blog/2012/08/08/scorm-doesnt-work-in-moodle here] (Maintainer of SCORM Module in Moodle)

==Does Moodle Generate SCORM Content?==

Moodle '''does not''' generate scorm content. Moodle presents the content in SCORM packages to learners, and saves data from learner interactions with the SCORM package.

==Can I add a password for access to my SCORM package?==
No, although there is a tracker request for this: MDL-46403 As a workaround you could add your SCORM package using the single activity course format - see [[Course formats]] - and add an enrolment key to the course.

==Supported Versions==

* SCORM 1.2 is supported in Moodle 2.1(or higher) and passes all the tests in the ADL Conformance test suite 1.2.7 for SCORM 1.2. The best place for information on SCORM 1.2 conformance is the [http://www.adlnet.gov/Technologies/scorm/SCORMSDocuments/Previous%20Versions/SCORM%201.2/Conformance%20Test%20Suite%20(SCORM%201.2)/SCORM_1.2_ConformanceReq.pdf SCORM Comformance Requirements documentation (PDF 3.4MB)].

* SCORM 2004 is not supported in Moodle. Parts of the API have been implemented, but others such as Navigation and Sequencing have not. Development on native SCORM 2004 support in Moodle [https://moodle.org/mod/forum/discuss.php?d=227906 has stopped]. If you require a fully certified SCORM 2004 Player in Moodle, [http://www.scorm.com Rustici Software] have a [http://support.scorm.com/entries/20394726-scorm-cloud-moodle-module Moodle plugin] which connects to their commercial [http://www.scorm.com/scorm-solved/scorm-cloud/ SCORM Cloud] service turning Moodle into a fully compliant SCORM 2004 LMS.

* AICC objects are supported in Moodle 2.1 and higher.

* Moodle does not support Tin Can at this stage.

==Asking for Help in the SCORM Forum==

When trying to engage the community to help with a problem you are facing, you will get a better response if you follow a few simple guidelines:
* Always start your report with '''version information''' - preferably the information displayed on the Admin -> Environment panel eg. http://localhost/moodle/admin/environment.php where http://localhost/moodle is your particular prefix. With this it will be clear how you are running your Moodle instance, on what platform, and at which version. This will quickly expose issues where a simple upgrade will solve your problem.
* Be prepared to '''provide the SCORM package''' that illustrates your problem - if you don't then it will be very difficult for anyone offering assistance to recreate your situation - a real barrier to help.
* '''Screenshots''' are very helpful. Provide a screenshot of all error messages, and any instance where something seems to go wrong in the interface.
* Nonstandard themes can introduce SCORM issues. Be sure to tell us '''what theme you're using'''.
* If you have admin privileges, and have access to a localhost install or other place where real-time users won't be disturbed, be sure to turn on debugging. Navigate to '''Site Administration > Development > Debugging''' and set '''Debug messages: Developer''' and '''Display debug messages: Yes'''. Access the SCORM content. If there are errors printed to the page, include them in your forum post.
* Use [https://developers.google.com/chrome-developer-tools/docs/console Chrome's JavaScript Console] or [https://developer.mozilla.org/en-US/docs/Tools/Web_Console Firebug's JavaScript console] to check that there are no JavaScript errors on the page when the content loads.
* Run your problematic SCORM package through '''API debugging''' (see below) and include the text of that API log with your post. That way we can see right away if the right function calls are not taking place.
* If you're using a content development suite which publishes to SCORM, such as Articulate, Captivate, Lectora, LessonBuilder, Udutu, or some other product, then include that in your post. Every authoring software has its ticks, and if you've run into one, it's likely that someone else has also dealt with it, and will recognize it. However, please keep in mind that '''this is a place to get help with Moodle issues, not help with your SCORM package authoring suite'''.

==Debugging ==

# Debugging settings are located at Settings > Site Administration > Plugins > Activities > Scorm.
# Check the checkbox for '''Activate API debug...'''
# Set the api mask. You can use the mask to enable debugging under certain conditions. For example, if you are logged in using the admin user (username admin) you can set the api mask to: <cite>admin.*</cite> Users not logged in as admin will not see the debugging log. The "Default" api mask is <cite>.*</cite>

==What does the debugging log mean?==

The SCO commonly sends the following communications through the API:

* '''LMSInitialize();''' opens the connection between the SCO and Moodle
* '''LMSGetValue( 'valuename' );''' gets a value from Moodle
* '''LMSSetValue( 'valuename' , 'value' );''' sends a value to Moodle
* '''LMSCommit();''' saves values sent to Moodle via LMSSetValue() and should be called after every LMSSetValue()
* '''LMSFinish()''' saves values sent to Moodle and closes the connection between the SCO And Moodle

Red lines in the debugging log means there was an error in the communication through the API.

If LMSInitialize() fails, returns an error, then no subsequent values sent to Moodle will be saved.

Click through the entire SCORM package. Then access the scorm report for your attempt, and compare the saved values in the debugging log with Moodle's report of the attempt. If the values set in the debug log do not match the values saved to Moodle, then there may be a problem with Moodle. Otherwise it's likely to be an issue with the SCO or the SCORM activity settings not giving you the functionality you need.

==SCORM and the Gradebook==
Please see [https://docs.moodle.org/en/SCORM_FAQ#My_SCORM_Module_doesn.27t_function_properly FAQ:My SCORM Module doesn't function properly] and [https://docs.moodle.org/en/SCORM_FAQ#Handling_of_Multiple_Attempts FAQ:Handling of Multiple Attempts]

Some SCORM packages report both cmi.core.lesson_status and cmi.core.score.raw. Others report only cmi.core.lesson_status, or only cmi.core.score.raw. The '''Grading Method''' setting for SCORM objects is meant to account for that.

If you have the '''Grading Method''' set to '''Highest grade''', '''Average grade''', or '''Sum grade''', and your learning object does not report a score, only, cmi.core.lesson_status, then there will be no numerical score to pass to the gradebook.

If your SCOs do not report cmi.core.score.raw, then the best '''Grading Method''' setting is '''Learning Objects'''. This reports either a 1 or a 0 as a score for each learning object. The gradebook value for that SCORM activity is the percent of scos in the package for which learners got a 1.

On the other hand, if your SCOs do not report a lesson_status, then select one of the score-based '''Grading Method''' options, such as '''Highest grade''', '''Average grade''', or '''Sum grade''', and not '''Learning Objects'''.

If you do not know what your SCOs are reporting to the LMS, then run them through to completion with debugging on.

Much of the way SCORM objects are graded is controlled inside the SCORM Authoring process before it is packaged for use in an LMS like Moodle - make sure all your grading settings are set correctly.

==SCORM Administration Options==

See [[SCORM settings]]

==Common Solutions==

===Difficulty Displaying a SCORM Package===
If you have difficulty displaying a SCORM, try loading the SCORM in [http://www.reload.ac.uk Reload] and re-saving it, then save the folder as a .zip package and try again.

===Character Display Errors===
When you notice there is a problem displaying characters correctly, it could be a misconfiguration of your server. Make sure that both httpd.conf (when using Apache) and php.ini are set to DefaultCharacterset = utf8 or switch the sending of a default character set off.

===slash arguments warning when I add/update SCORM objects in my course===
SCORM require '''slasharguments''' on the web server in order to work properly. Unfortunately, some PHP servers doesn't allow this method and your SCORM objects might not displayed.

This affects IIS 5 and earlier and some Apache servers. Under IIS 5 and earlier, a workaround using an [http://www.isapirewrite.com/ ISAPI re-write] tool can be used.

A common problem on Apache web server is the '''File not found''' error after uploading a file. For further instructions to fix this issue can be found here:
* [[Installation_FAQ#Uploaded_files_give_.22File_not_found.22|File not found error on uploaded files]]

For further information about slasharguments and web server configuration see:
* [[admin/environment/slasharguments|Slasharguments]]
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

===SCORM doesn't work on Godaddy Host===
Godaddy hosts give a 404 file not found error - this is because by default they do not allow slash arguments which SCORM requires. The best way to test this is to visit http://yourmoodlesite/admin/tool/health/index.php - but the fix involves adding a php.ini or php5.ini file with the following text:
AcceptPathInfo
cgi.fix_pathinfo=1

===My Flash-Based Content Loads, then Stalls===
This issue is most commonly associated with zlib compression. Classic presentation is that the base HTML file and SWF are loaded into the SCORM player, but the SWF is not able to load any audio or video assets, and therefore stalls. You can watch the loading of SWFs and assets using Chrome's Developer Tools or other.

Check your site's zlib compression settings as an admin by loading up the Server > phpinfo page. zlib compression is not a Moodle setting but a server setting, so you'll need a server admin to disable it. Be sure to Purge All Caches, and clear browser caches, before confirming the change.

===Zlib warning when I add/update SCORM objects in my course===
Zlib is a php compression setting made in a websites PHP configuration - unfortunately some browsers don't handle this well (especially Internet Explorer 6) Some webhosts enable this setting, but it will likely cause issues for your users when they attempt to view/use the SCORM object. You will need to contact your server administrator to turn this off. The setting to change in php configuration is "zlib.output_compression"

===Incorrect file package - missing imsmanifest.xml or AICC structure===
This means that Moodle cannot find a file called imsmanifest.xml inside the SCORM object. Reasons for this could be:
* imsmanifest.xml needs to be immediately inside the scorm directory, NOT inside a directory inside of that. So if the zipped scorm package is package.zip, the unzipped package directory should contain immediately inside of it the imsmanifest.xml. This is a common mistake and normally occurs when a SCORM author creates a package themselves and then selects that folder to compress. This places the content folder inside of another folder, The imsmanifest.xml is there, but it is 2 directories deep. To avoid this problem when zipping scorm content into a package, go INSIDE of the exported scorm folder, select all files inside, and compress them while all are selected. The resultant compressed directory has the imsmanifest.xml file in the first directory, immediately available to the moodle scorm loading process.
* when using linux based systems the filename imsmanifest.xml must be all in lowercase not IMSmanifest.xml or Imsmanifest.XML
* The SCORM authoring tool Articulate sometimes fails to create the imsmanifest.xml -Try exporting the package again and see if the manifest is generated.
* The SCORM authoring tool Articulate Presenter will publish packages where the imsmanifest.xml file is in the correct place, but there are several lines of white space in the manifest file if you do not fill out the Reporting and Tracking Options in Articulate Presenter for Keywords and LMS Description. Moodle will give a "Manifest not found" error when encountering this. To fix this problem select the Reporting and Tracking Options in the Articulate Presenter publish dialog and fill in the LMS Description and Keywords.

===File not found error===
You have this error if the scorm package is created in moodle, and the scorm menu loads, but inside of the viewing area for the scorm content, you get a page with a 404 file not found error, usually showing the current Moodle theme.

What this means is that one of the files listed in the imsmanifest.xml is not in the scorm package or not in the correct directory.

Download and unzip the package, open up imsmanifest.xml. At the bottom of the xml file, below any metadata, you'll find a place where organizations and resources for those organizations are designated:

<code xml>

<organizations default="TOC1">
<organization identifier="TOC1">
<title>SCORM Test</title>
<item identifier="I_SCO0" identifierref="SCO0">
<title>Library Quiz</title>
<adlcp:masteryscore>0</adlcp:masteryscore>
</item>
</organization>
</organizations>
<resources>
<resource identifier="SCO0" type="webcontent" adlcp:scormtype="sco" href="scorm.html">
<file href="scorm.html"/>
<dependency identifierref="ALLRESOURCES" />
</resource>
<resource identifier="ALLRESOURCES" type="webcontent" adlcp:scormtype="asset">
<file href="scorm.html" />
<file href="scorm.js" />
<file href="swfobject.js" />
<file href="scorm.swf" />
<file href="scormwrapper.js" />
</resource>
</resources>
</manifest>
</code>

In this xml, we have a single organization, and in that organization is a single resource, a single sco. There are 5 files necessary for that resource to work correctly. The scorm.html file is loaded first. It loads 3 external js files and a swf.

What you need to do now is go to the directory containing imsmanifest.xml, and check that all of those listed files are available at the correct path from imsmanfiest.xml, as listed in imsmanifest.xml. If any one of those files is missing (especially the html file or the swf), or if the paths in imsmanifest.xml are incorrect, then it's very likely that the scorm object won't be able to load at all.

Sometimes the files aren't missing, but are simply misnamed in the manifest, or placed in the wrong directory. You can fix this by moving the files to the correct places, or updating their names so that the imsmanifest and the actual file names match up. In the case of a misnamed file, change the manifest rather than the actual file names, since the the files also reference one another in other places!

===Unzip issues===
If you get a blank page after filling in the title, description, and selecting a large SCORM file, it's likely you haven't installed the PHP-zip lib which is required for Moodle 2.x for more info see [[admin/environment/php_extension/zip]]

===Clear an Attempt===
To clear attempts by a student:

# Go to the SCORM activity and select the link "View reports for x users"
# Select the attempt or attempts you want to clear using the checkbox
# Select Delete in the drop-down box at the bottom of the page

===Handling of Multiple Attempts===
SCORM is designed to allow a learner to exit and return at a later date to the same point they left from. This means that each time they enter the SCORM they are using the same single attempt. Some SCORM packages are intelligent about handling re-entry, many are not. What this means is that if the learner re-enters an existing attempt, if the SCORM content does not have internal logic to avoid overwriting cmi.core.lesson_status and cmi.core.score.raw, they can be overwritten by a lower score, confusing the learner.

When a SCORM sets the cmi.core.lesson_status value to 'completed', 'passed' or 'failed' then Moodle allows the user to create a new attempt by adding a '''Start new attempt''' checkbox to the entry page. If cmi.core.lesson_status is set to 'incomplete', 'browsed' or 'notattempted' the learner can only re-enter the existing attempt. If you are using the setting 'Student skip content structure page', this checkbox will never be shown to the user.

Moodle provides a range of settings to allow this to be controlled, some of these settings are hidden by default as advanced options.
* Number of attempts
:This allows the teacher to set how many SCORM attempts the learner may create - this is not how many times a learner can re-enter a SCORM attempt.
* Attempts grading
:This allows the teacher to set how multiple SCORM attempts(not re-entries) are graded. It is important to note that a 'failed' cmi.core_lesson_status allows a new attempt to be generated but the attempts grading setting "last completed attempt" only includes 'completed' and 'passed' values in it's calculations.
* Display attempt status
:This displays a users SCORM attempts and how their final grade is calculated on the SCORM entry page and the My Moodle page for the learner.
* Force completed
:This is a setting that can be used to force a SCORM package to report a 'completed' cmi.core.lesson_status if it doesn't currently set the value.
* Force new attempt
:This hides the '''Start new attempt''' checkbox and will force a new attempt if the previous attempt has cmi.core.lesson_status value to 'completed', 'passed' or 'failed' - this setting can also be used to make sure a new attempt is generated when the 'Student skip content structure page' setting is used.
* Lock after final attempt
:This prevents access to the SCORM after the total number of attempts have been used - if this is not set the learner can re-enter their last attempt and potentially change/overwrite their score each time depending on how the SCORM package supports multiple re-entries.

===Reducing Load Time with Captivate===
* Modify the percent that must be downloaded before the content starts to play. In Captivate 4, there's a setting in: Preferences / Project / Start and End / Preload. Reduce that to 50%.
* If you use audio in your Cp file (as background or element attachment), try to put a gap of 0,1 second at the beginning of each element including audio on your slides. If you don't do that, Cp merge all the audio files in one big audio file it need to download before playing the project. This problem have been report many times from the Cp community.

===Moodle changes cmi.core.lesson_status from "completed" or "passed" to "failed"===
Many SCORM authorware suites generate a masteryscore node in the imsmanifest.xml by default. This node is not necessary to the XML file. But when it is there, the SCORM standard designates specific behavior with regard to the value set there.

Here's what is in the scorm standard, on page 35 of 155 in SCORM_1.2_ConformanceReq.pdf, numbered page 2-19 ([http://www.adlnet.gov/Technologies/scorm/SCORMSDocuments/Forms/AllItems.aspx?RootFolder=%2fTechnologies%2fscorm%2fSCORMSDocuments%2fPrevious%20Versions%2fSCORM%201%2e2%2fDocumentation%20Suite%20%28SCORM%201%2e2%29&FolderCTID=0x0120007F801FCD5325044C89D91240519482D7&View=%7b4D6DFFDE%2d3CFC%2d4DD9%2dA21A%2d4B687728824A%7d SCORM Version 1.2 Conformance Requirements Version 1.2]):
<blockquote>
If the value for this element is not set to “incomplete” by the SCO, then the LMS shall re-evaluate and change the value based on the following:<ul>
<li>If there is no mastery score in the Manifest, and the SCO sets a score (cmi.core.score.raw) and the lesson_status (cmi.core.lesson_status) then the LMS shall not override the SCO determined status.</li>
<li>If there is a mastery score in the Manifest, the LMS can change the status to either passed or failed depending on the student's score (cmi.core.score.raw) compared to the mastery score.</li>
<li>If the student is taking the SCO for no-credit, (cmi.core.credit = “no-credit”) there is no change to the lesson_status, with one exception. If the lesson_mode (cmi.core.lesson_mode) is "browse", the lesson_status may change to "browsed" even if the cmi.core.credit is set to no-credit.</li>
</ul>
</blockquote>
This can result in some functionality you don't intend. You can fix the problem by removing the mastery score node from your imsmanifest.xml file. You will also want to find out what options you have, within your authorware suite, for the writing of that node into the manifest file, and change your authoring process accordingly.

===Player Look 'n Feel===
You should be able to adjust height and width settings for the SCORM player window '''so long as''' your theme is based on/not too much of an aberration from one of the standard themes which ship with Moodle 2.

If your site or course theme isn't closely based on one of the standard M2 themes, then it's possible that your theme CSS is overriding local height and width settings for the SCORM player. Have a Web developer (or a Moodle Partner) examine how your theme is interacting with the player layout, and make changes to your theme as needed.

'''Why can't I just change it locally?''' You can change height and width per individual SCORM package, and you can set defaults for these local height and width values ( [[SCORM Admin Options]] ). Other things, such as colors, shading, borders, backgrounds, are controlled by CSS, just like everything else on the site.

=== Courselab 2.4 ===
If you receive a " found more than one record!" error when trying to run your SCORM 1.2 package check the imsmanifest.xml file of your SCORM package and ensure that the values for <organization identifier> and <item identifier> are unique. To change the <organization identifier>, in Courselab, go to File > Course Runtime Settings. The dialog says 'Course identification in LMS' but changing the Identifier field is what sets the <organization identifier>. (see MDL-38060 for more information)

=== SCORM results deleted after package update ===

When uploading a SCORM package over a previous one, if the item identifier in the manifest file is different to the one being overwritten then the tracking data for that SCORM package in Moodle is deleted.

Ensure the item identifier is the same for the new SCORM resource

==See also==

* Using Moodle [http://moodle.org/mod/forum/view.php?id=1951 SCORM forum]
* [http://danmarsden.com/blog/2012/08/08/scorm-doesnt-work-in-moodle SCORM doesn't work] blog post from developer Dan Marsden
* [http://danmarsden.com/blog/2009/05/23/scorm-2004-in-moodle/ SCORM 2004 in Moodle] blog post from developer Dan Marsden
* [https://docs.moodle.org/dev/SCORM_schema Internal SCORM Schema]
* The official standard: [http://www.adlnet.gov/Technologies/scorm/default.aspx Advanced Distributed Learning - SCORM]

Online resources
* [http://www.scormcourse.com/ SCORMCourse.com] serves the SCORM and ADL community as an educational resource for SCORM technology.
* [http://www.eduworks.com/index.php/Publications/Learning-Object-Tutorial.html Learning Object Tutorial]
* [http://elearningweekly.wordpress.com/2007/04/12/tutorial-build-scorm-compatible-lesson-templates-for-your-lms/ Tutorial: Build SCORM-Compatible Lesson Templates for Your LMS]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=3757 Simple introduction to SCORM]
*[http://moodle.org/mod/forum/discuss.php?d=57059 Are there any sugestions for scorm authoring with Microsoft word / or any other easy (maybe free) scorm authoring tool?]
*[http://moodle.org/mod/forum/discuss.php?d=95946 Is SCORM worth it?]
*[http://moodle.org/mod/forum/discuss.php?d=207964 Updating an Object]

[[Category:FAQ]]
[[de:Lernpaket FAQ]]

Using slash arguments

2015-03-26T08:45:00Z

Lameze:

{{Environment}}

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always '''enabled'''.

If you disable this '''slasharguments''' setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.

Another very common problem reported on support forums about slasharguments:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

A common problem on Apache web server is the '''File not found''' error after uploading a file. For further instructions to fix this issue can be found here:
* [[Installation_FAQ#Uploaded_files_give_.22File_not_found.22|File not found error on uploaded files]]

For further information about slasharguments configuration on web servers see:
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Using slash arguments

2015-03-26T08:44:26Z

Lameze:

{{Environment}}

The slasharguments setting is intended mostly for diagnostic purposes and we ''''''strongly recommend this setting should be always enabled'''.

If you disable this '''slasharguments''' setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.

Another very common problem reported on support forums about slasharguments:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

A common problem on Apache web server is the '''File not found''' error after uploading a file. For further instructions to fix this issue can be found here:
* [[Installation_FAQ#Uploaded_files_give_.22File_not_found.22|File not found error on uploaded files]]

For further information about slasharguments configuration on web servers see:
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Using slash arguments

2015-03-26T08:43:27Z

Lameze:

{{Environment}}

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always enabled.
If you disable this slasharguments setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.

Another very common problem reported on support forums about slasharguments:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

A common problem on Apache web server is the '''File not found''' error after uploading a file. For further instructions to fix this issue can be found here:
* [[Installation_FAQ#Uploaded_files_give_.22File_not_found.22|File not found error on uploaded files]]

For further information about slasharguments configuration on web servers see:
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Using slash arguments

2015-03-26T08:24:12Z

Lameze:

{{Environment}}

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always enabled.
If you disable this slasharguments setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.
Another very common problem reported on support forums about slasharguments:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

For further information about slasharguments configuration on web servers see:
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Using slash arguments

2015-03-26T08:23:28Z

Lameze:

{{Environment}}

The slasharguments setting is intended mostly for diagnostic purposes and we strongly recommend this setting should be always enabled.
If you disable this slasharguments setting, many Moodle features will not work properly, such as:
* SCORM packages.
* Relative links in embedded pages.
* Add-ons and plugins.
* Broken images.

If you disable slasharguments setting and embedded images start to be displayed it means that the server is not properly configured.
Another very common problem reported on support forums about slasharguments:
* [[SCORM_FAQ#slash_arguments_warning_when_I_add.2Fupdate_SCORM_objects_in_my_course|SCORM FAQ: slash arguments warning when I add/update SCORM objects in my course]]

For further information about slasharguments configuration on web servers see:
* [[Internet Information Services#Slasharguments|IIS server configuration]]
* [[Apache#Slasharguments|Apache slasharguments configuration]]
* [[Nginx#Slasharguments|Nginx slasharguments configuration]]

'''Please note that will not be possible to disable slasharguments settings on moodle 3.0, we recommend to check and configure slasharguments in your webserver.'''

Grade import

2015-03-05T03:07:48Z

Lameze: /* CSV import */

{{Grades}}
==Importing grades==
Grades may be imported as a CSV or XML file, or (new in 2.8 onwards) by pasting from a spreadsheet.

The import file format is the same as the corresponding export format.

Note: Grade import is equivalent to manual grading in the [[Grader report|grader report]]. Thus, if grades for a particular Moodle activity such as an assignment are imported, they can no longer be edited via the assignment submission page.

[[Image:Csv grade import.png|thumb|CSV grade import]]
To import grades into the gradebook:

# Decide on an import format - CSV or XML file, or paste from spreadsheet (see below) - then [[Grade export|export some grades]] using the corresponding export format.
# Edit the export file as appropriate and save it.
# Tip: If you opened your exported file in Excel, don't add columns there because Moodle will reject the import if there are new columns that didn't exist in the exported file. If you need to add columns, do that in Moodle BEFORE you export your gradebook.
# Select your chosen import format from the gradebook dropdown menu.
# Browse and upload your previously saved file.
# Set options as required.
# Click the "Upload grades" button.
# CSV import only: Preview the grade import and choose the column mapping then click the "Upload grades" button to complete the grade import.
## Tip: By default "Map from" is set to First Name, and "Map to" to userid. Change both dropdowns to: "Email Address" to "useremail", or to "Id Number" to "useridnumber" (assuming that your users have ID number fields filled in in their profiles).
## Tip: Unlike in most email programs, email addresses are case sensitive in grade import files. (This should eventually be fixed as per MDL-29315.)

You need two permissions to import grades: (1) general permission to import grades and (2) permission to import grades in a particular format. For example, to import CSV grades you need moodle/grade:import ("Import grades") = Allow and gradeimport/csv:view ("Import grades from CSV") = Allow

==CSV import==

CSV import is more flexible than XML import, as you may choose the column mapping.

===Grade Mapping===

After selecting your CSV for import you'll be prompted to map user fields and grade items to the new column headers to ensure that there is a match. More than one item can be mapped to the same grade item in your destination course so be mindful of the mapping to ensure that grade data is imported properly, any collisions (i.e. if two or more fields are mapped to the same but duplicate data exists) will cause an error. User grade data for users not yet enrolled to the destination course will be noted (and once enrolled their grade data will display).

===Encoding===

If you are unsure of the encoding of your CSV file, try selecting the second option in the encoding dropdown menu. If you've used Excel to produce the CSV file the second option WINDOWS-xxx encoding is probably the correct one. The grade import preview will tell you if you guessed the encoding correctly.

===Verbose scales===

Scales can be either specified as a raw id - eg. 0, 1, 2, 3, etc. or as a string, eg. "good", "bad", "not very bad". The later format is called "verbose".

===Force import===

Since 2.8 a new column '''Last downloaded from this course''' containing the time stamp of the exported date is present on every exported file.
This prevents grade overriding during the grade importing in a scenario where more than one teacher exports grades of a course and then import again. If a second teacher exports the grades and try to import the following error message will be displayed and the grade importing procedure will be aborted.
<pre>Student name grades have not been imported because the grades in the import file are older than in the grader report. To proceed with the grade import anyway, use the force import option.</pre>
Also, the grade importing will prevent the import of an old exported file (1 year ago) and future dates.
In cases that the teacher needs to import the grades anyway, we've create an option called '''Force import'''. Using this option will avoid this date checking and the grade are imported.

==Paste from spreadsheet==

{{New features}}
Grades may be pasted directly from a spreadsheet such as Excel or Libre Office:

1) Ensure you have the correct column names for your grades (eg the assignment title or manual grade) It might help to download and edit the relevant students and graded information by using the [[Grade export]] feature.

2) For the students you need either their username, their ID or their email address. Add the grades you need and copy the relevant section:
[[File:pastegrades1.png|thumb|center|400px]]
3) In your course, go to ''Grade administration>Import>Paste from spreadsheet'' and paste:
[[File:pastegrades2.png|thumb|center|400px]]
4) In the preview, ensure you match up the identifier you used for the students -so if you used 'username', ensure it maps to 'username'. Do the same for your graded activities:
[[File:pastegrades3.png|thumb|400px|center]]
5) If everything has been correctly mapped (See grade mapping above), you should get a success message and the grades will have been added, displaying in a different colour to show they were imported directly into the gradebook:
{|
| [[File:pastegrades4.png|thumb|400px]]
| [[File:pastegrades5.png|thumb|400px]]
|}

Paste from a spreadsheet requires similar permissions to a csv file import: (1) general permission to import grades and (2) permission to import grades in a particular format i.e. moodle/grade:import ("Import grades") = Allow and gradeimport/direct:view ("Import grades from spreadsheet") = Allow

==XML import==

Before importing an XML file you will need to ensure that all of the students that you want to alter grades for have their ID number field filled out. This is located in the "Optional" section of the user edit profile page.
You will also need to set the ID number of the activity as well. You can find this under "Common module settings" when editing the activity.

The format for the XML should be as follows:
<pre>
<results>
<result>
<assignment>activityidnumber</assignment>
<student>studentidnumber</student>
<score>53.00</score>
</result>
<result>
<assignment>differentactivityidnumber</assignment>
<student>studentidnumber</student>
<score>73.00</score>
</result>
</results>
</pre>

For a working example try exporting the gradebook as an xml file and view the format.

===Remote file URL===

The remote file URL field is for fetching data from a remote server, such as a student information system.

==Grade import capabilities==

* [[Capabilities/gradeimport/csv:view|Import grades from CSV]]
* [[Capabilities/gradeimport/xml:publish|Publish import grades from XML]]
* [[Capabilities/gradeimport/xml:view|Import grades from XML]]

==See also==

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=85944 Gradebook confusion]
*[http://moodle.org/mod/forum/discuss.php?d=92081 Can external software insert data into the gradebook?]

[[ja:評定のインポート]]
[[de:Bewertungen importieren]]
[[es:Importar calificaciones]]
[[fr:Importation des notes]]

Administration via command line

2015-02-09T08:31:59Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This affect all moodle versions and is due MySQL default InnoDB file format (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the InnoDB file format to Barracuda.

Since 2.6 onwards we have a specific tool to help users on this conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Upgrading

2015-02-09T08:31:35Z

Lameze: /* MySQL dmlwriteexceptionerror exception throw on course restoration */

{{Installing Moodle}}
''This page explains in detail how to upgrade Moodle. For a summary of the process, see [[Upgrade overview]].''

==Check the requirements==

Check that your server meets all requirements for 2.8 in ''Administration > Site administration > Server > [[Environment]]''.

Note: You can only upgrade to Moodle 2.8 from Moodle 2.2 or later. If upgrading from earlier versions, you must [https://docs.moodle.org/22/en/Upgrading_to_Moodle_2.2 upgrade to 2.2] as a first step.

==Before upgrading==

'''We advise that you test the upgrade first on a COPY of your production site, to make sure it works as you expect.'''

== Backup important data ==

There are three areas that should be backed up before any upgrade:
#Moodle software (For example, everything in server/htdocs/moodle)
#Moodle uploaded files (For example, server/moodledata)
#Moodle database (For example, your Postgres or MySQL database dump)

See [[Site backup]] for more specific information.

==Put your site into maintenance mode==
Before you begin upgrading your site, you should put it into [[Maintenance_mode | maintenance mode]] to stop any non-admin users from logging in.

== Check for plugin updates ==

If you have [[Automatic updates deployment]] enabled, you will be able to update installed plugins automatically during the upgrade. Just make sure you check for available updates (via the button for it) at the Plugins check screen.

If you are updating plugins manually, it is a good moment now to check in the [http://moodle.org/plugins Moodle Plugins directory] whether there is a 2.8 version available for any plugins (including themes) that you have previously installed on your site. If so, download the plugin package. In the next step, you will copy it to the appropriate location in your Moodle code (see [[Installing plugins]]).

The upgrade of the plugin will then happen as part of the Moodle upgrade process.

If an out-of-date plugin causes your upgrade to fail, you can usually delete the plugin code rather than uninstalling it from within Moodle so that the data associated with it is not deleted.

== Install the new Moodle software ==
You can fetch the current (2.8) version of the software through

wget http://sourceforge.net/projects/moodle/files/Moodle/stable28/moodle-latest-28.tgz

=== Standard install package ===

# Move your old Moodle software program files to another location. ''Do NOT copy new files over the old files.''
# Unzip or unpack the upgrade file so that all the new Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and moodledata if it needs to in the upgrade.
# Copy your old [[Configuration file|config.php file]] back to the new Moodle directory.
# As mentioned above, if you had installed any plugins on your site you should add them to the new code tree now. It is important to check that you get the correct version for your new version of Moodle. Be particularly careful that you do not overwrite any code in the new version of Moodle.
# Dont forget to also copy over your moodledata folder / directory. If you don't you will get a "fatal error $cfg- dataroot is not configured properly".

====Linux====
mv moodle moodle.backup
tar xvzf moodle-2.8.tgz

Next, copy across your config.php, any custom plugins, and your .htaccess file if you created one ('''check that custom plugins are the correct version for your new Moodle first'''):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to make moodle/config.php (and the rest of the source code) readable by your www server. Ideally the files should not be writeable by your server.

If you use cron, take care that cron.php is executeable and uses the correct php command:
chmod 740 admin/cli/cron.php (some configurations need chmod 750 or chmod 755)
copy the first line from cron.php (if it looks like '#!/usr/local/bin/php' or '#!/usr/local/bin/php5.3', no need to copy '<?php')

if necessary.

=== Using Git ===

You can use Git for updating or upgrading your Moodle. See [[Git for Administrators]] for details.

===Command line upgrade===

On Linux servers, Moodle 2.8 supports running the [[CLI|upgrade from the command line]], rather than through a web browser. This is likely to be more reliable, particularly for large sites.

== Finishing the upgrade ==

The last step is to trigger the upgrade processes within Moodle.

To do this just go to ''Administration > Site administration > Notifications''.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

Note: If you are running multiple servers then you should purge all caches manually (via ''Administration > Site administration > Development > Purge all caches'') after completing the upgrade on all servers.

===Fatal error: Maximum execution time of 30 seconds exceeded...===

If your server uses a main language other than English, you may encounter a 'Fatal error: Maximum execution time of 30 seconds exceeded' when you try to upgrade it. You can increase max_execution_time = 160 on php.ini to allow the scripts enough time to process the language update. Otherwise, you can switch to English as the default language before doing the upgrade and back to your original language after a succcessful upgrade. See the forum discussion at https://moodle.org/mod/forum/discuss.php?d=119598.

==After upgrading==

The config.php file from your installation should work fine but if you take a look at config-dist.php that came with Moodle 2.8 there are more/different options available (e.g. database drivers and settings). It's a good idea to map your old config.php settings to a new one based on the 2.8 config-dist.php.

===Cron===

Cron has received a major update (MDL-25499) and now has support for both scheduled and adhoc tasks.

The benefits of these changes are:
* The schedule for every task can be configured by the admin
* Tasks can run in parallel
* Cron processes use locking to prevent the same task running at the same time by different processes
* Clusters with multiple identical application nodes are supported, you can run cron on all of them

A result of this is that cron can be run much more often, which means (for example) forum posts can be sent out sooner. To take advantage of the new cron system it is now strongly recommended that administrators increase the frequency that cron is run to at least ''once per minute''.

You also may need to modify any automated scripts you have that are parsing the output from cron. It is no longer possible to simply monitor the output of cron for the string "Cron script completed correctly" (if that is what you were doing). An alternative is to monitor the output for the string "task failed:". If you detect that a task is failing, [[Cron#Debugging_Scheduled_Tasks|here]] are some tips for debugging the failure.

Before the upgrade to 2.8, there may have been a cron task that was failing, which was preventing the rest of cron from being executed. A failure in any single task will no longer prevent the rest of the Moodle cron tasks from executing, so you may uncover previously masked bugs. It is a good idea to closely monitor the output from cron after the upgrade to 2.8.

===Assignments===

The old assignment (2.2) module has been removed from core and has been replaced by a stub to support transparently remapping URLs and restoring course backups from the old module to the new one.

If you are still using the old assignment (2.2) module, after upgrading to Moodle 2.8 all assignment (2.2) activities will be hidden. You need to run the [[Assignment upgrade tool]] to un-hide the activities.

If you really, really need to keep using the old assignment (2.2) module, you should update the code to Moodle 2.8, and then replace the "mod/assignment" folder with the one from https://github.com/moodlehq/moodle-mod_assignment/releases before completing the upgrade.

==Possible issues that may affect you in Moodle 2.8==

===New aggregation method - 'Natural'===

The aggregation method 'Sum of grades' used in the [[Grades|gradebook]] has been reviewed, significantly improved and renamed to 'Natural'. It is recommended that 'Natural' is set as the default aggregation method, as for new Moodle 2.8 installs.

In addition, the aggregation setting 'Aggregate including subcategories' has been removed.

Any courses previously using either 'Sum of grades' and/or 'Aggregate including subcategories' may have some changes to grades. Thus it is recommended that grades in the gradebook are reviewed for such courses.

===Teachers able to enrol users via the cohort sync enrolment method===

Teachers will get access to [[Cohort sync]] enrolment method if it is enabled, remove capability to use this enrolment method from teachers if you want to preserve 2.7 behaviour. See MDL-36014

===Gradebook scrolling and theme issues===
Themes with non-fixed headers must have the .navbar class in their navbar in order for floating headers in the grader report to work - see MDL-46658 for more information.

===Removal of the 'Group members only' experimental setting===

The experimental setting 'Group members only' has been removed in Moodle 2.8. The group and grouping restrictions in [[Conditional activities settings|conditional activities]] now provide this functionality. Any 'Available for group members only' instances are automatically converted to group or grouping restrictions when a site is upgraded.

* 'Available for group members only' instances with no grouping selected are converted to a 'Must belong to any group' restriction.
* 'Available for group members only' instances with a grouping specified are converted to a 'Must belong to the specific grouping' restriction.

''More items to be added here...''

=== MySQL dmlwriteexceptionerror exception throw on course restoration ===

Some users are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This affect all moodle versions and is due MySQL default InnoDB file format (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the InnoDB file format to Barracuda.

Since 2.6 onwards we have a specific tool to help users on this conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

=== Moodle 2.3, 2.4, 2.5, 2.6 and 2.7 improvements ===

Depending on which version you are upgrading from, please see the section 'Possible issues that may affect you' in the documentation

* [https://docs.moodle.org/23/en/Upgrading Upgrading to Moodle 2.3]
* [https://docs.moodle.org/24/en/Upgrading Upgrading to Moodle 2.4]
* [https://docs.moodle.org/25/en/Upgrading Upgrading to Moodle 2.5]
* [https://docs.moodle.org/26/en/Upgrading Upgrading to Moodle 2.6]
* [https://docs.moodle.org/27/en/Upgrading Upgrading to Moodle 2.7]

==See also==

* [[Installation]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[dev:Moodle 2.8 release notes|Moodle 2.8 release notes]]

[[es:Actualización de moodle]]
[[fr:Mise à jour]]
[[ja:Moodleをアップグレードする]]
[[de:Aktualisierung von Moodle]]

Upgrading

2015-02-09T08:30:31Z

Lameze: /* Possible issues that may affect you in Moodle 2.8 */

{{Installing Moodle}}
''This page explains in detail how to upgrade Moodle. For a summary of the process, see [[Upgrade overview]].''

==Check the requirements==

Check that your server meets all requirements for 2.8 in ''Administration > Site administration > Server > [[Environment]]''.

Note: You can only upgrade to Moodle 2.8 from Moodle 2.2 or later. If upgrading from earlier versions, you must [https://docs.moodle.org/22/en/Upgrading_to_Moodle_2.2 upgrade to 2.2] as a first step.

==Before upgrading==

'''We advise that you test the upgrade first on a COPY of your production site, to make sure it works as you expect.'''

== Backup important data ==

There are three areas that should be backed up before any upgrade:
#Moodle software (For example, everything in server/htdocs/moodle)
#Moodle uploaded files (For example, server/moodledata)
#Moodle database (For example, your Postgres or MySQL database dump)

See [[Site backup]] for more specific information.

==Put your site into maintenance mode==
Before you begin upgrading your site, you should put it into [[Maintenance_mode | maintenance mode]] to stop any non-admin users from logging in.

== Check for plugin updates ==

If you have [[Automatic updates deployment]] enabled, you will be able to update installed plugins automatically during the upgrade. Just make sure you check for available updates (via the button for it) at the Plugins check screen.

If you are updating plugins manually, it is a good moment now to check in the [http://moodle.org/plugins Moodle Plugins directory] whether there is a 2.8 version available for any plugins (including themes) that you have previously installed on your site. If so, download the plugin package. In the next step, you will copy it to the appropriate location in your Moodle code (see [[Installing plugins]]).

The upgrade of the plugin will then happen as part of the Moodle upgrade process.

If an out-of-date plugin causes your upgrade to fail, you can usually delete the plugin code rather than uninstalling it from within Moodle so that the data associated with it is not deleted.

== Install the new Moodle software ==
You can fetch the current (2.8) version of the software through

wget http://sourceforge.net/projects/moodle/files/Moodle/stable28/moodle-latest-28.tgz

=== Standard install package ===

# Move your old Moodle software program files to another location. ''Do NOT copy new files over the old files.''
# Unzip or unpack the upgrade file so that all the new Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and moodledata if it needs to in the upgrade.
# Copy your old [[Configuration file|config.php file]] back to the new Moodle directory.
# As mentioned above, if you had installed any plugins on your site you should add them to the new code tree now. It is important to check that you get the correct version for your new version of Moodle. Be particularly careful that you do not overwrite any code in the new version of Moodle.
# Dont forget to also copy over your moodledata folder / directory. If you don't you will get a "fatal error $cfg- dataroot is not configured properly".

====Linux====
mv moodle moodle.backup
tar xvzf moodle-2.8.tgz

Next, copy across your config.php, any custom plugins, and your .htaccess file if you created one ('''check that custom plugins are the correct version for your new Moodle first'''):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to make moodle/config.php (and the rest of the source code) readable by your www server. Ideally the files should not be writeable by your server.

If you use cron, take care that cron.php is executeable and uses the correct php command:
chmod 740 admin/cli/cron.php (some configurations need chmod 750 or chmod 755)
copy the first line from cron.php (if it looks like '#!/usr/local/bin/php' or '#!/usr/local/bin/php5.3', no need to copy '<?php')

if necessary.

=== Using Git ===

You can use Git for updating or upgrading your Moodle. See [[Git for Administrators]] for details.

===Command line upgrade===

On Linux servers, Moodle 2.8 supports running the [[CLI|upgrade from the command line]], rather than through a web browser. This is likely to be more reliable, particularly for large sites.

== Finishing the upgrade ==

The last step is to trigger the upgrade processes within Moodle.

To do this just go to ''Administration > Site administration > Notifications''.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

Note: If you are running multiple servers then you should purge all caches manually (via ''Administration > Site administration > Development > Purge all caches'') after completing the upgrade on all servers.

===Fatal error: Maximum execution time of 30 seconds exceeded...===

If your server uses a main language other than English, you may encounter a 'Fatal error: Maximum execution time of 30 seconds exceeded' when you try to upgrade it. You can increase max_execution_time = 160 on php.ini to allow the scripts enough time to process the language update. Otherwise, you can switch to English as the default language before doing the upgrade and back to your original language after a succcessful upgrade. See the forum discussion at https://moodle.org/mod/forum/discuss.php?d=119598.

==After upgrading==

The config.php file from your installation should work fine but if you take a look at config-dist.php that came with Moodle 2.8 there are more/different options available (e.g. database drivers and settings). It's a good idea to map your old config.php settings to a new one based on the 2.8 config-dist.php.

===Cron===

Cron has received a major update (MDL-25499) and now has support for both scheduled and adhoc tasks.

The benefits of these changes are:
* The schedule for every task can be configured by the admin
* Tasks can run in parallel
* Cron processes use locking to prevent the same task running at the same time by different processes
* Clusters with multiple identical application nodes are supported, you can run cron on all of them

A result of this is that cron can be run much more often, which means (for example) forum posts can be sent out sooner. To take advantage of the new cron system it is now strongly recommended that administrators increase the frequency that cron is run to at least ''once per minute''.

You also may need to modify any automated scripts you have that are parsing the output from cron. It is no longer possible to simply monitor the output of cron for the string "Cron script completed correctly" (if that is what you were doing). An alternative is to monitor the output for the string "task failed:". If you detect that a task is failing, [[Cron#Debugging_Scheduled_Tasks|here]] are some tips for debugging the failure.

Before the upgrade to 2.8, there may have been a cron task that was failing, which was preventing the rest of cron from being executed. A failure in any single task will no longer prevent the rest of the Moodle cron tasks from executing, so you may uncover previously masked bugs. It is a good idea to closely monitor the output from cron after the upgrade to 2.8.

===Assignments===

The old assignment (2.2) module has been removed from core and has been replaced by a stub to support transparently remapping URLs and restoring course backups from the old module to the new one.

If you are still using the old assignment (2.2) module, after upgrading to Moodle 2.8 all assignment (2.2) activities will be hidden. You need to run the [[Assignment upgrade tool]] to un-hide the activities.

If you really, really need to keep using the old assignment (2.2) module, you should update the code to Moodle 2.8, and then replace the "mod/assignment" folder with the one from https://github.com/moodlehq/moodle-mod_assignment/releases before completing the upgrade.

==Possible issues that may affect you in Moodle 2.8==

===New aggregation method - 'Natural'===

The aggregation method 'Sum of grades' used in the [[Grades|gradebook]] has been reviewed, significantly improved and renamed to 'Natural'. It is recommended that 'Natural' is set as the default aggregation method, as for new Moodle 2.8 installs.

In addition, the aggregation setting 'Aggregate including subcategories' has been removed.

Any courses previously using either 'Sum of grades' and/or 'Aggregate including subcategories' may have some changes to grades. Thus it is recommended that grades in the gradebook are reviewed for such courses.

===Teachers able to enrol users via the cohort sync enrolment method===

Teachers will get access to [[Cohort sync]] enrolment method if it is enabled, remove capability to use this enrolment method from teachers if you want to preserve 2.7 behaviour. See MDL-36014

===Gradebook scrolling and theme issues===
Themes with non-fixed headers must have the .navbar class in their navbar in order for floating headers in the grader report to work - see MDL-46658 for more information.

===Removal of the 'Group members only' experimental setting===

The experimental setting 'Group members only' has been removed in Moodle 2.8. The group and grouping restrictions in [[Conditional activities settings|conditional activities]] now provide this functionality. Any 'Available for group members only' instances are automatically converted to group or grouping restrictions when a site is upgraded.

* 'Available for group members only' instances with no grouping selected are converted to a 'Must belong to any group' restriction.
* 'Available for group members only' instances with a grouping specified are converted to a 'Must belong to the specific grouping' restriction.

''More items to be added here...''

=== MySQL dmlwriteexceptionerror exception throw on course restoration ===

Some users are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This affect all moodle versions and is due MySQL default InnoDB file format (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the InnoDB file format to Barracuda.

Since 2.6 onwards we have a tool specially to help users on this conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

=== Moodle 2.3, 2.4, 2.5, 2.6 and 2.7 improvements ===

Depending on which version you are upgrading from, please see the section 'Possible issues that may affect you' in the documentation

* [https://docs.moodle.org/23/en/Upgrading Upgrading to Moodle 2.3]
* [https://docs.moodle.org/24/en/Upgrading Upgrading to Moodle 2.4]
* [https://docs.moodle.org/25/en/Upgrading Upgrading to Moodle 2.5]
* [https://docs.moodle.org/26/en/Upgrading Upgrading to Moodle 2.6]
* [https://docs.moodle.org/27/en/Upgrading Upgrading to Moodle 2.7]

==See also==

* [[Installation]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[dev:Moodle 2.8 release notes|Moodle 2.8 release notes]]

[[es:Actualización de moodle]]
[[fr:Mise à jour]]
[[ja:Moodleをアップグレードする]]
[[de:Aktualisierung von Moodle]]

Administration via command line

2015-02-09T08:11:18Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This affect all moodle versions and is due MySQL default InnoDB file format (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the InnoDB file format to Barracuda.

Since 2.6 onwards we have a tool specially to help users on this conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Administration via command line

2015-02-09T08:07:34Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This is due MySQL default InnoDB file format (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the InnoDB file format to Barracuda.

We've created a tool specially to help users on this conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Administration via command line

2015-02-09T08:04:50Z

Lameze:

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users upgrading to 2.8 are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This is due MySQL default type (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the default type to Barracuda.

We've created a tool specially to help users on this database type conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

More information about InnoDB file formats can be found here:
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope
http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Administration via command line

2015-02-09T07:41:31Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users upgrading to 2.8 are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This is due MySQL default type (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the default type to Barracuda.

We've created a tool specially to help users on this database type conversion. Please use the command below to do the database change.

php admin/cli/mysql_compressed_rows.php

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Administration via command line

2015-02-09T07:40:44Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users upgrading to 2.8 are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This is due MySQL default type (Antelope) cannot handle more than 10 text columns. We strongly recommend you change the default type to Barracuda.

We've created a tool specially to help users on this database type conversion. Please use the command below to do the change on your database.

php admin/cli/mysql_compressed_rows.php

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Administration via command line

2015-02-09T07:39:17Z

Lameze: /* Tool for converting innodb tables to Barracuda */

{{Installing Moodle}}
If you have shell access to your web server, you may find various CLI (command line interface) scripts useful during Moodle administration. Core admin CLI tools are located in the <code>admin/cli/*</code> folder. Other plugins provide their CLI functionality via scripts in their own cli folder. For example, the enrol_db sync script is located in <code>enrol/db/cli/</code>.

To avoid problems with access control, you should run them as the owner of the web server process. It is especially important for CLI installation and upgrade as they create new files in moodledata directory and the web server has to have write access to them. In Linux distributions, the user that runs the web server is usually apache or wwrun or httpd or something similar. As a root, you will probably want to execute Moodle CLI scripts like this:

$ cd /path/to/your/moodle/dir
$ sudo -u apache /usr/bin/php admin/cli/somescript.php --params

Most of the scripts accept common --help (or -h) parameter to display the full usage information, for example:

$ sudo -u apache /usr/bin/php admin/cli/install.php --help

== Upgrading via command line ==

Moodle can be upgraded from the command line. As with the installation script, there is either interactive or non-interactive mode of the upgrade. The script itself does not put the site into the maintenance mode, you have to do it on your own. Also, the script does not backup any data (if you read this page, you probably have some own scripts to backup your moodledata and the database, right?)

$ sudo -u apache /usr/bin/php admin/cli/upgrade.php

Upgrading via command line is a very comfortable way of Moodle upgrade if you use Git checkout of the Moodle source code (see [[Git for Administrators]]). See the following procedure how to upgrade your site within several seconds to the most recent version while preserving your eventual local customizations tracked in git repository:

$ cd /var/www/sites/moodle/htdocs/
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable
$ git pull
$ sudo -u apache /usr/bin/php admin/cli/upgrade.php
$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --disable

== Installation via command line ==

Since version 2.0, Moodle can be installed from the command line. There are two modes of installation. In interactive mode, the install script asks you for all data needed to properly set up new Moodle site. In non-interactive mode, you must provide all required data as the script parameters and then the new site is installed silently. The parameters can be passed in the interactive mode, too. The provided values are then used as the default values during the interactive session.

$ sudo -u apache /usr/bin/php admin/cli/install.php --lang=cs

== Maintenance mode ==

To switch your site into the maintenance mode via CLI, you can use

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enable

To turn the maintenance mode off, just execute the same script with --disable parameter.

== Offline mode ==

In some situations, you may want to switch your Moodle site into offline mode so that it is not accessible via the web but you can not stop the web server completely (typically because there are other web pages and applications running there). If a file called <code>climaintenance.html</code> exists in the root folder of moodledata directory, Moodle will automatically display the contents of that file instead of any other page.

$ cd /var/www/sites/moodle/moodledata/
$ echo '<h1>Sorry, maintenance in progress</h1>' > climaintenance.html

You can prepare a nice formatted HTML page to inform your users about the server being down and keep in the moodledata directory under a name like <code>climaintenance.off</code> and rename it to the <code>climaintenance.html</code> if needed.

== Custom site defaults ==

During the install and upgrade via CLI, Moodle sets the administration variables to the default values. You can use different defaults. See MDL-17850 for details. Shortly, all you need to do is to add a file <code>local/defaults.php</code> into your Moodle installation. The format of the file is like

<code php>
<?php
$defaults['pluginname']['settingname'] = 'settingvalue'; // for plugins
$defaults['moodle']['settingname'] = 'settingvalue'; // for core settings
</code>

These defaults are used during install, upgrade and are also displayed as defaults at the Site administration pages.

== Reset user password ==

If you happen to forget your admin password (or you want to set a password for any other user of your Moodle system), you can use reset_password.php script. The script sets the correctly salted password for the given user.

$ sudo -u apache /usr/bin/php admin/cli/reset_password.php

== MySQL storage engine conversion ==

If you run your Moodle site with MySQL database backend and use the default MyISAM as the storage engine for your tables, you may want to convert them to use some more reliable engine like InnoDB (actually, you should want to switch to PostgreSQL ;-) anyway).

$ sudo -u apache /usr/bin/php admin/cli/mysql_engine.php --engine=InnoDB

== Running cron via command line ==

In versions 1.x, you could execute admin/cron.php either from command line or via the web. Since Moodle 2.0, only admin/cli/cron.php script can be run via command line.

== Scheduled tasks ==

Since Moodle 2.7

Scheduled tasks are automatically run by the cron script above, but the specific tasks which run on each cron iteration are determined by the scheduled tasks configuration. It is possible to override the scheduled tasks configuration and run a single scheduled task immediately using the admin/tool/task/cli/schedule_task.php script.

This script accepts the following arguments:

--list - list all the known scheduled tasks. The tasks are listed by the class name used to run the task. This class name is required as the argument to the next option in order to run a specific task immediately.

--execute=<task> - Runs a single scheduled task immediately - regardless of scheduling settings. This will even run disabled tasks. Tasks will still use locking to prevent concurrent execution of the same task - even on clusters. The format of the <task> argument must be the same as returned by the --list option above.

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:

<pre>php schedule_task.php --list</pre>

will return something like:

<pre>
== List of scheduled tasks (http://yourserver.com/moodle) ==
\enrol_imsenterprise\task\cron_task 10 * * * * * ASAP
\logstore_legacy\task\cleanup_task * 5 * * * * ASAP
\logstore_standard\task\cleanup_task * 4 * * * * Wednesday, November 12, 2014, 4:35 AM
\mod_forum\task\cron_task * * * * * * ASAP
\core\task\automated_backup_task 50 * * * * * ASAP

...
</pre>

To run the first task in that list, you would execute

<pre>php schedule_task.php --execute=\\enrol_imsenterprise\\task\\cron_task</pre>

==Database transfer==

A command line script for [[Database transfer]] may be found in ''admin/tool/dbtransfer/cli/migrate.php''.

==Update user pictures via command line==

http://moodle.org/pluginfile.php/143/mod_forum/attachment/926929/updatepics.php
Tested for 2.3.1+

Place this file in /admin/cli/updatepics.php

How to use:
Run with "dir" option to specify which directory contains the files.

.../admin/cli/updatepics.php --dir=PATH_TO_DIR

* File names must be identical to usernames

==Manage MOD's,Blocks via command line==

Here are two scripts to help you manage your plugins.

http://tracker.moodle.org/browse/MDL-35736

How to use "manage_blocks.php":
place in /admin/cli

hide:
../admin/cli/manage_blocks.php --name=tag_youtube --hide

show:
../admin/cli/manage_blocks.php --name=tag_youtube --show

delete:
../admin/cli/manage_blocks.php --name=tag_youtube --delete

protect:
../admin/cli/manage_blocks.php --name=tag_youtube --protect

unprotect:
../admin/cli/manage_blocks.php --name=tag_youtube --unprotect

(obviously - replace "tag_youtube" with the blockthat you want to remove...)

How to use "manage_mods.php":

hide:
../admin/cli/manage_blocks.php --name=game --hide

show:
../admin/cli/manage_blocks.php --name=game --show

delete:
../admin/cli/manage_blocks.php --name=game --delete

*Important!
this script does not delete the relevant folder in /moodle/mod or /moodle/blocks

you have to delete it yourself !

==Update language pack via CLI==

http://tracker.moodle.org/browse/MDL-35735

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

==ReSort course list via CLI==

http://tracker.moodle.org/browse/MDL-36237

Place attached file in /admin/cli
and simply run it, without any command-line arguments :)

I import courses every night from an external system, and run this script afterwards

==Purge caches via CLI==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Tool for converting innodb tables to Barracuda==

Some users upgrading to 2.8 are getting the following MySQL error during the course restoration procedure:

Row size too large (>8126). Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.

This is due MySQL default type (Antelope) cannot handle more than 10 text columns. We strongly recommemd you change the default type to Barracuda.

We've created a tool specially to help users on this database type conversion. Please use the command below to do the change on your database.

php admin/cli/mysql_compressed_rows.php

[[fr:Administration en ligne de commande]]
[[de:Administration über Kommandozeile]]
[[ja:コマンドライン経由の管理]]
[[es:Administración por línea de comando]]

Reset course

2014-12-11T08:15:03Z

Lameze: /* Gradebook Reset Options */

{{Reusing activities}}
== Overview ==

This allows you to empty a course of user data, while retaining the activities and other settings. Please be warned when choosing items you will delete your chosen user data from this course forever!

You can select which user data to remove at a granular level under the categories of General, Roles, Gradebook, Groups and Activity data.

Note: Only users with the [[Capabilities/moodle/course:reset|reset course capability]] (by default managers and teachers) can reset a course.

== How to Reset - step by step ==

# Log in and go to the course area you want to reset
# Resetting a given activity is irreversible, so ensure that you have taken a Backup of your area including the user data - this is a snapshot and can be reinstated if necessary
# In your area's Administration block, click on Reset
# Click any Show Advanced button to show all options for that category
# Make your selections based on the options (see below for more on these)
# Click the Reset button
# Return to your area and check that things are as you want them.

== General Reset Options ==

You can set a new Course Start Date for the freshly reset course, delete all Calendar events, comments, course AND activity completion data and user notes attached to the course. Note that course logs are not deleted (See MDL-43274)

(Before you reset)
You will need to make sure that you back up the information that you have within your course before you reset. When you back up the course make sure that you back it up with the user information. That way you will have a back up data on the ones that have taken your course before you reset it for another group or department.

== Role Reset Options ==

These Role Reset options allow you to unenrol all users with a particular role within a course (e.g students) as well as remove all role overrides and role assignment specific to the course. This does not affect user role assignments outside the context of the course.

== Gradebook Reset Options ==

The Gradebook reset options allow you to delete all gradebook items and categories and/or delete all recorded grades within the course.
There are two options for gradebook reset:

'''Delete all grades''' - Removes all grade items within the course. Please note activity grade items are not removed in this option.

'''Delete all items and categories''' - Remove all categories and related grade items.

Note that these grades are still recorded against a user's account.

== Group Reset Options ==

The Group reset options provides you with the ability to delete all groups created in the course and/or remove all users from any groups within the course.

You can also delete all groupings created in the course and/or remove all users from any groupings within the course.

== Activity Reset Options ==

Depending on the activities used within a course, you will be provided with the option to remove the user data associated with these learning objects. This includes responses to Choices, Quiz attempts, Feedback Responses, Forum posts (from selected Forum types), Glossary entries etc.

You can remove all attempts from all quizzes.

For [[Workshop]] you can:
:delete all submissions
:delete all assessments
:switch to the setup phase

You can also specify a new course start date.

[[es:Reiniciar curso]]
[[fr:Réinitialisation]]
[[ja:コースのリセット]]
[[de:Kurs zurücksetzen]]

Grade export

2014-08-07T07:07:52Z

Lameze: /* XML file export */

{{Grades}}Grades can be exported to Excel spreadsheet, OpenDocument spreadsheet, plain text file or XML file.

''Grade export is NOT intended for students.''

==How to export grades==
[[Image:Grade export.png|thumb|left|Grade export]]To export grades from the gradebook:
# Choose an export format from the gradebook dropdown menu.
# Set options as required.
# If the course uses groups, select whether to export grades for all participants or for a particular group.
# Select the grade items to be included. Note that ID numbers are required for all activities for XML file export. An ID number field can be found in the common module settings for each activity.
# Click the submit button.
# After previewing the data on the following page, click the download button.

==XML file export==

To export grades to XML file, you need to ensure that:
* Users have ID numbers (an optional field in the user profile)
* Activities have ID numbers (an optional field in the common module settings)

'''Export new or updated grades only'''

To export only new or updated grades you need to enable '''XML File''' in ''Grades > General settings > Primary grade export methods (gradeexport)''.

After this setting has been enabled, the XML File option will then set and use a "last exported" field for every grade. The result will export the records with the <state> tag being identified as new or regraded.

This means the report will track the last exported date. If you export and then try again, it will not show any results because there are no new or updated grades since the last export.

==Default grade export settings==

The grade export display type and grade export decimal points site-wide defaults may be set by an administrator in ''Site administration > Grades > [[General grade settings|General settings]]''.

==User profile fields export==

In Moodle 2.4 onwards, an administrator can specify user profile fields and custom profile fields to be included in the grade export in ''Site administration > Grades > General settings''.

==Grade publishing==
[[Image:Grade publishing settings.png|thumb|left|Grade publishing settings]]
Grade publishing is a way of importing and exporting grades via a URL without being logged in to Moodle. Grade publishing is intended for administrators only, due to the security implications.

Grade publishing is disabled by default. It can be enabled by an administrator by checking the gradepublishing box in ''Settings > Site administration > Grades > [[General grade settings|General settings]]''. Users with grade publishing capabilities (normally administrators only) are then provided with grade export publishing settings.

To determine the URL for exporting grades, follow an export format link e.g. XML file, select a user key or 'Create a new key' to generate a new one, select other options as required, then click the Submit button. A download URL e.g. <code><nowiki>http://qa.moodle.net/grade/export/xml/dump.php?id=2&groupid=&itemids=-1&export_letters=&export_feedback=0&updatedgradesonly=0&displaytype=1&decimalpoints=2&key=ed18257297c48d15096dd49c1d09ac06</nowiki></code> will then be provided.

==Grade export capabilities==

* [[Capabilities/gradeexport/ods:publish|Publish ODS grade export]]
* [[Capabilities/gradeexport/ods:view|Use OpenDocument grade export]]
* [[Capabilities/gradeexport/txt:publish|Publish text file grade export]]
* [[Capabilities/gradeexport/txt:view|Use text file grade export]]
* [[Capabilities/gradeexport/xls:publish|Publish XLS grade export]]
* [[Capabilities/gradeexport/xls:view|Use Excel grade export]]
* [[Capabilities/gradeexport/xml:publish|Publish XML grade export]]
* [[Capabilities/gradeexport/xml:view|Use XML grade export]]

==Tips and tricks==
*Export grades in a spreadsheet format. Then copy and paste that information into another file that has worksheet ("raw grades"). Create other worksheets which are custom reports which take their data from "raw grades". This works if graded activities are '''not''' moved around to different positions in the course. This allows you to create a standard printed report(s). For example a compact landscape report of all students and all grades for each activity, a report of just quizes, another of lessons, another of assignments. A pivot table of students by scores, generated from a report worksheet, which gets its data from the raw data.
*Mailmerge exported grades into custom documents. For example, a document that is given to a department to file as a proof of training, with scores for every subject quiz.

==See also==

*[[:dev:Gradebook export]] developer documentation
*[http://www.youtube.com/watch?v=yZcbN_7p2zI Video showing how to export grades in Moodle 1.9]

[[es:Exportar_calificaciones]]
[[fr:Exportation des notes]]
[[ja:評定のエクスポート]]
[[de:Bewertungen exportieren]]

Grade export

2014-08-07T06:41:27Z

Lameze: /* XML file export */

{{Grades}}Grades can be exported to Excel spreadsheet, OpenDocument spreadsheet, plain text file or XML file.

''Grade export is NOT intended for students.''

==How to export grades==
[[Image:Grade export.png|thumb|left|Grade export]]To export grades from the gradebook:
# Choose an export format from the gradebook dropdown menu.
# Set options as required.
# If the course uses groups, select whether to export grades for all participants or for a particular group.
# Select the grade items to be included. Note that ID numbers are required for all activities for XML file export. An ID number field can be found in the common module settings for each activity.
# Click the submit button.
# After previewing the data on the following page, click the download button.

==XML file export==

To export grades to XML file, you need to ensure that:
* Users have ID numbers (an optional field in the user profile)
* Activities have ID numbers (an optional field in the common module settings)

'''Export new or updated grades only'''

To export only the new or updated grades you need to enable XML File on
''Grades > General settings > Primary grade export methods (gradeexport)''.

After enable XML File option will then set and use a "last exported" field for every grade. The result in exported records with ''<state>'' tag, being identified as ''new'' or ''regraded''.

This means the report will track last exported date, if you exported once and try to export again it will not show any results, because there's no new or update grades since last export.

==Default grade export settings==

The grade export display type and grade export decimal points site-wide defaults may be set by an administrator in ''Site administration > Grades > [[General grade settings|General settings]]''.

==User profile fields export==

In Moodle 2.4 onwards, an administrator can specify user profile fields and custom profile fields to be included in the grade export in ''Site administration > Grades > General settings''.

==Grade publishing==
[[Image:Grade publishing settings.png|thumb|left|Grade publishing settings]]
Grade publishing is a way of importing and exporting grades via a URL without being logged in to Moodle. Grade publishing is intended for administrators only, due to the security implications.

Grade publishing is disabled by default. It can be enabled by an administrator by checking the gradepublishing box in ''Settings > Site administration > Grades > [[General grade settings|General settings]]''. Users with grade publishing capabilities (normally administrators only) are then provided with grade export publishing settings.

To determine the URL for exporting grades, follow an export format link e.g. XML file, select a user key or 'Create a new key' to generate a new one, select other options as required, then click the Submit button. A download URL e.g. <code><nowiki>http://qa.moodle.net/grade/export/xml/dump.php?id=2&groupid=&itemids=-1&export_letters=&export_feedback=0&updatedgradesonly=0&displaytype=1&decimalpoints=2&key=ed18257297c48d15096dd49c1d09ac06</nowiki></code> will then be provided.

==Grade export capabilities==

* [[Capabilities/gradeexport/ods:publish|Publish ODS grade export]]
* [[Capabilities/gradeexport/ods:view|Use OpenDocument grade export]]
* [[Capabilities/gradeexport/txt:publish|Publish text file grade export]]
* [[Capabilities/gradeexport/txt:view|Use text file grade export]]
* [[Capabilities/gradeexport/xls:publish|Publish XLS grade export]]
* [[Capabilities/gradeexport/xls:view|Use Excel grade export]]
* [[Capabilities/gradeexport/xml:publish|Publish XML grade export]]
* [[Capabilities/gradeexport/xml:view|Use XML grade export]]

==Tips and tricks==
*Export grades in a spreadsheet format. Then copy and paste that information into another file that has worksheet ("raw grades"). Create other worksheets which are custom reports which take their data from "raw grades". This works if graded activities are '''not''' moved around to different positions in the course. This allows you to create a standard printed report(s). For example a compact landscape report of all students and all grades for each activity, a report of just quizes, another of lessons, another of assignments. A pivot table of students by scores, generated from a report worksheet, which gets its data from the raw data.
*Mailmerge exported grades into custom documents. For example, a document that is given to a department to file as a proof of training, with scores for every subject quiz.

==See also==

*[[:dev:Gradebook export]] developer documentation
*[http://www.youtube.com/watch?v=yZcbN_7p2zI Video showing how to export grades in Moodle 1.9]

[[es:Exportar_calificaciones]]
[[fr:Exportation des notes]]
[[ja:評定のエクスポート]]
[[de:Bewertungen exportieren]]

Grade export

2014-08-07T03:58:09Z

Lameze: /* XML file export */

{{Grades}}Grades can be exported to Excel spreadsheet, OpenDocument spreadsheet, plain text file or XML file.

''Grade export is NOT intended for students.''

==How to export grades==
[[Image:Grade export.png|thumb|left|Grade export]]To export grades from the gradebook:
# Choose an export format from the gradebook dropdown menu.
# Set options as required.
# If the course uses groups, select whether to export grades for all participants or for a particular group.
# Select the grade items to be included. Note that ID numbers are required for all activities for XML file export. An ID number field can be found in the common module settings for each activity.
# Click the submit button.
# After previewing the data on the following page, click the download button.

==XML file export==

To export grades to XML file, you need to ensure that:
* Users have ID numbers (an optional field in the user profile)
* Activities have ID numbers (an optional field in the common module settings)

'''Export new or updated grades only'''

To export only the new or updated grades you need to enable XML File on
''Grades > General settings > Primary grade export methods (gradeexport)''.

After enable XML File option will then set and use a "last exported" field for every grade.

This might result in exported records with ''<state>'' tag, being identified as ''new'' or ''regraded''.

==Default grade export settings==

The grade export display type and grade export decimal points site-wide defaults may be set by an administrator in ''Site administration > Grades > [[General grade settings|General settings]]''.

==User profile fields export==

In Moodle 2.4 onwards, an administrator can specify user profile fields and custom profile fields to be included in the grade export in ''Site administration > Grades > General settings''.

==Grade publishing==
[[Image:Grade publishing settings.png|thumb|left|Grade publishing settings]]
Grade publishing is a way of importing and exporting grades via a URL without being logged in to Moodle. Grade publishing is intended for administrators only, due to the security implications.

Grade publishing is disabled by default. It can be enabled by an administrator by checking the gradepublishing box in ''Settings > Site administration > Grades > [[General grade settings|General settings]]''. Users with grade publishing capabilities (normally administrators only) are then provided with grade export publishing settings.

To determine the URL for exporting grades, follow an export format link e.g. XML file, select a user key or 'Create a new key' to generate a new one, select other options as required, then click the Submit button. A download URL e.g. <code><nowiki>http://qa.moodle.net/grade/export/xml/dump.php?id=2&groupid=&itemids=-1&export_letters=&export_feedback=0&updatedgradesonly=0&displaytype=1&decimalpoints=2&key=ed18257297c48d15096dd49c1d09ac06</nowiki></code> will then be provided.

==Grade export capabilities==

* [[Capabilities/gradeexport/ods:publish|Publish ODS grade export]]
* [[Capabilities/gradeexport/ods:view|Use OpenDocument grade export]]
* [[Capabilities/gradeexport/txt:publish|Publish text file grade export]]
* [[Capabilities/gradeexport/txt:view|Use text file grade export]]
* [[Capabilities/gradeexport/xls:publish|Publish XLS grade export]]
* [[Capabilities/gradeexport/xls:view|Use Excel grade export]]
* [[Capabilities/gradeexport/xml:publish|Publish XML grade export]]
* [[Capabilities/gradeexport/xml:view|Use XML grade export]]

==Tips and tricks==
*Export grades in a spreadsheet format. Then copy and paste that information into another file that has worksheet ("raw grades"). Create other worksheets which are custom reports which take their data from "raw grades". This works if graded activities are '''not''' moved around to different positions in the course. This allows you to create a standard printed report(s). For example a compact landscape report of all students and all grades for each activity, a report of just quizes, another of lessons, another of assignments. A pivot table of students by scores, generated from a report worksheet, which gets its data from the raw data.
*Mailmerge exported grades into custom documents. For example, a document that is given to a department to file as a proof of training, with scores for every subject quiz.

==See also==

*[[:dev:Gradebook export]] developer documentation
*[http://www.youtube.com/watch?v=yZcbN_7p2zI Video showing how to export grades in Moodle 1.9]

[[es:Exportar_calificaciones]]
[[fr:Exportation des notes]]
[[ja:評定のエクスポート]]
[[de:Bewertungen exportieren]]