MoodleDocs - User contributions [en]

admin/environment/php extension/intl

2025-02-15T11:04:03Z

Leonstr: Tidy up formatting

{{Environment}}
The Internationalization extension (Intl) is a wrapper for the ICU library, a set of C/C++ and Java libraries that provide Unicode and Globalization support for software applications. It enables PHP programmers to perform UCA-conformant collation and date/time/number/currency formatting in their scripts.

The Intl extension is required in Moodle 3.4 onwards.

== Microsoft Windows ==

To enable this extension add the following line to your php.ini file usually found in /php:

extension=php_intl.dll

And then set the ''intl.default_locale'' and ''intl.error_level'' directives in your php.ini file.

[intl]
intl.default_locale=en_utf8
intl.error_level=E_WARNING

The ''intl.error_level'' directive is optional.

In a WAMP installation it may be required to add the php path to the system PATH so that the module4 could uploaded properly (see http://forum.wampserver.com/read.php?2,80704,82499 for a couple of other approaches).

===Problems in Windows 11 VirtualBox virtual machines===
If you had the ''msvcp110.dll missing file error'', you added that file and then you got the ''intl missing error'' which can not be solved by doing the above instructions, you need to go to http://www.microsoft.com/es-es/download/confirmation.aspx?id=30679 and install the vcredist_x64.exe and vcredist_x86.exe, as described in https://stackoverflow.com/a/18876880

==Other operating systems==

Use system package manager or specify compilation flag.

*Debian 5.0 (& Ubuntu) use: '''apt-get install php-intl'''.

*CentOS 8.0 (& Red Hat) use: '''dnf install php-intl'''. CentOS 7.0 (& Red Hat) use: '''yum install php-intl'''. The package name may be slightly different depending on the repository used for PHP packages, e.g. '''php74-intl'''.

==See also==

*[http://www.php.net/manual/en/intro.intl.php INTL Introduction]
*[http://www.php.net/manual/en/book.intl.php PHP Internationalization Functions]
*[https://docs.moodle.org/en/Table_of_locales Table of locales] lists the locales that you can use.

[[Category:Environment|PHP]]

[[fr:admin/environment/php extension/intl]]
[[es:admin/environment/php extension/intl]]

Quiz submission email notification

2023-11-08T15:35:57Z

Leonstr: /* Allow Quiz notification messages to teachers */

{{Quiz}}
It is possible for a message to be sent out to confirm that the student submitted the quiz.

There are two types of notification:
#A confirmation to the student that their attempt has finished successfully
#A notification to the teacher(s) that someone has submitted an attempt. Messages are never sent for preview attempts.

Note that although the capabilities are "emailnotifysubmission/emailconfirmsubmission" the notifications do NOT have to be via email. The notifications come via Moodle's messaging system. Admins can set the defaults from ''Administration > Site administration > Plugins > Message outputs > Default message outputs'' to enable/disable email/pop up notification.
{|
| [[File:quizsubmissionnotificationdefault.png|thumb|Quiz submission notification default settings]]
|}

See [[Messaging settings]] for more details. (Notification messages in Moodle quiz are disabled by default.)

==Allow Quiz notification messages to teachers==

To do this for an individual quiz, click into the quiz, click the gear icon top right and click Permissions (Boost theme) or for other themes, click Permissions from the Quiz administration block.

This may also be done on the site level by the administrator in ''Administration > Site administration > Users > Permissions > Define roles > Teacher''

#In the filter, type "email" to locate the capability "mod/quiz:emailnotifysubmission"
#Click on the + for "Roles with permission"
#On the next screen, select Teacher and click "Allow"

[[File:QuizEmailNotifySub.png]]
===Messages in a specific quiz to specific teacher(s)===
The system administrator will need to create a new role, and allow the capability ''mod/quiz:emailnotifysubmission'' for that role. Do not give the capability to the teacher's role on the system or course level. The new role is similar to a teacher's role and should be available on the activity level.

In the course, go to the quiz and the quiz administration>locally assigned roles, assign the user(s) that should get emails/messages for a submitted quiz to the new role.

==Allow confirmation messages to students==
To do this for an individual quiz, go to:
''Administration > Quiz administration > Permissions''

This may also be done on the site level by the administrator in ''Administration > Site administration > Users > Permissions > Define roles > Student''

#In the Capability column under ''Activity: Quiz'' find the capability ''mod/quiz:emailconfirmsubmission''
#Click on the +
#On the next screen, select Student and click "Allow"

{|
| [[File:studentno.png|thumb|1. Click the + to add a role]]
| [[File:studentadd.png|thumb|2. Select Student and click "Allow"]]
| [[File:studentyes.png|thumb|3. Students will now receive messages]]
|}

==Notes==
:Note that if the quiz is set to separate groups, then teachers will only get a notification if either
* the student is in the same group as the teacher, or
* the teacher has moodle/site:accessallgroups.

==How to configure the text of the messages==
''Administration > Site administration > Language > Language customization''

This can only be done by a user that has permission to alter the language files. To reconfigure the way the email reads, you will need to understand string variables and how they work as part of another string. While not complicated, this will require attention to detail. This section assumes you also have read [[Language customization]].

The subject and body of the emails are defined in the quiz.php language file that are in the "mod" group. The strings to edit are 'emailconfirmsubject', 'emailconfirmbody', 'emailnotifysubject' and 'emailnotifybody'. The $a string passed in when these language strings are loaded contains all the following information:

===The emailconfirmbody string===
<nowiki> Dear {$a->username}, Thank you for submitting your answers to '{$a->quizname}' in course '{$a->coursename}' at {$a->submissiontime}. This message confirms that we have safely received your answers. You can access this quiz at {$a->quizurl}.</nowiki>

===The emailnotifybody string===
<nowiki>Dear {$a->username}, {$a->studentname} has completed the quiz '{$a->quizname}' ({$a->quizurl}) in course '{$a->coursename}' You can review this attempt at {$a->quizreviewurl}.</nowiki>

=== The emailnotifysmall===
<nowiki>{$a->studentname} has completed {$a->quizname}</nowiki>

===The emailnotifysubject string===
<nowiki>Quiz submission confirmation: {$a->quizname}</nowiki>

===Potential strings to use in an email===
;$a->coursename
:The name of the course
;$a->courseshortname
:The shortname of the course
;$a->quizname
:The name of the quiz
;$a->quizreporturl
:The URL of the results overview for this quiz (.../mod/quiz/report.php?q=''quizid'')
;$a->quizreportlink
:The URL of the results overview URL and quiz name as a HTML link
;$a->quizreviewurl
:The URL of the review page for this attempt (.../mod/quiz/review.php?attempt=''attemptid'')
;$a->quizreviewlink
:The attempt review URL and quiz name as a HTML link
;$a->quizurl
:The URL of the main page of the quiz (.../mod/quiz/view.php?q=''quizid'')
;$a->quizlink
:The URL of the quiz and the quiz name as a HTML link
;$a->attemptsubmissiontime
:The time the attempt was submitted, formatted using userdate().
;$a->timetaken
:How long the quiz attempt lasted.
;$a->studentname
:The name of the person who submitted the quiz.
;$a->studentidnumber
:The idnumber of the person who submitted the quiz.
;$a->studentusername
:The username of the person who submitted the quiz.
;$a->username
:The name of the user the email is being sent to.
;$a->useridnumber
:The idnumber of the user the email is being sent to.
;$a->userusername
:The username of the user the email is being sent to.

[[ja:解答送信の通知メール]]
[[de:E-Mail-Benachrichtigung bei Testabgabe]]
[[es:Notificación Email sobre envío de examen]]

Feedback settings

2023-11-08T11:42:41Z

Leonstr: /* Map feedback to courses */

{{Feedback}}
This page explores in more detail the settings for the Feedback activity once you have added it to your course and also covers the Site administration settings.

The Feedback activity is enabled by default in new sites but if you don't see it in a course, ask your administrator to check if it is disabled site wide.

The [[Feedback block]] works with the [[Feedback activity]] to display a list of global Feedback activities associated with a course.
==General==
In the Description, provide instructions for students. Check the box if you want these instructions to display on the course page.
==Availability==
Here you can choose when users can complete feedback.
==Question and submission settings==
:Record user names
:Choose here whether to show the names of users who complete the feedback or not.
;Allow multiple submissions
:Choose here whether or not to allow users to complete the feeback more than once. This is important when using Feedback for anonymous surveys on the front page as it will allow non-logged in users to complete the feedback.
;Enable notification of submissions
:If set to 'Yes' then teachers will receive notifications when users submit feedback.
;Auto-number questions
:If set to 'Yes' then the questions will be automatically numbered.
==After submission==
;Show analysis page
:Choose whether to show students the analyis page or only show to teachers.
;Completion message
:Type a personalised message here that students will read after completing the feedback.
;Link to next activity
:This allows you to add a URL to another activity or webpage which you would like them to go to once they have answered the questions.
''Note:'' Neither of the above fields is required for a student to answer the questions, but they must click the '''Answer the questions...''' link to start the Feedback activity.
==Other settings==
Depending on what is enabled for your site and course, you may also need to explore [[Common module settings]], [[Restrict access| Restrict access]], [[Activity completion]], [[Tags]] and [[Competencies]]

==Map feedback to courses==
If a feedback instance is added to the front page there is an option, when 'Save and display' is clicked, to map the feedback to courses. All courses or certain courses may be selected. (In other words, if you only want the feedback to be available in certain courses but not all, you would choose just those courses.) The [[Feedback block]] can then be added to those courses and it provides a quick link to the Feedback activity.

To map to a course, first type in the name of a course and press the Search button. You will then be presented with a drop down menu from which you may choose your course. Click the 'map feedback' button to add it. Repeat this to add another course. If you don't choose a course then the feedback will be mapped to all courses by default.

==Site administration settings==
The Feedback activity has additional settings which may be changed by an administrator in ''Administration > Site administration > Plugins > Activity modules > Feedback''.
===Allow full anonymous===
Changing this setting to "yes" permits non-logged in users on the front page to complete a feedback activity. Notice that anonymous feedback is not anonymous in the sense that [[GDPR]] describes it.
==Feedback capabilities==
*[[Capabilities/mod/feedback:complete|Complete a feedback]]
*[[Capabilities/mod/feedback:createprivatetemplate|Create private template]]
*[[Capabilities/mod/feedback:createpublictemplate|Create public template]]
*[[Capabilities/mod/feedback:deletesubmissions|Delete completed submissions]]
*[[Capabilities/mod/feedback:deletetemplate|Delete template]]
*[[Capabilities/mod/feedback:edititems|Edit items]]
*[[Capabilities/mod/feedback:mapcourse|Map courses to global feedbacks]]
*[[Capabilities/mod/feedback:receivemail|Receive email notification]]
*[[Capabilities/mod/feedback:view|View a feedback]]
*[[Capabilities/mod/feedback:viewanalysepage|View the analysis page after submit]]
*[[Capabilities/mod/feedback:viewreports|View reports]]
*[[Capabilities/mod/feedback:addinstance|Add a new feedback]]
[[de:Feedback konfigurieren]]
[[es:Configuraciones de retroalimentación]]

Course copy

2023-08-10T15:52:45Z

Leonstr: Course copy was always async so unaffected by enableasyncbackup, asynchronous_copy_task is an adhoc task so cannot be disabled

{{Backup}}
==About course copy==
Administrators, managers and those with the relevant capabilities can quickly copy courses from a course category or within a course.
{{MediaPlayer | url = https://youtu.be/-V8z3jlOygc| desc = Course copy}}

==Course copy from Course and category management screen==
# From ''Site administration / Courses / Manage courses and categories'', click to select a category.
# Find the course you want to copy, and click the duplicate icon to copy the course.

[[File:CategoryCopyCourse.png|center|Copying courses from a category]]

==Course copy from within a course==
# Access the course you want to copy.
# From Course navigation > More > Course reuse, select 'Course copy'.

==Course copy settings==
As well as setting the course name, category, visibility and dates, you can make the following selections:
* Include user data - Similar to in a course backup, you can decide whether or not to include the data of any users with the roles in your course who will be included in the next setting.
* Include role enrolments - If you select a role here then users with that role will be enrolled into the copied course, either with or without their user data, depending on the previous setting.

==Allow teachers to copy courses==
To allow a course teacher (or any role other than an admin or manager) to copy courses, the role needs the following capabilities:

* [[Capabilities/moodle/backup:backupcourse]]
* [[Capabilities/moodle/restore:restorecourse]]
* [[Capabilities/moodle/course:view]]
* [[Capabilities/moodle/course:create]]

Besides, if you want they can include user data (i.e. keep role enrolments), the role will need the following capabilities too:

* [[Capabilities/moodle/restore:createuser]]
* [[Capabilities/moodle/backup:userinfo]]
* [[Capabilities/moodle/restore:userinfo]]

==Troubleshooting==

If course copying fails to complete, please check [[Cron]] is running every minute

If there is a quiz in the course and you are a teacher or manager this feature does not currently work. For more information see MDL-69941

[[es:Copia del curso]]
[[de:Kurs kopieren]]

Dashboard

2023-08-08T09:07:30Z

Leonstr: /* See also */ "The content of this forum post has been removed and can no longer be accessed"

{{Site appearance}}
==About the Dashboard==
The Dashboard is a customisable page for providing users with details of their progress and upcoming deadlines.

The default dashboard includes a [[Timeline block|Timeline]], [[Calendar]] and from the Block drawer, the [[Recently accessed items block]].

Quick access to Dashboard is also available from the site navigation at the top of the screen once logged in.

Users can normally customise their Dashboard, adding or removing blocks and changing block positions. They can revert their Dashboard back to the original blocks as follows:

# Activate the 'Edit mode' switch.
# Click the 'Reset page to default' button.

(Note that an administrator can reset the Dashboard for all users from 'Default Dashboard page' in the Site administration).
==Hiding the Dashboard==
If deadlines and calendar events are not used in your site then the Dashboard may be removed from the top navigation from Site administration > Appearance > Navigation and unchecking 'Enable Dashboard'. A different home page can then be set for users.

==Default home page==

For new installations, Dashboard is the default home page for logged in users. An administrator can change the default home page in ''Administration > Site administration > Appearance > Navigation''.

If 'User preference' is selected as default home page, each user needs to set the desired page – Home, My courses or Dashboard – under User menu > Preferences > User account > Home page. Once selected, Moodle will remember which page to present them each time they log on.

[[File:defaulthomepagelink.png|300px]]

==Setting the default Dashboard==

An administrator or manager (or other user with the capability [[Capabilities/moodle/my:configsyspages|moodle/my:configsyspages]]) can set the default blocks for all users from ''Administration > Site administration > Appearance > Default Dashboard page''.

Clicking the button 'Reset Dashboard for all users' will then apply these settings to the Dashboard for everyone on the site.

Default blocks are:
* [[Navigation block|Navigation]]
* [[Administration block|Administration]]
* [[Course overview block|Course overview]]
* [[Private files block|Private files]]
* [[Latest badges block|Latest badges]]
* [[Calendar block|Calendar]]
* [[Upcoming events block|Upcoming events]]
* [[Online users block|Online users]]

==Preventing users from customizing their Dashboard==

By default, users can customize their Dashboard and add blocks. An admin can prevent this as follows:

# Go to ''Administration > Site administration > Users > Permissions > Define roles''
# Edit the authenticated user role and untick the [[Capabilities/moodle/my:manageblocks|Manage Dashboard blocks capability]]

==Dashboard capabilities==

* [[Capabilities/moodle/my:manageblocks|Manage Dashboard blocks]] (see above)
* [[Capabilities/moodle/my:configsyspages|Configure system templates for Dashboard]]

In addition, all blocks which may be added to a Dashboard have a ''myaddinstance'' capability (e.g. [[Capabilities/block/comments:myaddinstance|block/comments:myaddinstance]]) for controlling whether a user with a particular role can add the block.

==Preventing users from adding a block to their Dashboard==

By default, users can add many blocks to their Dashboard. An admin can prevent them from adding a particular block, such as the [[Online users block]], as follows:

# Go to ''Administration > Site administration > Users > Permissions > Define roles''
# Edit the authenticated user role and untick the [[Capabilities/block/online users:myaddinstance|Add a new online users block to the Dashboard capability]]

==Blocks not available on the Dashboard==

The following blocks may not be added to a user's Dashboard (because it wouldn't make sense):

*[[Course completion status block]]
*[[Course/site summary block]]
*[[Self completion block]]

==See also==

* [https://moodle.org/mod/forum/discuss.php?d=340126 Show Categories of courses on Dashboard after sign in] forum discussion

[[eu:Nire_Moodle]]
[[fr:Tableau de bord]]
[[de:Dashboard]]
[[es:Tablero]]

MySQL full unicode support

2023-08-07T10:43:22Z

Leonstr: /* UTF-8 */ Added note about utf8 in recent MySQL/MariaDB versions

{{Environment}}
==UTF-8==

UTF-8 is a character encoding that most websites use. It encodes each of the 1,112,064 valid code points. To store all of this information, four bytes is required. The most popular values are in the three byte region. MySQL by default only uses a three byte encoding and so values in the four byte range (e.g. Asian characters and Emojis) can not be stored. Any attempt to enter a text that contains four byte characters will result in a Moodle database error.

MySQL does provide full four byte UTF-8 support, but it requires certain database settings to be configured. From version 3.3 on Moodle uses full UTF-8 for both MySQL and MariaDB by default. Existing databases will still run with partial support, but it is recommended to move over to full support.

Moodle comes with a Command Line Interface (CLI) script for converting to full UTF-8 for MySQL (and MariaDB). Before Moodle versions 3.1.5 and 3.2.2 this conversion tool would only change the Collation to some variant of 'utf8_bin'. 'utf8_unicode_ci' was the recommended Collation. We now recommend using 'utf8mb4_unicode_ci' which supports four byte characters (utf8_unicode_ci only supports three).

This script will attempt to change the database Collation, Character set, default table settings and column definitions.

To summarise:

* Fresh installs of Moodle will use utf8mb4 by default, if the database server is configured appropriately (see below).
* Sites upgrading to Moodle versions beyond 3.1.5 or 3.2.2 can use the script to update to utf8mb4. In Moodle 3.3 onwards a warning will show that the database isn't using full UTF-8 support and suggest moving to 'utf8mb4_unicode_ci'.
* You may choose to keep using 'utf8_*' unless you have MySQL 8.0.28 or later, or MariaDB 10.6.1 or later, in which case you must update to utf8mb4 (because utf8 was renamed to utf8mb3 in these versions, see MDL-74616).

===File format===

To allow for large indexes on columns that are a varchar, a combination of settings needs to be set. The file format for the system needs to be using "Barracuda". This allows for the row format to be set to "Compressed" or "Dynamic". To enable this setting see the upgrade steps listed below. Moodle will not install if you have large format enabled without the Barracuda file format.

===File per table===

To enable this setting see the upgrade steps listed below.

===Large prefix===

This in conjunction with the row format being either "Compressed" or "Dynamic" allows for large varchar indexes above 191 characters.
To enable this setting see the upgrade steps listed below.

==Steps to upgrade==

Most important: Please backup your database before making any changes or running the CLI script.

* Change configuration settings for MySQL (exactly the same for MariaDB). This step is optional. You can run the script and it will try and make these changes itself. If errors occur then try manually changing these settings as listed below.
** On Linux based systems you will want to alter my.cnf. This may be located in '/etc/mysql/'.
** Make the following alterations to my.cnf:

Important Change; InnoDB: The following InnoDB file format configuration options were deprecated in MySQL 5.7.7 and are now removed:

innodb_file_format

innodb_file_format_check

innodb_file_format_max

innodb_large_prefix

<syntaxhighlight lang="ini">
[client]
default-character-set = utf8mb4

[mysqld]
innodb_file_format = Barracuda
innodb_file_per_table = 1
innodb_large_prefix = true

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
skip-character-set-client-handshake

[mysql]
default-character-set = utf8mb4
</syntaxhighlight>
* Restart your MySQL server.
* Run the CLI script to convert to the new character set and collation (requires Moodle 3.1.5, 3.2.2 or newer):
<pre>
$ php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci
</pre>
* Make sure to repair and optimize all databases and tables.
<pre>
mysqlcheck -u root -p --auto-repair --optimize --all-databases
</pre>
NOTE: On very large sites this may take a long time to run. You should probably establish how long on a test install before taking your live site offline. In some cases you might consider dumping and re-importing your data.

* Adjust the $CFG->dboptions array in your '''config.php''' to make sure that Moodle uses the right collation when connecting to the MySQL Server:
<pre>
$CFG->dboptions = array(
…
'dbcollation' => 'utf8mb4_unicode_ci',
…
);
</pre>

If you only have access to the database command line (or something like phpMyaAdmin) you can try the following SQL commands:
<syntaxhighlight lang="sql">
SET GLOBAL innodb_file_format = barracuda;

SET GLOBAL innodb_file_per_table = 1;

SET GLOBAL innodb_large_prefix = 'on';
</syntaxhighlight>

* Try adding some Emojis (e.g. 😂💩) to your Moodle site to verify that the upgrade was successful.

[[Category:Environment|UTF-8]]
[[Category:UTF-8]]

[[es:MySQL soporte unicode completo]]
[[fr:Support unicode complet pour MySQL]]
[[de:MySQL Unicode Unterstützung]]

MoodleDocs:Style guide

2023-07-15T09:22:08Z

Leonstr: Replace <code> with <syntaxhighlight>

{{Help}}
==Describing the location of items==

* A site admin setting may be referred to as, for example, the setting 'Maximum uploaded file size' in 'Site policies' in Site administration
* In the Boost theme, we have a navigation drawer and a gear menu. In the Classic theme we have a 'Course administration'
* In 3.2 we have a menu bar containing a notifications menu and a messages menu

Examples:
* Grades in the navigation drawer
* Groups from the gear menu on the Participants page
* 'Add a new badge' from the More... link in the gear menu on the course page
* Messages in the user menu

== Categories ==
A category is an index of documentation pages.

* A page can be added to a category by typing <code><nowiki>[[Category:Category name]]</nowiki></code>, for example <code><nowiki>[[Category:Site administration]]</nowiki></code>, at the bottom of the page. Many templates automatically categorise pages using the template, for example <code><nowiki>[[Template:Forum]]</nowiki></code> categorises pages into [[:Category:Forum]].
* For '''linking to a category''' you have to add another colon like so: <code><nowiki>[[:Category:FAQ]]</nowiki></code> which will show as [[:Category:FAQ]].
* [[Special:Categories|Categories]] lists all Moodle Docs categories. This can be found in the Toolbox Special pages link.
* For '''further information''' about categories and how they work in MediaWiki, please refer to the [https://en.wikipedia.org/wiki/Wikipedia:Categorization Wikipedia:Categorization].

== Screenshots ==
* You are encouraged to illustrate documentation with screenshots. Please use the official [https://sandbox.moodledemo.net/ Moodle demo site], or any other site or course using one of the standard themes, and ensure that the screenshot is as small as possible.
* Screenshots should be GIF, JPEG or PNG format, with 72ppi resolution, and maximum width 800px.
* To fit more into a screenshot, select a smaller text size for the web page via the View > Text size menu in your web browser.
* Screenshots can be uploaded using the toolbox [[Special:Upload|Upload file]] link.
* Please name screenshots descriptively to avoid confusion.
* To include the screenshot in an article, use a link in the form <code><nowiki>[[File:Screenshot.png|thumb|alt text]]</nowiki></code>.
* Please do not apply effects such as borders, watermarks or drop shadows to screenshots. This will allow others to add or replace screenshots over time and still maintain a consistent look and feel to articles.
* You can duplicate the look of the [http://school.moodledemo.net/ Mount Orange School] used in many Moodle documentation pages by following [[Standard_themes#Mount_Orange:_example_of_a_customised_More_theme|these instructions]].
* For help on image placement and adding an image caption, please refer to the [https://en.wikipedia.org/wiki/Wikipedia:Picture_tutorial Wikipedia Picture tutorial].

==Templates==
* In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.
* A template may be added to a page by typing <code><nowiki>{{Name}}</nowiki></code> for Template:''Name'' (template names are case sensitive).
* [https://docs.moodle.org/en/index.php?title=Special%3AAllpages&from=&namespace=10 All pages (Template namespace)] lists all Moodle Docs templates.
* Please refer to the [http://meta.wikimedia.org/wiki/Help:Template MediaWiki Template help] for further information.

==Moodle Docs editing tags==
*[[MoodleDocs:Deletion|Deletion]] - If you find any page requiring deletion, type <code><nowiki>{{Deletion}}</nowiki></code> at the top of the page. Use the page comments if necessary to state the reason for deletion.
*[[MoodleDocs:Update|Update]] - Features increase with each Moodle version. If you find a page requiring updating, type <code><nowiki>{{Update}}</nowiki></code> at the top of the page.
*[[:MoodleDocs:Stub|Stub]] - Developers and Moodle Docs administrators may add a new page with a <code><nowiki>{{Stub}}</nowiki></code> tag at the top, requesting help in adding content.
*You can also use the [[Help:Editing#Edit_summary|edit summary]] to communicate the need for more editing. For example, in the page history you might see: "Added section, needs more work, see page comments".

== PHP syntax highlighting ==

* To highlight PHP syntax, enclose the code in tags:
<pre><nowiki><syntaxhighlight lang="php">... Some PHP code here...</syntaxhighlight></nowiki></pre>

That will be rendered as:

<syntaxhighlight lang="php">
<?php
require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
print_error('invalidcoursemodule');
}
...
</syntaxhighlight>

* For long code examples you can even add '''line numbering''' like so:
<pre><nowiki><syntaxhighlight lang="php" line>... A lot of PHP code here...</syntaxhighlight></nowiki></pre>

That will be rendered as:

<syntaxhighlight lang="php" line>
<?php
require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
print_error('invalidcoursemodule');
}
...
</syntaxhighlight>

* But beware, line numbering makes copying & pasting of code examples more cumbersome!

== CSS syntax highlighting ==

* To highlight CSS syntax, enclose the code in tags:
<pre><nowiki><syntaxhighlight lang="css">... Some CSS code here...</syntaxhighlight></nowiki></pre>
* Example:
<syntaxhighlight lang="css">
.que .info .grade { display: none; }
</syntaxhighlight>
* You can see many examples of this in [https://docs.moodle.org/402/en/index.php?title=Quiz_FAQ&action=edit the Quiz FAQ Doc page].
* See also the documentation on [[Code syntax highlighting]] that uses the GeSHi (Generic Syntax Highlighter) filter.

[[Category:MoodleDocs|Style guide]]
[[de:Moodle Docs StyleGuide]]
[[es:MoodleDocs:Guía de Estilo]]
[[fr:MoodleDocs:Guide de style]]
[[ja:MoodleDocs:スタイルガイド]]
[[zh:MoodleDocs:风格指引]]

MySQL

2023-07-13T19:04:37Z

Leonstr: /* Command line */ FLUSH PRIVILEGES implicit when using GRANT https://stackoverflow.com/a/36464093/17436831

{{Installing Moodle}}
MySQL is one of the supported databases that underpins a Moodle installation.

== Installing MySQL ==

* If you are running Linux your preference should be to install using your distribution's package manager. This ensures you will get any available updates. However, you can also use apt-get or yum depending on the distribution that you are running.
* There are installers available for most popular operating systems at http://www.mysql.com/downloads/mysql/.
* It is possible and reasonably straightforward to build mysql from source but it is not recommended (the pre-built binaries are supposedly better optimised).
* Make sure you set a password for the 'root' user (see http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html).
* Consider installing and configuring my.cnf (the MySQL settings file) to suit your needs. The default configuration is usually very conservative in respect of memory usage versus performance. Increase the 'max_allowed_packet' setting to at least 4 megabytes.
* If you are going to use Master/Slave replication, you must add binlog_format = 'ROW' into your my.cnf within [mysqld]. Otherwise, Moodle will not be able to write to the database.

=== Configure full UTF-8 support ===

It's recommended that full UTF-8 support is configured in MySQL. If this is not done some character sets – notably emojis – cannot be used. It is possible to do this after installing your site but is much easier and quicker before installation.

Check if this is already configured by running the following statement, e.g. at the '''mysql>''' prompt or in phpMyAdmin:
<pre>SHOW GLOBAL VARIABLES WHERE variable_name IN ('innodb_file_format', 'innodb_large_prefix', 'innodb_file_per_table');</pre>

[[File:phpMyAdmin1.png|alt=innodb_file_format=Barracuda;innodb_file_per_table=ON;innodb_large_prefix=ON]] or [[File:phpMyAdmin2.png|alt=innodb_file_format=(blank);innodb_file_per_table=ON;innodb_large_prefix=(blank)]] or [[File:phpMyAdmin3.png|alt=innodb_file_per_table=ON]]

If the settings you see match any list above then no changes are needed and you can skip to [[#Creating_Moodle_database| Creating Moodle database]].

If your settings do not match any list you will have to edit the MySQL configuration file. On Linux this may be '''/etc/my.cnf''', '''/etc/mysql/my.cnf''', or '''/etc/my.cnf.d/mariadb-server.cnf'''; on Microsoft Windows it may be '''my.ini'''.

* Note: Back up the configuration file before changing it.
* Note: Back up all databases before making this change.
* Note: Other systems with databases on this server may be impacted by this change.

Add the following settings to the configuration file, do not add '''innodb_file_format = Barracuda''' and '''innodb_large_prefix = 1''' if these were blank or missing when you ran '''SHOW GLOBAL VARIABLES''' above:
<pre>[client]
default-character-set = utf8mb4

[mysqld]
innodb_file_format = Barracuda # Remove line if not needed
innodb_file_per_table = 1
innodb_large_prefix = 1 # Remove line if not needed

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
skip-character-set-client-handshake

[mysql]
default-character-set = utf8mb4</pre>

Restart the MySQL server process to apply these settings (for example with MariaDB on Linux: '''systemctl restart mariadb''').

If you have any difficulty applying these settings, see [[MySQL_full_unicode_support]] for further information.

If for some reason you cannot change to the settings described here you can continue to install Moodle but you must select '''utf8''' and '''utf8_unicode_ci''' for the default character set and collation respectively.

== Creating Moodle database ==

These are the steps to create an empty Moodle database. Substitute your own database name, user name and password as appropriate.

The instructions assume that the web server and MySQL server are on the same machine. In this case the 'dbhost' is 'localhost'. If they are on different machines substitute the name of the web server for 'localhost' in the following instructions and the 'dbhost' setting will be the name of the database server.
Databases have a "Character set" and a "Collation". For Moodle, we recommend the Character Set be set to '''utf8mb4''' and the Collation '''utf8mb4_unicode_ci'''. You may get the option to set these values when you create the database. If you are not given a choice, the default options are probably good. An install on an old server may have the wrong settings.

=== Command line ===

* To create a database using the 'mysql' command line client, first log into MySQL
<pre>
$ mysql -u root -p
Enter password:
</pre>
(Enter the password you previously set - or been given - for the MySQL 'root' user). After some pre-amble this should take you to the ''mysql>'' prompt.
* Create a new database (called 'moodle' - substitute your own name if required).
If you have successfully configured the recommended full UTF-8 support as described above run:
<pre>
mysql> CREATE DATABASE moodle DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
</pre>
If you do not have the recommended full UTF-8 support run:
<pre>mysql> CREATE DATABASE moodle DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;</pre>
* Add a user/password with the minimum needed permissions:
<pre>
mysql> CREATE USER moodleuser@localhost IDENTIFIED BY 'yourpassword';
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,DROP,INDEX,ALTER ON moodle.* TO moodleuser@localhost;
</pre>
...which creates a user called 'moodleuser' with a password 'yourpassword'. Make sure you invent a strong password and resist the temptation to 'GRANT ALL'.
* Exit from mysql:
<pre>
mysql> quit
</pre>

=== phpMyAdmin ===

[http://www.phpmyadmin.net/ phpMyAdmin] is a web based administration tool for MySQL. If this is available you can use it to create a new database. If you have successfully configured the recommended full UTF-8 support as described above select collation '''utf8mb4_unicode_ci'''. If you do not have the recommended full UTF-8 support select collation '''utf8_unicode_ci'''.

==Which database belongs to which Moodle==
If you have installed several Moodle installations on the same server, there will be several databases in your MySQL server. The names might be quite poor reflections of the content like _mdl1 _mdl2 _mdl3 . So how do I see which database goes with which Moodle installation? You can go in with phpMyAdmin and in the various databases check for the table "mdl_course". There you will easily see the name of that Moodle Installation. In table mdl_config you can see the Moodle version. The main URL for the site is not in the database except where there are absolute links.

== See also ==

* [[MariaDB]]
* [[MySQL full unicode support]]
* [http://www.mysql.com/ The MySQL homepage]
* [http://en.wikipedia.org/wiki/MySQL Wikipedia article about ''MySQL'']
* [http://forums.mysql.com/read.php?24,92131,92131 List of articles on MySQL performance tuning]

[[Category:SQL databases]]

[[ja:MySQL]]
[[de:MySQL]]
[[es:MySQL]]

File:feedbackteacher402.png

2023-07-01T13:16:39Z

Leonstr: Screenshot of teacher view of feedback activity

== Summary ==
Screenshot of teacher view of feedback activity

File:feedbackstudent402.png

2023-07-01T13:16:05Z

Leonstr: Screenshot of student view of feedback activity

== Summary ==
Screenshot of student view of feedback activity

Feedback activity

2023-07-01T13:15:42Z

Leonstr: /* How does it work? */ No preview for students since Moodle 4.1.2 (MDL-70586); update text and screenshots to reflect current appearance

{{Activities}}
__NOTOC__
==What is the Feedback activity?==
The Feedback activity allows you to create and conduct surveys to collect feedback. Unlike the [[Survey module|Survey]] tool it allows you to write your own questions, rather than choose from a list of pre-written questions and unlike the [[Quiz module|Quiz]] tool, you can create non-graded questions. The Feedback activity is ideal for course or teacher evaluations.

{{MediaPlayer | url = https://youtu.be/FvtkNJsrwBU | desc = Overview of the Feedback activity}}

==How is it set up?==
#In a course, with the editing turned on, choose 'Feedback' from the activity chooser.
#Give it a name and if required, a description
# Expand the other sections to define the settings you want, in particular Question and Submission settings and what to display After submission.
#Click Save and display and from the Edit questions tab, Add question drop down, add the questions you want.
==How does it work?==

===Student view===
Students click on the feedback icon in the course to access the activity and then must click the button ''Answer the questions''.

[[File:feedbackstudent402.png|alt=Screenshot of student view of feedback with title and answer the questions button]]

===Teacher view===
Teachers see the ''Settings'' tab as well as an ''Analysis'' tab and ''Responses'' tab. Results may be exported to a spreadsheet program.

From the ''Analysis'' tab they see a report of the aggregate of responses, including a graphical display of answers to multiple choice questions.

From the ''Responses'' tab they see individual responses in detail.

[[File:feedbackteacher402.png|alt=Screenshot of teacher view of feedback with tabs Feedback, Settings, Templates, Analysis and Responses, and buttons to edit and preview questions]]

==More information==
* [[Feedback settings]]
* [[Building Feedback]]
* [[Using Feedback]]
* [[Feedback FAQ]]
*[[Feedback block]]

{{Note|If you don't see the Feedback activity, ask the admin to check it has been enabled.}}

[[Category:Feedback]]

[[fr:Feedback]]
[[es:Actividad de retroalimentación]]
[[eu:Feedback]]
[[de:Feedback]]

Talk:Course settings

2023-06-27T08:34:02Z

Leonstr: #Show_gradebook_to_students suggested update

==Locked page==

[[Course settings]] has been locked because previously many people were getting confused and adding their own course full name, short name etc. to the page.

''Please use this page for suggesting additional content or other changes...''

==Course end date==

Please add

Course end date

Course end date also is used for calculating retention period for deleting data via Privacy API.

: Thanks Ralf, I have added the text as suggested. --[[User:Helen Foster|Helen Foster]] ([[User talk:Helen Foster|talk]]) 08:22, 28 August 2018 (UTC)

==Avoid using non-ASCII characters in course short name==
Maybe we should have a sentence advising to use only standard ASCII letters and numbers in the short name field, in order to avoid errors described in https://moodle.org/mod/forum/discuss.php?d=362971#p1537035 and MDL-36652 . [[User:German Valero|German Valero]] ([[User talk:German Valero|talk]])

==Suggested minor update==
For [[Course_settings#Show_gradebook_to_students]] change to:

Here you can decide whether to allow students to see the link to grades in the <ins>course menu</ins>. If your course doesn't use graded activities, it makes sense to disable this. If grades are used and this link is disabled<del>,</del> students can still see their grade in the actual activity itself, <ins>for example: in an assignment.</ins>
--[[User:Leon Stringer|Leon Stringer]] ([[User talk:Leon Stringer|talk]]) 08:33, 27 June 2023 (UTC)

Backup and restore FAQ

2023-06-12T14:27:40Z

Leonstr: This had been deleted in 2015 (MDL-51972) but crept back in, I don't think it was ever true (for Moodle 2.0 onwards)

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.
* Glossary data
* Badges - if they have not been awarded to at least one user and users are not included in the course backup.

==How do I fix backups that lack the student log and participation data?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include logs." By default, this is off.

If you enable this, then the logs from the user activities can be saved as the option "Include course logs" will now appear on the backup menu of items to include in the backup. These logs provide the data that the various reports such as Course participation, Logs, and Activity report, use to produce their reports.

==How do I fix backups that lack the student grade history?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include histories." By default, this is off.

If you enable this, then the logs from the user grade history and its changes made by teachers manually or by certain activities can be saved when performing a Backup. The option "Include grade history" will now appear on the backup menu of items to include in the backup.

==What do the backup file names mean?==

The default backup file name is composed of the following parts:

*backup-moodle2- :: This tells you that it is backup file of version 2 backup, which have been used since Moodle 2.0, and so it not a Moodle 1 backup file
*course-##- :: This tells you it is a course backup and the ## is the internal id number of the course, as seen in the course url
*shortname- :: Then follows the shortname of the course as set in the course settings
*date-time- :: This is the date and time in ISO format when the backup was made
* nu-nf :: optional suffixes: If the backup does not contain enrolled users, the -nu will be added; if the backup does not include files, the -nf will be added
*.mbz :: The file extension stands for "Moodle backup zip" and you can rename to .zip or .gzip (depending on your server OS) to expand it

Example: backup-moodle2-course-27-HISTORY101-20210124-0916-nu-nf.mbz

Deciphered: This is a backup file from Moodle 2 or above of course with id 27 with shortname HISTORY-101 made on Jan 24, 2021 at 09:16 AM with no enrolled users and no files included in it.

==How can I backup or restore a very large course?==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]
For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.

For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [https://confluence.atlassian.com/jira/files/12079/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

[[Image:autobackup_skip_settings.png|thumb|AutoBackup '''skip''' settings]]Moodle's ''Course backups'' routines are instructed to automatically skip courses based on three settings in ''Administration > Site administration > Courses > Backups > Automated backup setup.'' The Moodle administrator(s) use those settings to specify whether to ''Skip hidden courses'' (set by default to 'Yes'), ''Skip courses not modified since'' (set by default to '30 days'), and ''Skip courses not modified since previous backup'' (set by default to 'No'). A course which meets any of the enabled criteria will be skipped during the next run of ''Course backups''.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

This message is displayed when:

# The target site has a user xxxx (xxxx being the username) - often the admin user
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person, for example: if these users have different email addresses.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc.) from being associated with the target site user xxxx.

Here are the possible methods to make the xxxx users match and resolve the conflict:

<ol style="list-style-type:lower-alpha">
<li>Modify the backup archive's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site. Note that the '''''backup-<...>''.mbz''' is a [https://en.wikipedia.org/wiki/Tar_(computing) tarball] and can be extracted by creating a temporary folder and running '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. When editing is complete recompress the file with '''tar -czf ''/PATH/TO/backup-<...>''.mbz *'''.</li>
<li>Modify the target site and set the user ''email'' or ''firstaccess'' fields to match the ones in '''users.xml'''.</li>
<li>For admin user conflicts only: enable the setting 'Allow admin conflict resolution' in ''Site administration > Courses > Backups > General import defaults''. This will result in the username in the backup file being renamed to 'admin_xyz'.</li>
</ol>

==Restored users lose their passwords - How can they reset them?==

When a course is restored with enroled users included, any new users not already in the system will have new accounts created for them. Backups with enroled users do not include the user passwords. Instead, a password of "restored" is placed in the database for such users. When the user attempts to log into the new site, Moodle will recognise they were restored from a course backup and give the user the following message:

<pre>Restored Account.
This account was imported from another server and the password has been lost. To set a new password by email, please click "Continue"</pre>

When the user clicks the "Continue" button, they will then be sent a change password email to the email address associated with the restored account, just as if they had used the normal "Forgotten password" process. This will allow them to set a new password.

If you are the administrator and wish to avoid users getting such emails, remember that you can use the [[Upload users|Upload users tool]] to bulk set new passwords.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==Restoring a course results in broken HTML tags. What can I do?==
This has been known to be caused by older versions of libxml2 and PHP - try updating them to the latest versions.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an .mbz file) you downloaded (from the course's restore page), you can do so in much the same way as is suggested above.

The backup file can be opened with the command '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. Create a temporary folder to extract the backup's files into.

Next step would be to open the '''files.xml''' file in a text editor, and:

# Search for the name of each file you want to get.
# Take note of the value of the corresponding contenthash tag.
# In the '''files''' folder you extracted, locate the file whose name is the same as the value of the contenthash and which will be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a '''backup_courses-120730.mbz''' file of which the '''files.xml''' file and the '''files''' folder have been extracted. There is a PDF file named '''Leadership.pdf''' that is required for another purpose.

Open the '''files.xml''' file and:

1. Search for the string '''Leadership.pdf''', which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
⋮
<filename>Leadership.pdf</filename>
⋮
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the '''fb''' subfolder inside the '''files''' folder, and there is a file named '''fb6cf43a9b...'''. Rename that file as '''Leadership.pdf''' and move it to the desired location. Repeat this for all the files required, using the corresponding contenthash value each time.

==MySQL dmlwriteexception error when restoring a course==

If you obtain a dmlwriteexception error when restoring a course, it is recommended that InnoDB tables are converted to the Barracuda file format. See the section 'Converting InnoDB tables to Barracuda' in [[Administration via command line]] for details of why this is recommended plus information on a tool for converting tables.

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=128 Backup and restore forum] on moodle.org.

== See also ==

* [[Site backup]]
* [[Moodle migration]]

Moodle forum discussions:
*[https://moodle.org/mod/forum/discuss.php?d=345466 Backing up and restoring course eliminates gradebook categories and items]

[[Category:FAQ]]

[[es:Respaldo y restauración FAQ]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]
[[de:Sicherung und Wiederherstellung FAQ]]

Backup and restore FAQ

2023-06-12T08:08:50Z

Leonstr: /* Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict" */ Specific example added

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==Why is my automated course backup much smaller in size than my manual course backup?==

This is an intentional design decision. Because of the way files are stored in Moodle 2.x, there is no need to include the files in the backup if you are planning to restore them to the same Moodle site. Leaving them out saves huge amounts of disk space and makes the backup procedure much faster.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.
* Glossary data
* Badges - if they have not been awarded to at least one user and users are not included in the course backup.

==How do I fix backups that lack the student log and participation data?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include logs." By default, this is off.

If you enable this, then the logs from the user activities can be saved as the option "Include course logs" will now appear on the backup menu of items to include in the backup. These logs provide the data that the various reports such as Course participation, Logs, and Activity report, use to produce their reports.

==How do I fix backups that lack the student grade history?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include histories." By default, this is off.

If you enable this, then the logs from the user grade history and its changes made by teachers manually or by certain activities can be saved when performing a Backup. The option "Include grade history" will now appear on the backup menu of items to include in the backup.

==What do the backup file names mean?==

The default backup file name is composed of the following parts:

*backup-moodle2- :: This tells you that it is backup file of version 2 backup, which have been used since Moodle 2.0, and so it not a Moodle 1 backup file
*course-##- :: This tells you it is a course backup and the ## is the internal id number of the course, as seen in the course url
*shortname- :: Then follows the shortname of the course as set in the course settings
*date-time- :: This is the date and time in ISO format when the backup was made
* nu-nf :: optional suffixes: If the backup does not contain enrolled users, the -nu will be added; if the backup does not include files, the -nf will be added
*.mbz :: The file extension stands for "Moodle backup zip" and you can rename to .zip or .gzip (depending on your server OS) to expand it

Example: backup-moodle2-course-27-HISTORY101-20210124-0916-nu-nf.mbz

Deciphered: This is a backup file from Moodle 2 or above of course with id 27 with shortname HISTORY-101 made on Jan 24, 2021 at 09:16 AM with no enrolled users and no files included in it.

==How can I backup or restore a very large course?==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]
For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.

For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [https://confluence.atlassian.com/jira/files/12079/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

[[Image:autobackup_skip_settings.png|thumb|AutoBackup '''skip''' settings]]Moodle's ''Course backups'' routines are instructed to automatically skip courses based on three settings in ''Administration > Site administration > Courses > Backups > Automated backup setup.'' The Moodle administrator(s) use those settings to specify whether to ''Skip hidden courses'' (set by default to 'Yes'), ''Skip courses not modified since'' (set by default to '30 days'), and ''Skip courses not modified since previous backup'' (set by default to 'No'). A course which meets any of the enabled criteria will be skipped during the next run of ''Course backups''.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

This message is displayed when:

# The target site has a user xxxx (xxxx being the username) - often the admin user
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person, for example: if these users have different email addresses.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc.) from being associated with the target site user xxxx.

Here are the possible methods to make the xxxx users match and resolve the conflict:

<ol style="list-style-type:lower-alpha">
<li>Modify the backup archive's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site. Note that the '''''backup-<...>''.mbz''' is a [https://en.wikipedia.org/wiki/Tar_(computing) tarball] and can be extracted by creating a temporary folder and running '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. When editing is complete recompress the file with '''tar -czf ''/PATH/TO/backup-<...>''.mbz *'''.</li>
<li>Modify the target site and set the user ''email'' or ''firstaccess'' fields to match the ones in '''users.xml'''.</li>
<li>For admin user conflicts only: enable the setting 'Allow admin conflict resolution' in ''Site administration > Courses > Backups > General import defaults''. This will result in the username in the backup file being renamed to 'admin_xyz'.</li>
</ol>

==Restored users lose their passwords - How can they reset them?==

When a course is restored with enroled users included, any new users not already in the system will have new accounts created for them. Backups with enroled users do not include the user passwords. Instead, a password of "restored" is placed in the database for such users. When the user attempts to log into the new site, Moodle will recognise they were restored from a course backup and give the user the following message:

<pre>Restored Account.
This account was imported from another server and the password has been lost. To set a new password by email, please click "Continue"</pre>

When the user clicks the "Continue" button, they will then be sent a change password email to the email address associated with the restored account, just as if they had used the normal "Forgotten password" process. This will allow them to set a new password.

If you are the administrator and wish to avoid users getting such emails, remember that you can use the [[Upload users|Upload users tool]] to bulk set new passwords.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==Restoring a course results in broken HTML tags. What can I do?==
This has been known to be caused by older versions of libxml2 and PHP - try updating them to the latest versions.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an .mbz file) you downloaded (from the course's restore page), you can do so in much the same way as is suggested above.

The backup file can be opened with the command '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. Create a temporary folder to extract the backup's files into.

Next step would be to open the '''files.xml''' file in a text editor, and:

# Search for the name of each file you want to get.
# Take note of the value of the corresponding contenthash tag.
# In the '''files''' folder you extracted, locate the file whose name is the same as the value of the contenthash and which will be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a '''backup_courses-120730.mbz''' file of which the '''files.xml''' file and the '''files''' folder have been extracted. There is a PDF file named '''Leadership.pdf''' that is required for another purpose.

Open the '''files.xml''' file and:

1. Search for the string '''Leadership.pdf''', which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
⋮
<filename>Leadership.pdf</filename>
⋮
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the '''fb''' subfolder inside the '''files''' folder, and there is a file named '''fb6cf43a9b...'''. Rename that file as '''Leadership.pdf''' and move it to the desired location. Repeat this for all the files required, using the corresponding contenthash value each time.

==MySQL dmlwriteexception error when restoring a course==

If you obtain a dmlwriteexception error when restoring a course, it is recommended that InnoDB tables are converted to the Barracuda file format. See the section 'Converting InnoDB tables to Barracuda' in [[Administration via command line]] for details of why this is recommended plus information on a tool for converting tables.

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=128 Backup and restore forum] on moodle.org.

== See also ==

* [[Site backup]]
* [[Moodle migration]]

Moodle forum discussions:
*[https://moodle.org/mod/forum/discuss.php?d=345466 Backing up and restoring course eliminates gradebook categories and items]

[[Category:FAQ]]

[[es:Respaldo y restauración FAQ]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]
[[de:Sicherung und Wiederherstellung FAQ]]

Backup and restore FAQ

2023-06-10T15:19:48Z

Leonstr: /* How can I extract original files from a Moodle backup file? */ MBZ files are tarballs not zips since MDL-49298/Moodle 2.9 (should fix MDLSITE-5140)

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==Why is my automated course backup much smaller in size than my manual course backup?==

This is an intentional design decision. Because of the way files are stored in Moodle 2.x, there is no need to include the files in the backup if you are planning to restore them to the same Moodle site. Leaving them out saves huge amounts of disk space and makes the backup procedure much faster.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.
* Glossary data
* Badges - if they have not been awarded to at least one user and users are not included in the course backup.

==How do I fix backups that lack the student log and participation data?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include logs." By default, this is off.

If you enable this, then the logs from the user activities can be saved as the option "Include course logs" will now appear on the backup menu of items to include in the backup. These logs provide the data that the various reports such as Course participation, Logs, and Activity report, use to produce their reports.

==How do I fix backups that lack the student grade history?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include histories." By default, this is off.

If you enable this, then the logs from the user grade history and its changes made by teachers manually or by certain activities can be saved when performing a Backup. The option "Include grade history" will now appear on the backup menu of items to include in the backup.

==What do the backup file names mean?==

The default backup file name is composed of the following parts:

*backup-moodle2- :: This tells you that it is backup file of version 2 backup, which have been used since Moodle 2.0, and so it not a Moodle 1 backup file
*course-##- :: This tells you it is a course backup and the ## is the internal id number of the course, as seen in the course url
*shortname- :: Then follows the shortname of the course as set in the course settings
*date-time- :: This is the date and time in ISO format when the backup was made
* nu-nf :: optional suffixes: If the backup does not contain enrolled users, the -nu will be added; if the backup does not include files, the -nf will be added
*.mbz :: The file extension stands for "Moodle backup zip" and you can rename to .zip or .gzip (depending on your server OS) to expand it

Example: backup-moodle2-course-27-HISTORY101-20210124-0916-nu-nf.mbz

Deciphered: This is a backup file from Moodle 2 or above of course with id 27 with shortname HISTORY-101 made on Jan 24, 2021 at 09:16 AM with no enrolled users and no files included in it.

==How can I backup or restore a very large course?==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]
For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.

For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [https://confluence.atlassian.com/jira/files/12079/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

[[Image:autobackup_skip_settings.png|thumb|AutoBackup '''skip''' settings]]Moodle's ''Course backups'' routines are instructed to automatically skip courses based on three settings in ''Administration > Site administration > Courses > Backups > Automated backup setup.'' The Moodle administrator(s) use those settings to specify whether to ''Skip hidden courses'' (set by default to 'Yes'), ''Skip courses not modified since'' (set by default to '30 days'), and ''Skip courses not modified since previous backup'' (set by default to 'No'). A course which meets any of the enabled criteria will be skipped during the next run of ''Course backups''.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

This message is displayed when:

# The target site has a user xxxx (xxxx being the username) - often the admin user
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc.) from being associated with the target site user xxxx.

Here are the possible methods to make the xxxx users match (and resolve the conflict):

<ol style="list-style-type:lower-alpha">
<li>Modify the backup archive's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site. Note that the '''''backup-<...>''.mbz''' is a [https://en.wikipedia.org/wiki/Tar_(computing) tarball] and can be extracted by creating a temporary folder and running '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. When editing is complete recompress the file with '''tar -czf ''/PATH/TO/backup-<...>''.mbz *'''.</li>
<li>Modify the target site and set the user ''email'' or ''firstaccess'' fields to match the ones in backup archive '''users.xml''' file.</li>
<li>For admin user conflicts only: enable the setting 'Allow admin conflict resolution' in ''Site administration > Courses > Backups > General import defaults''. This will result in the username in the backup file being renamed to 'admin_xyz'.</li>
</ol>

==Restored users lose their passwords - How can they reset them?==

When a course is restored with enroled users included, any new users not already in the system will have new accounts created for them. Backups with enroled users do not include the user passwords. Instead, a password of "restored" is placed in the database for such users. When the user attempts to log into the new site, Moodle will recognise they were restored from a course backup and give the user the following message:

<pre>Restored Account.
This account was imported from another server and the password has been lost. To set a new password by email, please click "Continue"</pre>

When the user clicks the "Continue" button, they will then be sent a change password email to the email address associated with the restored account, just as if they had used the normal "Forgotten password" process. This will allow them to set a new password.

If you are the administrator and wish to avoid users getting such emails, remember that you can use the [[Upload users|Upload users tool]] to bulk set new passwords.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==Restoring a course results in broken HTML tags. What can I do?==
This has been known to be caused by older versions of libxml2 and PHP - try updating them to the latest versions.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an .mbz file) you downloaded (from the course's restore page), you can do so in much the same way as is suggested above.

The backup file can be opened with the command '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. Create a temporary folder to extract the backup's files into.

Next step would be to open the '''files.xml''' file in a text editor, and:

# Search for the name of each file you want to get.
# Take note of the value of the corresponding contenthash tag.
# In the '''files''' folder you extracted, locate the file whose name is the same as the value of the contenthash and which will be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a '''backup_courses-120730.mbz''' file of which the '''files.xml''' file and the '''files''' folder have been extracted. There is a PDF file named '''Leadership.pdf''' that is required for another purpose.

Open the '''files.xml''' file and:

1. Search for the string '''Leadership.pdf''', which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
⋮
<filename>Leadership.pdf</filename>
⋮
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the '''fb''' subfolder inside the '''files''' folder, and there is a file named '''fb6cf43a9b...'''. Rename that file as '''Leadership.pdf''' and move it to the desired location. Repeat this for all the files required, using the corresponding contenthash value each time.

==MySQL dmlwriteexception error when restoring a course==

If you obtain a dmlwriteexception error when restoring a course, it is recommended that InnoDB tables are converted to the Barracuda file format. See the section 'Converting InnoDB tables to Barracuda' in [[Administration via command line]] for details of why this is recommended plus information on a tool for converting tables.

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=128 Backup and restore forum] on moodle.org.

== See also ==

* [[Site backup]]
* [[Moodle migration]]

Moodle forum discussions:
*[https://moodle.org/mod/forum/discuss.php?d=345466 Backing up and restoring course eliminates gradebook categories and items]

[[Category:FAQ]]

[[es:Respaldo y restauración FAQ]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]
[[de:Sicherung und Wiederherstellung FAQ]]

Backup and restore FAQ

2023-06-10T14:50:46Z

Leonstr: These errors were removed in Moodle 2.0

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==Why is my automated course backup much smaller in size than my manual course backup?==

This is an intentional design decision. Because of the way files are stored in Moodle 2.x, there is no need to include the files in the backup if you are planning to restore them to the same Moodle site. Leaving them out saves huge amounts of disk space and makes the backup procedure much faster.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.
* Glossary data
* Badges - if they have not been awarded to at least one user and users are not included in the course backup.

==How do I fix backups that lack the student log and participation data?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include logs." By default, this is off.

If you enable this, then the logs from the user activities can be saved as the option "Include course logs" will now appear on the backup menu of items to include in the backup. These logs provide the data that the various reports such as Course participation, Logs, and Activity report, use to produce their reports.

==How do I fix backups that lack the student grade history?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include histories." By default, this is off.

If you enable this, then the logs from the user grade history and its changes made by teachers manually or by certain activities can be saved when performing a Backup. The option "Include grade history" will now appear on the backup menu of items to include in the backup.

==What do the backup file names mean?==

The default backup file name is composed of the following parts:

*backup-moodle2- :: This tells you that it is backup file of version 2 backup, which have been used since Moodle 2.0, and so it not a Moodle 1 backup file
*course-##- :: This tells you it is a course backup and the ## is the internal id number of the course, as seen in the course url
*shortname- :: Then follows the shortname of the course as set in the course settings
*date-time- :: This is the date and time in ISO format when the backup was made
* nu-nf :: optional suffixes: If the backup does not contain enrolled users, the -nu will be added; if the backup does not include files, the -nf will be added
*.mbz :: The file extension stands for "Moodle backup zip" and you can rename to .zip or .gzip (depending on your server OS) to expand it

Example: backup-moodle2-course-27-HISTORY101-20210124-0916-nu-nf.mbz

Deciphered: This is a backup file from Moodle 2 or above of course with id 27 with shortname HISTORY-101 made on Jan 24, 2021 at 09:16 AM with no enrolled users and no files included in it.

==How can I backup or restore a very large course?==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]
For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.

For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [https://confluence.atlassian.com/jira/files/12079/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

[[Image:autobackup_skip_settings.png|thumb|AutoBackup '''skip''' settings]]Moodle's ''Course backups'' routines are instructed to automatically skip courses based on three settings in ''Administration > Site administration > Courses > Backups > Automated backup setup.'' The Moodle administrator(s) use those settings to specify whether to ''Skip hidden courses'' (set by default to 'Yes'), ''Skip courses not modified since'' (set by default to '30 days'), and ''Skip courses not modified since previous backup'' (set by default to 'No'). A course which meets any of the enabled criteria will be skipped during the next run of ''Course backups''.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

This message is displayed when:

# The target site has a user xxxx (xxxx being the username) - often the admin user
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc.) from being associated with the target site user xxxx.

Here are the possible methods to make the xxxx users match (and resolve the conflict):

<ol style="list-style-type:lower-alpha">
<li>Modify the backup archive's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site. Note that the '''''backup-<...>''.mbz''' is a [https://en.wikipedia.org/wiki/Tar_(computing) tarball] and can be extracted by creating a temporary folder and running '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. When editing is complete recompress the file with '''tar -czf ''/PATH/TO/backup-<...>''.mbz *'''.</li>
<li>Modify the target site and set the user ''email'' or ''firstaccess'' fields to match the ones in backup archive '''users.xml''' file.</li>
<li>For admin user conflicts only: enable the setting 'Allow admin conflict resolution' in ''Site administration > Courses > Backups > General import defaults''. This will result in the username in the backup file being renamed to 'admin_xyz'.</li>
</ol>

==Restored users lose their passwords - How can they reset them?==

When a course is restored with enroled users included, any new users not already in the system will have new accounts created for them. Backups with enroled users do not include the user passwords. Instead, a password of "restored" is placed in the database for such users. When the user attempts to log into the new site, Moodle will recognise they were restored from a course backup and give the user the following message:

<pre>Restored Account.
This account was imported from another server and the password has been lost. To set a new password by email, please click "Continue"</pre>

When the user clicks the "Continue" button, they will then be sent a change password email to the email address associated with the restored account, just as if they had used the normal "Forgotten password" process. This will allow them to set a new password.

If you are the administrator and wish to avoid users getting such emails, remember that you can use the [[Upload users|Upload users tool]] to bulk set new passwords.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==Restoring a course results in broken HTML tags. What can I do?==
This has been known to be caused by older versions of libxml2 and PHP - try updating them to the latest versions.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an ".mbz" file) you downloaded (using the backup and restore feature), you can do so in much the same way as is suggested above.

The backup file can actually be opened with any zip/unzip program you can download. Once you open the file, you need to extract:

The files.xml file.
The files directory (folder).

Next step would be to open the "files.xml" file in a text editor, and:

Search for the name of each file you want to get.
Take note of the value of the corresponding contenthash tag.
In the "files" folder you extracted, locate the file whose name is the same as the value of the contenthash and which will always be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a "backup_courses-120730.mbz" file of which the "files.xml" file and the "files" folder have been extracted. There is a PDF file named "Leadership.pdf" that is required for another purpose.

Open the files.xml file and:

1. Search for the string "Leadership.pdf", which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
:
<filename>Leadership.pdf</filename>
:
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the "fb" folder inside the "files" directory (which was previously extracted), and there is a file named "fb6cf43a9b...". Rename that file as "Leadership.pdf", and then move it to another location. Repeat this for all the files required, using the correct contenthash value of course.

==MySQL dmlwriteexception error when restoring a course==

If you obtain a dmlwriteexception error when restoring a course, it is recommended that InnoDB tables are converted to the Barracuda file format. See the section 'Converting InnoDB tables to Barracuda' in [[Administration via command line]] for details of why this is recommended plus information on a tool for converting tables.

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=128 Backup and restore forum] on moodle.org.

== See also ==

* [[Site backup]]
* [[Moodle migration]]

Moodle forum discussions:
*[https://moodle.org/mod/forum/discuss.php?d=345466 Backing up and restoring course eliminates gradebook categories and items]

[[Category:FAQ]]

[[es:Respaldo y restauración FAQ]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]
[[de:Sicherung und Wiederherstellung FAQ]]

Backup and restore FAQ

2023-06-10T14:44:48Z

Leonstr: /* Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict" */ MBZ files are tarballs not zip files

{{Backup}}
==How do I backup a course?==

See [[Course backup]] and [[Automated backup setup]].

==How do I restore a course?==

See [[Course restore]].

==How do I backup my site?==

See [[Site backup]].

==What are the pros and cons of course versus site backups?==

[[Site backup|Site backups]] are recommended in order to have all data saved with the best confidence and the shortest recovery time.

For a site administrator, [[Automated course backup|automated course backups]] are more expensive in terms of time, CPU usage and storage. The recovery time to have a site running again takes longer than a site backup. However, teachers and site administrators might find a course backups as a way to create a "fresh" copy of a course that can be re-used (in older versions of Moodle, in newer versions see [[Import course data]]) or as a method to distribute a course(s) to other Moodle sites.

==Why is my automated course backup much smaller in size than my manual course backup?==

This is an intentional design decision. Because of the way files are stored in Moodle 2.x, there is no need to include the files in the backup if you are planning to restore them to the same Moodle site. Leaving them out saves huge amounts of disk space and makes the backup procedure much faster.

==What data is not contained in course backups?==

By selecting all the options when setting up the backup you can include almost all the data in the course. However you should be aware of the fact that some things are not backed up:
* Quiz questions are only backed up if at least one question from their category has been added to a quiz.
* Scales are only backed up if they are used by at least one activity.
* Users' passwords are not backed up when the "Include enrolled users" option is selected.
* Glossary data
* Badges - if they have not been awarded to at least one user and users are not included in the course backup.

==How do I fix backups that lack the student log and participation data?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include logs." By default, this is off.

If you enable this, then the logs from the user activities can be saved as the option "Include course logs" will now appear on the backup menu of items to include in the backup. These logs provide the data that the various reports such as Course participation, Logs, and Activity report, use to produce their reports.

==How do I fix backups that lack the student grade history?==

In ''Site administration > Courses > Backups > General backup defaults'', there is a setting for "Include histories." By default, this is off.

If you enable this, then the logs from the user grade history and its changes made by teachers manually or by certain activities can be saved when performing a Backup. The option "Include grade history" will now appear on the backup menu of items to include in the backup.

==What do the backup file names mean?==

The default backup file name is composed of the following parts:

*backup-moodle2- :: This tells you that it is backup file of version 2 backup, which have been used since Moodle 2.0, and so it not a Moodle 1 backup file
*course-##- :: This tells you it is a course backup and the ## is the internal id number of the course, as seen in the course url
*shortname- :: Then follows the shortname of the course as set in the course settings
*date-time- :: This is the date and time in ISO format when the backup was made
* nu-nf :: optional suffixes: If the backup does not contain enrolled users, the -nu will be added; if the backup does not include files, the -nf will be added
*.mbz :: The file extension stands for "Moodle backup zip" and you can rename to .zip or .gzip (depending on your server OS) to expand it

Example: backup-moodle2-course-27-HISTORY101-20210124-0916-nu-nf.mbz

Deciphered: This is a backup file from Moodle 2 or above of course with id 27 with shortname HISTORY-101 made on Jan 24, 2021 at 09:16 AM with no enrolled users and no files included in it.

==How can I backup or restore a very large course?==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==The process ends with: "Error: An error occurred deleting old backup data". What should I do?==

This part of the backup (or restore) procedure tries to delete old info, used in previous executions, performing the following tasks:

# Delete old records from "backup_ids" table: Check the table exists, repair it and try again.
# Delete old records from "backup_files" table: Check the table exists, repair it and try again.
# Delete old files from "moodledata/temp/backup": Delete the dir completely and try again.

[[Image:BackupProblem.gif|thumb|Backup error message]]
For points 1 & 2, there are various ways of repairing tables, including using MySQL Admin.

For point 3 see below:

The error message states that the "directory not empty" and gives the path to that directory. If you go there with an FTP program you can see what is there and clean up. It could be just some empty subfolders that were leftover. Deleting these has been able to help. One can also delete the dir "moodledata/temp/backup" completely. That can take a bit longer but may solve several problems at once.

==The process ends with: "XML error: not well-formed (invalid token) at line YYYY". What can I do?==

This problem can appear at any point in the restore process. It's caused when the XML parser detects something incorrect in the backup file that prevent correct operation. Usually, it's caused by some "illegal" characters added in the original course due to some copy/paste of text containing them (control characters, or invalid sequences...).

The best method to handle this issue is:

* Unzip the problematic backup file under one empty folder.

* Open the moodle.xml with Firefox. It will show you where (exact char) the problem is happening.

* Edit the moodle.xml file with some UTF8-compatible editor and delete such characters. Save changes.

* Test the moodle.xml file again with Firefox until no error was displayed.

* Zip everything again (all the folder contents but not the folder itself!).

* Restore the course. It should work now.

* Restore still not working? See the next question.

Also, if possible, it's highly recommended to solve those problems in the original course too from Moodle itself. Once "repaired" there, problems will be out if you create new backup files in the future.

==The process ends with: "moodle xml not found at root level of zip file". What can I do?==
If you are restoring from a zip file backup make sure the moodle.xml file is at the root level. To ensure this:
#Unzip the backup file of the course (example: mycourse.zip)
#Once the file is unzipped, open the folder (example: mycourse).
#Select the folders within the mycourse folder AND the moodle.xml file and create a zip of those item (example: mycourse_new.zip)
#Upload the new zip file (example: mycourse_new.zip) and restore from that.

If the backup file is guaranteed to be correct, check paths to external files (zip, unzip). Incorrect settings also lead to this error message (see the Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=140355 moodle.xml not found in root...] and MDL-14812).

==The process ends with: "An error occurred while copying the zip file..."==

This problem is most likely caused by a permissions issue in the destination directory. Backup files are copied to "XXX/backupdata" under your dataroot directory (where XXX is the id of the course being backed up).

The problem could also be caused by a disk being full, though this is far less likely.

To obtain precise information about what's happening, you can enable debug messages in ''Administration > Server > [[Debugging]]'' (select the maximum level - DEVELOPER) and/or check the web server error logs.

==I Still get an XML error. How can I clean the borked XML file?==

In some cases XML backup files may contain characters causing the restore process to abort, even after the steps described in the previous question. In such cases you may want to try the following:

* Download the [https://confluence.atlassian.com/jira/files/12079/atlassian-xml-cleaner-0.1.jar Atlassian XML Cleaner Utility] from the [http://confluence.atlassian.com/display/JIRA/Removing+invalid+characters+from+XML+backups JIRA Atlassian site].

* Unzip the problematic Moodle backup file under one empty folder. Moodle will create the course file folders as long as the unclean moodle.xml file. Please unzip using the Moodle unzip feature.

* Rename the unclean moodle.xml file to moodle-unclean.xml.

* If you don't have access to your Moodle server's command prompt, using the Moodle zip feature, zip the moodle-unclean.xml file only, download the zip file locally and unzip it. It is very important to download the xml file in zipped format to avoid unwanted character encoding when transferring from an operating system to another.

* Move the downloaded Atlassian XML Cleaner Utility in the same folder where is your moodle-unclean.xml file.

* Issue the following command from the command prompt:

java -jar atlassian-xml-cleaner-0.1.jar moodle-unclean.xml > moodle.xml

* If you launched the utility on your local computer, zip the just created (and hopefully cleaned) moodle.xml file and upload it in the same place from where you downloaded the moodle-unclean.xml file. Once uploaded, unzip it using the Moodle unzip feature.

* Zip everything again (all the folder contents but the folder itself!).

* Restore the course. It should work now.

==What does "Some of your courses weren't saved!!" mean?==

There are three possible causes of this problem:
# Error - this happens when the backup procedure has found an error and so hasn't finished the backup of a particular course. These are "controlled" errors and the scheduled backup continues with the next course.
# Unfinished - this happens when the backup procedure dies without knowing why. When the cron is next executed it detects that the last execution went wrong, and continues skipping the problematic course. A possible solution would be to raise the PHP/Apache limit in your installation (memory, time of execution...). By taking a look to your log tables you should be able to see if the "crash" is happening at exact time intervals (usually a problem with the max_execution_time php's variable), or if there is some exact point were all the courses are breaking.
# Skipped - this happens when a course is unavailable to students and has not been changed in the last month (31 days). This isn't an error situation - it's a feature, especially useful for sites with many unavailable old courses, saving process time.

==Why are some courses being skipped?==

[[Image:autobackup_skip_settings.png|thumb|AutoBackup '''skip''' settings]]Moodle's ''Course backups'' routines are instructed to automatically skip courses based on three settings in ''Administration > Site administration > Courses > Backups > Automated backup setup.'' The Moodle administrator(s) use those settings to specify whether to ''Skip hidden courses'' (set by default to 'Yes'), ''Skip courses not modified since'' (set by default to '30 days'), and ''Skip courses not modified since previous backup'' (set by default to 'No'). A course which meets any of the enabled criteria will be skipped during the next run of ''Course backups''.

==Why does restore stop, rather than completing?==

Attempting to restore a course to an older version of Moodle than the one the course was backed up on can result in the restore process failing to complete. To ensure a successful restore, make sure that the version of Moodle you are restoring the course to is the same, or newer, than the one the course was backed up on.

If it stop unexpectedly with no errors shown try again with [[Debugging]] switched on. Any errors you now see can help experts in the support forums diagnose your problem. You can also check the discussion links in the See also section below for further advice.

==Restore stops with the message "Trying to restore user xxxx from backup file will cause conflict"==

This message is displayed when:

# The target site has a user xxxx (xxxx being the username) - often the admin user
# The backup archive being restored also contains a user xxxx (same username)
# After various comparisons, Moodle has determined that the target site user xxxx and the backup user xxxx aren't the same person.

If 1, 2 and 3 are all true, the restore process stops in order to prevent the backup user xxxx's activities (forum posts, quiz attempts, assignment uploads, etc.) from being associated with the target site user xxxx.

Here are the possible methods to make the xxxx users match (and resolve the conflict):

<ol style="list-style-type:lower-alpha">
<li>Modify the backup archive's '''users.xml''' file and make the ''email'' or ''firstaccess'' fields match the ones in target site. Note that the '''''backup-<...>''.mbz''' is a [https://en.wikipedia.org/wiki/Tar_(computing) tarball] and can be extracted by creating a temporary folder and running '''tar -xzf ''/PATH/TO/backup-<...>''.mbz'''. When editing is complete recompress the file with '''tar -czf ''/PATH/TO/backup-<...>''.mbz *'''.</li>
<li>Modify the target site and set the user ''email'' or ''firstaccess'' fields to match the ones in backup archive '''users.xml''' file.</li>
<li>For admin user conflicts only: enable the setting 'Allow admin conflict resolution' in ''Site administration > Courses > Backups > General import defaults''. This will result in the username in the backup file being renamed to 'admin_xyz'.</li>
</ol>

==Restored users lose their passwords - How can they reset them?==

When a course is restored with enroled users included, any new users not already in the system will have new accounts created for them. Backups with enroled users do not include the user passwords. Instead, a password of "restored" is placed in the database for such users. When the user attempts to log into the new site, Moodle will recognise they were restored from a course backup and give the user the following message:

<pre>Restored Account.
This account was imported from another server and the password has been lost. To set a new password by email, please click "Continue"</pre>

When the user clicks the "Continue" button, they will then be sent a change password email to the email address associated with the restored account, just as if they had used the normal "Forgotten password" process. This will allow them to set a new password.

If you are the administrator and wish to avoid users getting such emails, remember that you can use the [[Upload users|Upload users tool]] to bulk set new passwords.

==Why are certain course links broken in a restored course?==

Inter-activity links must be absolute (full) URLs e.g. <code><nowiki>http://site.com/mod/resource/view.php?id=xxx</nowiki></code> in order to be processed properly during backup and restore.

Any relative URLs e.g. <code>/mod/resource/view.php?id=xxx</code>, <code>../resource/view.php?id=xxx</code> or <code>view.php?id=xxx</code> will result in broken links when the course is restored.

==Restoring a course results in broken HTML tags. What can I do?==
This has been known to be caused by older versions of libxml2 and PHP - try updating them to the latest versions.

==How can I extract original files from a Moodle backup file?==
If you really want to get original files from the backup file (an ".mbz" file) you downloaded (using the backup and restore feature), you can do so in much the same way as is suggested above.

The backup file can actually be opened with any zip/unzip program you can download. Once you open the file, you need to extract:

The files.xml file.
The files directory (folder).

Next step would be to open the "files.xml" file in a text editor, and:

Search for the name of each file you want to get.
Take note of the value of the corresponding contenthash tag.
In the "files" folder you extracted, locate the file whose name is the same as the value of the contenthash and which will always be located in a folder whose name corresponds to the two first characters of the file name.

For example, let's assume there is a "backup_courses-120730.mbz" file of which the "files.xml" file and the "files" folder have been extracted. There is a PDF file named "Leadership.pdf" that is required for another purpose.

Open the files.xml file and:

1. Search for the string "Leadership.pdf", which in this case is found under the following <file id...> group tag:

<file id="12345">
<contenthash>fb6cf43a9b2d432403c70a2cb4c340dbb6225631</contenthash>
:
<filename>Leadership.pdf</filename>
:
<license>allrightsreserved</license>
<sortorder>1</sortorder>
</file>

2. Take note of the corresponding contenthash value: fb6cf43a9b2d432403c70a2cb4c340dbb6225631.

3. As the first two characters of the contenthash are "fb", open the "fb" folder inside the "files" directory (which was previously extracted), and there is a file named "fb6cf43a9b...". Rename that file as "Leadership.pdf", and then move it to another location. Repeat this for all the files required, using the correct contenthash value of course.

==MySQL dmlwriteexception error when restoring a course==

If you obtain a dmlwriteexception error when restoring a course, it is recommended that InnoDB tables are converted to the Barracuda file format. See the section 'Converting InnoDB tables to Barracuda' in [[Administration via command line]] for details of why this is recommended plus information on a tool for converting tables.

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=128 Backup and restore forum] on moodle.org.

== See also ==

* [[Site backup]]
* [[Moodle migration]]

Moodle forum discussions:
*[https://moodle.org/mod/forum/discuss.php?d=345466 Backing up and restoring course eliminates gradebook categories and items]

[[Category:FAQ]]

[[es:Respaldo y restauración FAQ]]
[[pl:Backup FAQ]]
[[fr:FAQ de sauvegarde]]
[[ja:バックアップFAQ]]
[[pt:FAQ sobre cópias de segurança]]
[[de:Sicherung und Wiederherstellung FAQ]]

Using Assignment

2023-05-06T13:00:54Z

Leonstr: /* File submission */ Fix button text

{{Assignment}}
This page explores the different types of assignment, how students submit assignments and how teachers can grade them.

==What are the options for submitting work in Moodle?==
The standard ways students can submit assignments are:
* File submissions (students submit a file for assessment)
* Online text (students can type their responses directly in Moodle)
* Audio or video (via the recording button in the [[Atto editor]])

Notes:
# It is also possible to use the assignment for grading an "offline assignment", ie, one where work is done outside of Moodle. This is done by simply unchecking the above three options.
# If you're not sure which assignment type best suits your needs, look at the section below [[#Which type of assignment submission suits you best?]]

==Which type of assignment submission suits you best?==

===You want students to type shorter or longer responses directly online===

Set ''Online text'' to Yes. This works well for younger children who will only manage a sentence or two and works just as well for higher education students who write more.
*Advantage - quick for the student to get started; no need to use a word-processing program and upload the file. The text is saved on a regular basis so it will be preserved if the student loses the page for some reason.
*Disadvantage: if the word count is expected to be large, setting ''Online text'' to No and ''File submission'' to Yes might be a better option.

===You want students to submit work you can download in a specified program===

Set ''File submission'' to Yes, set the number of files you will allow using the ''Maximum number of uploaded files'' setting and the file sizes by using the '' Maximum submission size'' setting.
*Advantage - better than students emailing work as the whole class's work is collated in one space on your course. Markers can provide comments directly on the student work.
*Advantage - with "Attempts reopened" enabled, teachers can see the progression through various drafts of a student's work.
*Disadvantage - assignments must downloaded to be viewed (but they can be [[Assignment_FAQ| downloaded in bulk]]) and the teacher needs the appropriate program to open them.

===You want students to submit files at different times for a project===

Set ''File submission'' to Yes, and use ''Maximum number of uploaded files'' to set the maximum number of separate files they can upload
*Advantage - all project files are in one assignment area for grading so they get a single grade.
*Disadvantage - all project files are in one assignment area for grading - so they can only have a single grade!
===You want students to write a response to a video/sound file/image===

Set up an assignment allowing ''online text'' submission and get students to use the Moodle media icon to add video/sound/image files.

===You want students to answer a series of questions on a video/sound file/image===

Investigate the [[Quiz]] module. Assignments are really just for a single question.

===You want to grade work students have done offline===
Uncheck the submission types when setting up the assignment. Students won't be required to do anything but you can use the assignment to grade them for work done outside of Moodle.

===You want to view, comment on and send back students' assignments===

Set up an assignment allowing ''file submissions''.
*Advantage: useful for teachers who like using the "comment" options in word-processing programs for example. If you have Ghostscript enabled on your server and the students upload PDF files, you can annotate them inline. See the section [[Using Assignment#Annotating PDF files| Annotating PDF files]] below.
*Disadvantage: if students upload other file types, you have to download them, comment and then re-upload them.

===You want students to send you a comment or note along with their uploaded work===

If [[Comments#Enabling_comments|comments are enabled site-wide]], students will be able to add submission comments; if comments are disabled site-wide, students will not be given the option to add submission comments.

===You want to allow students to redraft and decide when to submit the work===

In the settings set ''Require students click submit button'' to Yes. Students can then control when their draft work is submitted to the teacher.

===You want students to keep an ongoing journal or do an iterative assignment===

In the settings set ''Require students click submit button'' to No. Students can continue to make changes to their assignment and at no point do they 'submit'. If the work will be graded at some point it is recommended that either ''Prevent late submissions'' is set to Yes to ensure that no changes can be made after the due date, or [[Using_Assignment#Submission_status| all submissions are locked]] when grading commences to ensure that the work is not altered during grading.
*Advantage: the work remains in one place and is constantly improved, graded (if needed) and improved again.
*Disadvantage: there is no record/history of previous attempts (such as with the [[Wiki]]). The online text assignment does not replicate the display of a journal or blog where each new entry is additional to the previous ones.

===You want students to submit work in groups===

In the settings, set "Students submit in groups" to Yes. If you just do this, then once one student has submitted, the assignment will be flagged as submitted even if the others haven't contributed. If you want to ensure everyone has an input, set "Require students click submit button" to Yes and then change "Require all group members to submit" to Yes. The assignment will only be classed as submitted when each member has contributed, and once one student has submitted, the remaining members's names will be displayed for the group to see who still needs to add their input.

===You want to grade students' work anonymously===
In the settings, choose 'Anonymous submissions'. When students submit assignments, their names will be replaced by randomly-generated participant numbers so you will not know who is who. Note that this is not '''totally''' anonymous because you can reveal their identities in the assignment settings and you can work out identities from the logs - so this might not be suitable if your establishment has very precise privacy requirements.

===You want to read and grade student assignments offline===
In the settings, choose "Offline grading worksheet". When students have submitted, click "View/grade all submissions" and you can download their assignments from the link "Download all submissions" and download the grading sheet from the link "Download grading worksheet". You can then edit grades and re-upload the grading worksheet. You can also upload multiple feedback files in a zip from this drop down menu. See [[Assignment settings]] for an explanation of how to use the "upload multiple feedback files as zip" feature.

===You want to hide students' grades until a time of your choosing.===
Use 'marking workflow' as explained in [[Assignment settings]].

===You want to moderate other colleagues' marking or allocate certain teachers to certain students===
Use 'marking allocation' as explained in [[Assignment settings]].

==How do students submit their assignments?==
The first page students will see when they click on the assignment activity link from the course page will display the assignment name, description and the submission status. The first time a student views the assignment it will look like this:
{|
|[[Image:statuses.jpg|thumb|Student view of assignment]]
|}
The submission status section includes:
*'''Submission status'''
*'''Grading status'''
*Due date
*Time remaining
*Last modified
*Submission details

As they progress through the assignment the Submission status and Grading status will update and the Last modified date will appear.
{|
|[[Image:submission statuses graded.jpg|thumb|Example of submitted and graded assignment]]
|}

If the student uploaded a file which the teacher has annotated, this will be made available in the feedback section. The student can search through the document and filter specific comments.
{|
|[[File:26pdfstudentgraded.png|thumb|Student view of graded pdf file]]
|[[File:26searchcomments.png|thumb|Searching and filtering comments in annotated pdf]]
|}
Submission statuses include:

*Nothing submitted for this assignment
*Draft (not submitted)
*Submitted for grading

Grading statuses include:

*Not graded
*Graded

===File submission===
To submit a file submission, students complete the following steps:

# Click the ‘Add submission’ button to bring up the file upload page.
# Upload the relevant file into the submission. They are able to ‘drag and drop’ the file into the submission box.
# Click ‘Save Changes’.

There should now be a Last modified date and the file(s) uploaded will also be displayed. Depending on how the assignment is setup the status will either read ‘Submitted for grading’ - in which case no further action is need, or ‘Draft (not submitted)’.

# If changes are required, click ‘Edit submission’.
# Once ready to submit, click ‘Submit assignment’.

Note that once the assignment is 'submitted’ no further changes are allowed.

{|
|[[File:file upload.jpg|thumb|Student view when adding a submission]]
|[[File:file uploaded.jpg|thumb|Student view once file is uploaded]]
|[[File:submit button.jpg|thumb|Student view when submitting assignment]]
|}
Note: Depending on how the assignment is setup students may see both a file submission page and an online text editor.

If file submissions and online text are enabled, and a word limit is set for the online text, it is possible for a student to end up with a submission status of 'No attempt' together with saved file submissions. This occurs when a student submits files, enters online text, clicks 'Save changes' then obtains a message informing them that the text exceeds the word limit. If they then click Cancel, the submission status is shown as 'No attempt' together with saved file submissions.

===Access controlled links===
If the administrator has enabled this feature for either the [[Google Drive repository]] or the [[OneDrive repository]] then students can upload a file as an 'access controlled link' from either of these repositories. The file is then copied to the site account and the student is no longer able to edit it.The student retains the original file in their own Google Drive or OneDrive. The teacher is given permission to edit the file for grading purposes, and the student is sent a copy of the edited file.
[[File:accesscontrolledlink.png|center|thumb|Student submits an access controlled link]]

===Online text===
To submit online text, students complete the following steps:

# Click the ‘Add submission’ button to bring up the online text editor page.
# Type the relevant text into the [[Text_editor|text editor]], or paste from a previously written file.
# Click ‘Save Changes’.

There should now be a Last modified date and the first 100 characters entered will also be displayed. Depending on how the assignment is setup the status will either read ‘Submitted for grading’ - in which case no further action is need, or ‘Draft (not submitted)’.

# If changes are required, click on ‘Edit my submission’.
# Once ready to submit, click ‘Submit assignment’.

Note that once the assignment is 'submitted’ no further changes are allowed.

{|
|[[File:online text entered.jpg|thumb|Online text entered]]
|[[File:submit button online text.jpg|thumb|Submitting assignment]]
|}

===Submission comments===
If enabled by the administrator, there may be a section where students can leave submission comments.
{|
|[[Image:student comments.jpg|thumb|Student comments]]
|}

==How do teachers grade assignments?==
When students have submitted their assignments, they can be accessed by clicking on the assignment activity. This will bring up the Grading Summary page.

The Grading Summary page displays a summary of the assignment, including; number of participants, number of drafts, number of submitted assignments, due date and time remaining.

Clicking 'Grade' will take you to the first student in the list so you can start grading individually. If you wish to grade several assignments, clicking Save and Show next will take you to the next submission.

[[File:saveandshownext.png|center|thumb|400px]]

Clicking 'View all submissions' will take you to the grading table where you see all students.

The Grading Table contains columns of information about the student, the status of their submission, a link to grade their submission, a link to each submission and feedback comments and files (if enabled).

===Filtering submissions===

A dropdown menu accessed from the 'Options' section allows you to filter submissions so you can for example quickly see which students have not submitted yet.

You can also filter submissions which have had extensions granted.

[[File:filterassignments.png]]

===Allocating submissions to markers===
If you need to divide submissions between more than one person, you can apply groups to the assignment and let markers know which group(s) to mark. Note that because group membership is not itself anonymised, this may make anonymised submissions that bit less anonymous, though as long as the groups aren't very small this should be acceptable.

An alternative is to use [[Assignment_settings#Use_marking_allocation|marking allocation]] - this allows anyone with a teacher role to allocate one marker to each submission. This works particularly well if marking is allocated by subject specialism.

===Submission status===
If you will be assigning grades to student work, you may want to take note of the submission status before you begin the marking process. If you have required students click the Submit button, you may find that some submissions are still marked as Draft (not submitted), meaning the student has either uploaded a file(s) or entered some text, but has not clicked ‘Submit assignment’.

If it's after the due date and you are about to commencing marking that you use ‘Prevent submission changes’ to stop students from making changes to their assignment. You can do this one by one by using the icon in the Edit column.

Or you can select two or more students by putting a tick in the select column and going to 'Lock submissions’ from the ''With selected'' menu under the grading table.

Likewise you can also revert a student's submission to draft if they have uploaded the incorrect file. Instead of selecting ‘Prevent submission changes’ select ‘Revert the submission to draft’, or place ticks against selected students and choose 'Revert the submission to draft status' from the ''With selected'' menu under the grading table.

{|
|[[File:submission statuses.jpg|thumb|Submission statuses]]
|[[File:prevent submission changes dropdown.jpg|thumb|Prevent submission changes dropdown]]
|[[File:lock submissions.jpg|thumb|Lock submissions]]
|[[File:revert to draft.jpg|thumb|Revert to draft]]
|[[File:revert submission to draft status.jpg|thumb|Revert to draft status]]
|}

If the submission setting 'Attempts reopened' is set to 'Automatically until pass' and a submission is graded below the grade to pass, then then submission is automatically unlocked when the grade is saved. Similarly, if the submission setting 'Attempts reopened' is set to Manually, and a teacher selects 'Allow another attempt, then the submission is automatically unlocked.

===Overriding assignment deadlines===

A teacher can override a deadline for an individual or group from the Assignment navigation > More link [[Boost theme]] or Assignment administration other themes.)

When adding overrides for a group, it is possible to have one group override trump another. This is achieved by moving the override up/down on the group overrides page:

[[File:AssignGroupOverrides.png|||center]]

In this situation, a student in both groups (e.g. Frodo Baggins) will have the override from "The Council of Elrond" applied. By pressing the arrow icons on the right, the override for "The Fellowship" can be moved to the top of the list, and will have higher precedence.

Note also that if there exists a user override for a student, it will always take precedence over any group overrides.

===Granting extensions===
If an assignment has a deadline, a teacher can grant individual or group assignment extensions by selecting the Edit link next to a particular student or group.

#To grant an extension, open the assignment
#Click on "View all submissions"
#Locate the student who is to be allowed to submit after the "Cut-off date"To
#Click on the adjacent "Edit" drop down menu and select "Grant extension"
##[[File:grantextension0.png|thumb|center|600px]]
#Set the extension date and time. The student's or group's name is also shown on this screen.
##[[File:grantextension.png||thumb|center|600px]]
#Click on "Save changes".

===Quick grading===

'''Quick grading''' allows you to enter numeric grades directly into the grading table, bypassing the more detailed grading interface. Please note:
*if you want to give feedback, you need to use the more detailed Grade interface.
*Quick grading is incompatible with advanced grading e.g. Rubrics, and is not recommended when there are multiple markers.
*'''Submission comments''' are a two-way private conversation between a student and staff and are visible to students immediately i.e. markers use the grading interface to give feedback, not the submission comments.

To access the Quick Grading interface, from the Grading Summary page click 'View all submissions'; the Grading Table displays. Scroll to bottom of the page to configure Options, and check the box for 'Quick grading'. While you're down there, you can also set the number of assignments to display per page, filter the assignments e.g. to see who has not submitted, unmarked assignments, etc.

When you are ready to Quick Grade:

#You can enter grades directly into the grading table.
#Scroll to the bottom of the grading table and click 'Save all quick grading changes'
#A confirmation displays.

===Grading individual submissions===
If you have enabled File Feedback in the [[Assignment settings]] and wish to upload either the marked student assignment, a completed text based feedback document or audio feedback, click on the green tick in the Grade column (or use the icon in the Edit column and select Grade).

This brings you to the Student Grading Page where you can give grades, feedback comments and feedback files (if enabled in the [[Assignment settings]]). You can use drag and drop to upload feedback files.

{|
|[[File:green tick.jpg|thumb|Green tick]]
|[[File:grade.jpg|thumb|Grading]]
|[[File:feedbackfiles.png|thumb|Feedback files]]
|}

====Annotating submissions====

If the student has uploaded a PDF, docx or odt file, or if you set 'Comment inline' for an online text submission, then their submission will be displayed on the grading screen, allowing you to annotate it (requires [http://www.ghostscript.com/ Ghostscript] for PDF and [[Universal Office Converter (unoconv)|unoconv]] for docx and odt files), using a variety of tools, stamps (if uploaded by the admin) and comments which may be saved to a comments bank. When the annotations are complete, clicking to save the changes will result in it being displayed to the student as part of their feedback.

'Rotate' icons let you change the orientation of an uploaded document if the student submitted it in landscape mode for example.

[[File:AnnotatingAssignment.png|thumb|500px|center|Annotating a student's submission]]

Comments may be added and then saved in a quick list for future use ''(1)'' Click the paper/magnifying glass icon to the right of the page selector to filter comments you have already added to the work''(2)'':
*In the '''Search comments''' pop-up window, enter the term you would like to search for in the '''Filter comments...''' box.
*Clicking on the comment will take you to the part of the paper where that comment has been added.

{|
|[[File:NFaddcomment.png|thumb|400px|1.Saving and re-using comments]]
|[[File:NFcommentsearch.png|thumb|400px|2. Accessing comments]]
|}

Note: To ensure that comments display to students as the marker intends, do instruct students to download the annotated PDF rather than just previewing it. Preview sometimes displays comments in a way which obscures the original text.

The review panel and / or the grading panel may be collapsed by clicking the icons at the bottom right of the screen.

[[File:CollapseReviewPanel.png|center]]

===Controlling when to notify students of graded work===

====Notifying as you mark====

If you need to notify individual students, one by one, as you mark, the '''Notify students''' checkbox is available when grading individual submissions. Choose Yes to notify the student immediately or No to grade without notifying the student. Assuming you are not hiding grades in the ways outlined below, then Moodle will send a notification.

Note: How students receive Moodle notifications depends on your local default settings, and any changes students have made to those.

[[File:notifystudents.png|center|thumb|500px]]

====Keeping grades hidden until a release date====

Assessors often decide to hide grades and feedback until marking is complete and finalised, and then release them all at once. There are two alternatives for this.

*[[Grade_hiding|Hide the item in the Grader Report]]. This is convenient if there are few markers and you have decided a provision date for releasing the marks and feedback.
*Or enable [[Assignment_settings#Use_marking_.28grading.29_workflow|Use marking workflow]] in the Assignment's settings. This way is best where there are many markers, and/or you don't have a provisional date to release marks and feedback.

====Examples of Marking workflow====

One marker, Marker, wants to release all grades at the same time
* Marker enables "Use marking workflow"
* Marker marks each submission and transitions the grading to "Marking completed" as each submission is graded.
* Marker then uses the batch operations to transition all grades to "Released" at the same time.

Multiple markers,
* Marker enables "Use marking workflow"
* Marker marks each submission and transitions the grading to "Marking completed" as each submission is graded.
* Marker then uses the batch operations to transition all grades to "Released" at the same time.

===Offline marking - downloading and uploading multiple grades and feedback files===

If you don't have an internet connection or prefer to grade outside Moodle, you can do so (including with anonymous submissions).
These easy stages explained below:
#Download the submissions
#Download the spreadsheet (grading worksheet) to record grades.
#Grade and annotate (if applicable) the submitted work.
#Upload the completed grading worksheet.
#Upload the annotated submissions (if applicable).

Note:You cannot upload marks and feedback to Moodle if you have enabled Rubrics or Marking Guides.

====Before you start, enable the multiple file upload settings====
Go to the settings of that assignment.
For Feedback types, ensure that the Moodle Assignment settings, Feedback comments, Feedback files, and Offline grading worksheet are ticked.

====Downloading student submissions====

You can download a zip file containing all of the assignment submissions by selecting ‘Download all submissions’ from the 'Grading actions' menu at the top of the grading table, or in the settings menu.

File submissions will be downloaded in the format uploaded by the student. Online text submissions will be downloaded as html files. Each file in the zip will be named with the student first and last name followed by a unique identifier (not the user ID number).

If each submission is more than a single file, then submissions may be downloaded in folders by ticking the option 'Download submissions in folders' (below the grading table). Each submission is put in a separate folder, with the folder structure kept for any subfolders, and files are not renamed. Each folder will be named with the student first and last name followed by a unique identifier (not the user ID number).

You can also download selected assignment submissions (rather than all of them) by selecting the ones you want and then choosing 'With selected....Download selected submissions'.

====Download the Grading Worksheet to record grades ====
#Next, to download the spreadsheet in which you'll enter the grades and brief comments, return to the Moodle Assignment page and from its Grading action drop-down menu choose Download grading worksheet and save that file (keep its csv file format).

Note: Helpfully that downloaded worksheet will contain any existing grades and summary comments which have already been given for that assignment i.e. if marking has already started. However, to see pre-existing comments fully you may need to set your spreadsheet to 'wrap text' within cells.

====Grade and annotate (if applicable) the submitted work====
After downloading the submissions and the grading worksheet:
#Open a downloaded assignment file to assess it.
#Open the csv file in a spreadsheet editor e.g. Excel.
#For that student's record (if anonymous, a number corresponding to the submission file name will display), enter grades in the Grade column and summary comments in the Feedback comments column for each student.
#Leave the other data untouched unless you know exactly what you're doing.
#Repeat as needed.
#Save the csv file.

Note: Take care to enter data in the correct column of the spreadsheet.

If you are annotating the submissions to return to students as feedback:
#Open a downloaded submission.
#Carry out your annotations.
#Save it in its original place i.e. the folder corresponding to that student.
#Repeat as needed.
If you have separate feedback files to upload to students:
#Save these within that student's folder.
#You can give students multiple feedback files in this way e.g. annotations on their work along with a separate pro forma.

Note: Don't change the name or location of the folder - Moodle needs this information to allocate the files correctly.

Compress (zip) all the feedback files:

#Locate the folder containing the feedback files in Moodle, select them all (Ctrl+A within the folder), then zip them:
##Windows: Right click one of the selected files and Send to > Compressed (zipped) folder.
##Mac: Right Click (or Ctrl+click) one of the selected files and click Compress.
#They are now ready for upload (see below).

====Upload the completed grading worksheet====
When you are ready to upload grades and summary feedback:
#Click on the assignment name on the Moodle course homepage to access the summary page and click '''View/grade all submissions'''.
#From the Grading action drop-down menu choose '''Upload grading worksheet'''.
#Click '''Choose a file...''' and upload the grading worksheet to Moodle, or drag the csv file to the arrow and wait for the file name to appear in the box.
#There is a checkbox to '''overwrite records that have been modified more recently in Moodle than in the spreadsheet''' - only check this if you want to spreadsheet to overwrite all Moodle records, including ones made more recently than the spreadsheet.
#Click '''Upload grading worksheet'''; a Confirmation box displays the students grades and feedback that will be imported - check this carefully.
#If you are ready to proceed, click '''Confirm'''; a summary of updates displays.
#Click '''Continue'''.

====Upload feedback files (if applicable)====
#Click on the assignment name on the Moodle course homepage to access the summary page and click '''View/grade all submissions'''.
#From the Grading action drop-down menu choose '''Upload multiple feedback files in a zip'''.
#Click '''Choose a file...''' and upload the zipped assignments file to Moodle, or drag the compressed/zipped file to the arrow and wait for the file name to appear in the box.
#Click '''Import feedback file(s)'''.
#The Confirmation box will list all the feedback files and student names that will be imported.
#Click '''Confirm'''; the next screen summarises the changes.
#Click '''Continue'''.
#From the page containing the Grading Table, you can check your feedback files by enabling Quick grading (see Options at the bottom of that page) and scrolling horizontally, if needed.

For an assignment with no file submissions, see the discussion [https://moodle.org/mod/forum/discuss.php?d=336438 upload feedback files without student file submissions] for details of what to do.

===Give the same feedback file to multiple students===
If you have high level feedback you want to give to an entire cohort, it is generally a good idea to give this feedback in the context of the assignment, rather than e.g. separately via a Forum. Moodle allows you to select some or all students and attach a single, common feedback file to their assignment feedback. This common feedback will appear to each student along with any other individual feedback files you have prepared for each.
#Prepare the single file of feedback.
#Click on the link to the Assignment; its summary page displays.
#Click '''View all submissions'''; the assignment's Grading Table displays.
#Use the checkboxes to select all or some students to receive the feedback (you may first prefer to configure the Grading Table to show as many students as possible on a single page).
#Underneath the Grading Table click the '''With selected...''' menu, choose '''Send feedback files''', then click '''Go'''; a page displays a list of selected students above a file upload area.
#Upload the file of feedback you prepapred, or drag it to the arrow and wait for the file name to appear in the box.
#Click '''Send feedback files'''; the Grading Table displays again.
#Check your file is in place by scrolling horizontally to the '''Feedback files''' column.

==Keeping records (archiving, exporting, backing up)==
When students unenrol from a Moodle area, their records become invisible through the Gradebook interface. In order to have the information to hand, departments or course teaching teams may need systems in place to keep their own records for the data retention period required in their particular context. There are two separate procedures for exporting student submissions and marks.

To export marks (with or without feedback):
#Go to your course administration block and click Grades.
#From the Grader Report Settings block, select Export; a menu displays.
#From the menu, if you need easy viewing and running calculations you probably want to select one of the spreadsheet formats; a page of export settings loads
#Use the Visible Groups pulldown menu to limit the export to specific groups, as required
#In Options, you indicate whether feedback comments are included
#In Grade Items To Be Included lists you can, if required, omit particular Activities from the report
#When you've finished with the settings, click on Submit; a preview of your export displays
#Click on Download to export to the format you chose, and save the file.

To download the original student submissions:
#In your course area, click the link to the Assignment whose submissions you want to download.
#Click on the link to View/Grade all submissions; the Grading Table will load.
#Click the link to 'Download all submissions' and save the file.
==Tips and Tricks==
* Want to use an Assignment activity again in another Moodle site? Use the [[Activity_backup| backup and restore]] options.
*Want to use an Assignment activity in another course you teach? Use the [[Import_course_data| Import function]] in the course administration block.
*Moodle will sometimes appear not to be uploading a resubmitted assignment - you seem to be downloading the original assignment. This is a cache issue, in short, go to ''"Tools > Clear Recent History"'' in Firefox or ''"Tools > Delete Browsing History > Delete Temporary Files"'' in Windows Explorer. The newer file will then appear.

==See also==

===Examples from [https://school.moodledemo.net School demo site]===

* [https://school.moodledemo.net/mod/assign/view.php?id=573&rownum=3&action=grade Teacher view of a PDF assignment which can be annotated inline.]Log in with username 'teacher' and password 'moodle'
* [https://school.moodledemo.net/mod/assign/view.php?id=573&action=grading Teacher view of allocated markers and marking workflow status.] Log in with username 'teacher' and password 'moodle'
* [https://school.moodledemo.net/mod/assign/view.php?id=190 Student view of an assignment.] Log in with username 'student' and password 'moodle'. Scroll down to see the rubric and feedback.
* [https://school.moodledemo.net/mod/assign/view.php?id=46&action=editsubmission Student view of a student submission statement] Log in with username 'student' and password 'moodle'
* [https://school.moodledemo.net/mod/assign/view.php?id=715 Student view of group assignment grading screen] Log in with username 'student' and password 'moodle'
* [https://school.moodledemo.net/mod/assign/view.php?id=715&action=grading Teacher view of a group assignment grading screen] Log in with username 'teacher' and password 'moodle'.
* [https://school.moodledemo.net/mod/assign/view.php?id=191&action=grading Teacher view of Anonymous submissions grading screen] Log in with username 'teacher' and password 'moodle'

===Other===
* [http://www.somerandomthoughts.com/blog/2013/07/07/one-approach-for-group-project-grading/ One approach to group project grading] blog post by Gavin Henrick
* [http://moodle.org/mod/forum/discuss.php?d=201307 Advantages of using Assignment upload over emailing a document] forum discussion

[[de:Aufgabe nutzen]]
[[fr:Afficher un devoir]]
[[ja:課題を表示する]]
[[es:Usando Tarea]]

RedHat Linux installation

2023-04-28T16:32:36Z

Leonstr: /* SELinux */ Added details prompted by https://moodle.org/mod/forum/discuss.php?d=446229

{{Update}}

== Server Installation ==
* Web Server
** Moodle 3.7 needs PHP 7.1; RHEL8 comes with PHP 7.2.[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/8.0_release_notes/index#web-servers-databases-dynamic-languages]
* Database
** Moodle 3.7 needs MariaDB 5.5 or MySQL 5.6; RHEL8 comes with MariaDB 10.3 and MySQL 8.0 (They cannot be installed at the same time).[https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/deploying_different_types_of_servers/index#using-mariadb]
* BEWARE OF the 'Server with a GUI' option, it may not work as expected.

Note: Set up the firewall if necessary. You probably only need to enable HTTP/HTTPS (and perhaps FTP and SSH) access to your server machine, unless you know the difference.

== Network Interface ==

During installation, under "System" -> "Network & Host Name", remember to enable the NIC. It's not enabled by default.

== Configure hostname and domain name==

Type system-config-network to open the GUI editor. Click on the DNS tab. In the "DNS Search Path" fill in your domain name for example myuniversity.edu. Now ensure the "Hostname" contains the computer name you will use and click activate to make changes

== System Registration ==
* To receive package updates, create a user account at redhat.com, and then login and register as developer at https://developers.redhat.com/
* Subscribe the system by:
<pre>
subscription-manager register --auto-attach
</pre>
Enter the username and password as requested.
* Update the system and then reboot
<pre>
yum update
reboot
</pre>
See [https://developers.redhat.com/rhel8/install-rhel8-vbox/]

== SELinux ==
By default Red Hat Enterprise Linux comes with SELinux set to 'enforcing'. This may cause user problem accessing web content placed at directory other than the default directory (/var/www/html) or other access problem.

If you are not used to SELinux and setting permissions, it's (maybe less secure but) often easier to lower the SELinux level to 'permissive' or even 'disabled'.

<pre>
# vi /etc/sysconfig/selinux

SELINUX=disabled
</pre>

See the CentOS [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/sect-Security-Enhanced_Linux-Working_with_SELinux-Changing_SELinux_Modes.html]

=== Moodledata ===

To allow writing to the Moodledata directory run the following commands after creating the directory (assuming your Moodledata directory is in '''/var/www/moodle.example.com/moodledata'''):

# semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/moodle.example.com/moodledata"
# restorecon -v "/var/www/moodle.example.com/moodledata"

If the Moodledata directory already exists and is not empty instead run:

# semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/moodle.example.com/moodledata(/.*)?"
# restorecon -R -v "/var/www/moodle.example.com/moodledata"

=== Access to network services ===

If your Moodle site needs access to remote network services then you must allow this access with:

# setsebool -P httpd_can_network_connect 1

This is required if your Moodle database is remote, or if you are using a network service such as LDAP (auth_ldap or enrol_ldap), or some external database (auth_db or enrol_database). This is not required if your Moodle database is a local MySQL/MariaDB database, but is required if your Moodle database is a local PostgreSQL database.

=== Access to execute commands ===

To run commands such as those specified under [[System_paths|System paths]]:

# setsebool -P httpd_execmem on

== Firewall ==
The internal firewall (RHEL since version 7 uses 'firewalld'[https://firewalld.org/]) is on by default. It will block the access to the web server. You may stop it first to test connection:

<pre>
service firewalld stop
</pre>

and then either disable it:

<pre>
chkconfig firewalld off
</pre>

or enable permanent HTTP access to it, you may want to enable HTTPS as well:
<pre>
firewall-cmd --permanent --zone=public --add-service=http
firewall-cmd --permanent --zone=public --add-service=https
</pre>

Restart the firewall and then check the allow status:
<pre>
service firewalld restart
firewall-cmd --zone=public --list-services
</pre>

To disable certain types of ICMP traffic [http://www.freekb.net/Article?id=2639], e.g. timestamp request and reply:
<pre>
firewall-cmd --add-icmp-block=timestamp-request --permanent
firewall-cmd --add-icmp-block=timestamp-reply --permanent
</pre>

Restart the firewall and then check the block status:
<pre>
firewall-cmd --reload
firewall-cmd --query-icmp-block=timestamp-request
firewall-cmd --query-icmp-block=timestamp-reply
</pre>

To use iptables instead of firewalld, see [https://access.redhat.com/solutions/1264743]

== MariaDB / MySQL ==

* Make sure at least 'mariadb' and 'mariadb-server' packages are installed.
** (use "mysql" and "mysql-server" for MySQL)
<pre>
yum install mariadb mariadb-server
</pre>
*Then get the daemon running, it is not running by default. And set it to auto-start. See also [https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/chap-managing_confined_services-mariadb]
** (use "mysqld" for MySQL)
<pre>
service mariadb start; chkconfig mariadb on
</pre>
*Edit /etc/my.cnf (May be different for MySQL) (MariaDB 10.3 doesn't need this as these are already the default settings.)

<pre>vi /etc/my.cnf</pre>

Scroll down to the [mysqld] section and under "Basic Settings", add the following line under the last statement.

<pre>innodb_file_format = Barracuda</pre><br />
<pre>innodb_file_per_table = 1</pre><br />
<pre>innodb_large_prefix</pre>

* If you haven't yet, as root, change the MariaDB/MySQL root password, also secure the installation
** mysql_secure_installation
* Next, set up the MariaDB/MySQL database (see http://moodle.org/doc/?file=install.html#Database for more details)
* Launch MariaDB/MySQL as root
** mysql -u root -p
*** (at the password prompt, enter the password from above)
* At the '>' MariaDB/MySQL prompt, enter the following commands (MariaDB/MySQL commands are ended with a ';')
** CREATE DATABASE mymoodle CHARSET 'utf8mb4';
*** ('mymoodle' is the name of the database you would like to use, it will be entered to the Moodle 'config.php' later)
** GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,DROP,INDEX,ALTER ON mymoodle.* TO moodleuser@localhost IDENTIFIED BY 'moodlepass';
*** (as above, 'mymoodle', 'moodleuser' and 'moodlepass' will be entered to the Moodle 'config.php' later)
** flush privileges;
** quit
* (! Consider MariaDB/MySQL security - not covered here. If you run a firewall, you don't have too much to worry about.)

== Setup Moodle ==
(I will install under /usr/moodle, data in /usr/moodle_data)

=== Download ===
* Download your favourite version of Moodle from moodle.org (.zip archive is easiest)
* as Root create folder under /usr and copy zip
** su
** mkdir /usr/moodle
** mkdir /usr/moodle_data
** cp moodle_111.zip /usr/moodle
* If you prefer you can install the GIT version directly for all the latest features. Instead of downloading and copying the zip file. See [https://docs.moodle.org/400/en/Git_for_Administrators Git_for_Administrators] for details.
** cd /usr
** git clone git://git.moodle.org/moodle.git
* Or if you prefer you can install the CVS version directly for all the latest features. Instead of downloading and copying the zip file.
** cd /usr/moodle
** cvs -d:pserver:anonymous@uk.cvs.moodle.org:/cvsroot/moodle login
** cvs -z3 -d:pserver:anonymous@uk.cvs.moodle.org:/cvsroot/moodle co moodle

=== Unpack and set file permission etc ===

* Still as root we unpack moodle and rename to something appropriate (I have multiple moodle installs, hence this setup). I will call this install mymoodle.
** cd /usr/moodle
** unzip moodle_xxx.zip
** mv moodle mymoodle
*** (optional step - I have more than one install under /usr/moodle)
** mkdir /usr/moodle_data/mymoodle
*** (same name as the moodle install above)
** chown -R apache:apache /usr/moodle
*** (! Giving Apache full rights to your Moodle programs is not secure. Check out the forums for recommendations on how to secure a production environment.)
** chown -R apache:apache /usr/moodle_data

=== Setup config.php ===

* Still as root copy and edit the config file, you should know the host/domain name for your server
** cd /usr/moodle/mymoodle
** cp config-dist.php config.php
** vi config.php (or whatever your favourite editor is!)
* Your config.php settings should be something like...
** dbtype = 'mariadb' (use 'mysqli' for MySQL)
** dbhost = 'localhost'
** dbname = 'mymoodle'
** dbuser = 'moodleuser'
** dbpass = 'moodlepass' (<-- better make this something of your own)
** prefix = 'mdl_'
*** (Use different prefix if there is more than one instance of Moodle on the same server, and you plan to share the database)
** wwwroot = 'http://myhost.mydomain'
*** (If you only want to try moodle out and will not be accessing it from other machines you can use 'http://localhost/mymoodle')
** dataroot = '/usr/moodle_data/mymoodle'
* Save your changes and exit from the editor

== Apache ==
* Install it if it's not installed already.
<pre>
yum install httpd
</pre>
or everything<pre>
yum install httpd*
</pre>
* Start it and make it auto-start after reboot:
<pre>
service httpd start; chkconfig httpd on
</pre>
* Open a web browser and make sure you can connect to the installed web server and default port (80) of the server. If not OK, it may be blocked by the firewall (see above). Correct the problem before continuing.
* Edit the Apache configuration file <pre>/etc/httpd/conf/httpd.conf</pre>
* Right at the end of the file add the following lines:
** <Directory "/usr/moodle/mymoodle"> (the directory used during Moodle installation)
** DirectoryIndex index.php
** AcceptPathInfo on
** AllowOverride None
** Options None
** Order allow,deny
** Allow from all
** </Directory>
** Alias /mymoodle "/usr/moodle/mymoodle"
* Don't insert a space in "allow,deny" (common mistake!)
* You might also want to run through the rest of the config file and make some other (obvious) changes - administrator email and suchlike. Not vital though.
* Run the Services application (same as for Mysql) - tick and start "httpd", then save changes and exit.

=== Setting Document Root ===
Edit <pre>/etc/httpd/conf/httpd.conf</pre>

Change From: DocumentRoot /var/www/html

Change To: DocumentRoot /var/www/html/mymoodle

If you want the web site to be served as "http://www.whatever.com/mymoodle" instead of "http://www.whatever.com", don't change it, and modify the 'wwwroot' parameter of Moodle 'config.php' file accordingly.

== PHP ==
* Install PHP:
<pre>
yum install php php-cli php-common php-fpm php-gd php-intl php-json php-mbstring php-mysqlnd php-opcache php-pdo php-xml php-xmlrpc php-pecl-zip php-soap
</pre>

*Check the installed PHP version:
<pre>
# php -v
</pre>

* Restart the web server so that PHP can start working:
<pre>
service httpd restart
</pre>

*Create a "phpinfo.php" file within the "/var/www/html" directory (or anywhere the Apache "DocumentRoot" points to) with the following content:
<pre>
<?php
phpinfo();
?>
</pre>
And then open web browser and browse to "http://webserver/phpinfo.php" to make sure PHP is working with the web server. Then remove the file for security reason.



== Install Moodle ==
Now everything's ready. Use web browser to open "http://webserver/mymoodle/install.php" to start the installation.

== Set up cron job ==

As root user edit the /etc/crontab file using vi (or another editor) OR you can add a line to the root user's "personal" crontab (don't do both!).
===CLI version===
{{Note| According to Moodle's documentation, users should use the CLI version if possible, as the web version may be removed in future.[https://docs.moodle.org/36/en/Cron#Working_out_the_Moodle_cron_command]}}

* If you wish to place an entry in your root user's crontab use:
** <pre>crontab -e</pre>
** Add the following line:
<pre> */5 * * * * /usr/bin/php /path/to/mymoodle/admin/cli/cron.php</pre>
to run the command every 5 minutes.

===Web version===
{{Note|Use the CLI version if possible.}}
* If you wish to place an entry in your root user's crontab use:
** crontab -e
** Add the following line:
*** */5 * * * * /usr/bin/wget -O /dev/null http://localhost/mymoodle/admin/cron.php
**** (change the URL as appropriate for your site)
---
* If you wish to add an entry in /etc/crontab:
* Open the /etc/crontab file in an editor (vi).
* Add the following line:
** */5 * * * * root /usr/bin/wget -O /dev/null http://localhost/mymoodle/admin/cron.php
*** (change the URL as appropriate for your site)
---
* In either case, don't forget to save the file and exit (in vi that is <Esc>, then ':wq')

== Try your new installation ==

http://myhost.mydomain/admin
or
http://myhost.mydomain/mymoodle/admin

or, if you are running the browser on the same machine

http://localhost/admin
or
http://localhost/mymoodle/admin

== Installing SSL certificate ==

After installing the SSL certificate, change the 'http' to 'https' in the 'wwwroot' parameter of Moodle 'config.php' file.

[[Category:Administrator]]
[[Category:Installation]]
[[pl:Instalacja w RedHat]]

==See also==
*[[Unix or Linux Installation]]
*[[Installing Moodle]]

course/view/onetopic

2023-03-22T10:28:08Z

Leonstr: Add redirect for format_onetopic

#redirect [[Course homepage]]

Grade history

2023-03-06T19:08:23Z

Leonstr: /* Disabling grade history */ Spelling/grammar

{{Managing grades}}
==What is Grade history?==

Accessed from ''Course administration > Grade administration > Grade history,'' the Grade history report allows teachers to select specific students, grade items and/or graders and view the grading history for certain dates.

It is possible to view only revised grades and to download the data in various format such as .csv or an Excel/Libre Office spreadsheet.

[[File:fbgradehistory.png|thumb|600px|center]]

===Grader===

Note: If your course contains quizzes or workshops, then you will see your students listed in the 'Grader' dropdown. This is expected as they are graders in a workshop and self-grade in a quiz.

==Site administration settings==
The administrator can decide how many history entries will be displayed per page in the Grade history report by specifying a number in ''Site adminstration > Grades > Report settings > Grade history.'' The default is 50.
===Disabling grade history===
Grade history may be disabled, or the history only kept for a specified period, by editing the settings in ''Site administration > Server > Cleanup''. Disabling grade history may speed up the server a little and conserve space in the database.

[[es:Historia de la calificación]]
[[de:Bewertungsverlauf]]
[[fr:Historique d'évaluation]]

File resource FAQ

2023-03-06T11:13:42Z

Leonstr: /* I've uploaded a video file, but it's too small. How do I change the default video size? */ Change code to syntaxhighlight; x to ×

{{File}}
==I can't upload files to my course.I get the message that my 'filetype cannot be accepted'==
*Make sure you are not trying to upload to the course summary files area - ''Administration>Course administration>Edit settings.''
*This upload area is only for files describing the course and by default only image files are allowed (so that a screenshot may be displayed next to the summary.)
*If you wish to upload files into your course, make sure you are first on the main course page itself, not in the settings of the course.

==My students cannot open the file I uploaded for them==
Check that the students have the appropriate software to open your file. While Moodle will accept different types of files, it relies on the user to read them with the relevant program. If you uploaded a MS Word 2010 document for instance, make sure your class is able to access Office 2010, or provide them with alternatives such as links to Open Office, a "reader" or a pdf version of your file. If your teaching involves the use of subject-specific proprietary software, you should ensure your students are given the means to open the files at home as well as in your establishment.

See the [https://moodle.org/plugins/search.php?s=Power&p=1&l=20&o=263 existing additional plugins ] for opening PowerPoint and other MS Office files within Moodle.

See the [[Working_with_files#Alternative_to_MS_PowerPoint_and_PDF_files| Presentation]] additional plugin that displays multimedia HTML5 presentations and slide shows in users' web browsers.

==Office docs and PDFs won't open on Android devices==
Try changing the display to "Automatic" instead of "Force download". See this [https://moodle.org/mod/forum/discuss.php?d=271372#p1169372 forum post about documents and Android mobiles].

==Why is it possible to select multiple files in the file settings?==

Because you might be uploading a set of HTML pages with resources. You make the index.HTML page the main one, and can reference the other resources.

==How can I upload a lot of files in one go?==

You can use the [[Folder]] resource to display multiple files. Put all your files into a folder, zip(compress) the folder and upload it to the [[Folder]] resource. Click the icon to the right of its name to unzip it and then save. All the files will then display.

==How can I change the top frame size when displaying a file in a frame?==

#Login as an admin and go to ''Settings > Site administration > Plugins > Activity modules > File''.
#Change the 'Frame height' setting.
#Click the 'Save changes' button.

==If I upload a file in one course, can I use it in another course as well?==
Yes. From the file picker, choose Server files and then navigate to the course where you uploaded the file initially and select it there.

==How can I make ppt files open within Moodle rather than downloading?==

You need to convert the ppt to something else, such as PDF.

==How can I show the size of a file on the course page?==

Students who need to download files appreciate being able to see its size especially if they have a slow Internet connection. Simply tick the 'Show size' checkbox in the file settings.

==If students can link to uploaded files as aliases, how can I stop them changing their assignments?==

Don't worry! Students are not allowed to link to files in their private files when uploading assignments, forum attachments, workshop submissions or quiz essays. See [[Working with files]].

==I've uploaded a video file, but it's too small. How do I change the default video size?==

The default size for Moodle video and flash replay is 400×300 pixels. If you want the default video size to be larger, add the following code to your config.php file. Another method is to add the same code to the bottom of theme/themename/config.php file (where themename is the name of the theme or themes you are using). Note set the number to the size in pixels you want, common sizes being 800×600 or 700×525 or 600×450 or 500×375.

<syntaxhighlight lang="php">... if (!defined('CORE_MEDIA_VIDEO_WIDTH')) {
// Default video width if no width is specified; some players may do something
// more intelligent such as use real video width.
// May be defined in config.php if required.
define('CORE_MEDIA_VIDEO_WIDTH', 800);
}
if (!defined('CORE_MEDIA_VIDEO_HEIGHT')) {
// Default video height. May be defined in config.php if required.
define('CORE_MEDIA_VIDEO_HEIGHT', 600);
}
if (!defined('CORE_MEDIA_AUDIO_WIDTH')) {
// Default audio width if no width is specified.
// May be defined in config.php if required.
define('CORE_MEDIA_AUDIO_WIDTH', 400);
}...</syntaxhighlight>

[[Category:FAQ]]

[[de:Datei FAQ]]
[[es:Recurso Archivo FAQ]]

Roles FAQ

2023-02-22T16:51:24Z

Leonstr: /* Why doesn't "Switch role to.." within a course seem to work properly? */ Space

{{Roles}}
==What is the definition of a...==

;Capability
:A configurable aspect of program behavior. Moodle has 100s of capabilities. Each capability has a computer friendly name like [[Capabilities/mod/forum:rate|mod/forum:rate]] and a human-friendly name like "Rate posts."
;Permission
:Permissions are paired with each capability. There are four possible permission values: ''Allow'', ''Prevent'', ''Prohibit'' and ''Not set''/''Inherit''. (It is called not-set when defining roles and inherit when overriding permissions.)
;Role
:A named set of permissions that are associated with each capability. For example. the "Teacher" and "Student" roles come with the standard Moodle install.
;Context
:A functional area of Moodle. Contexts have a hierarchy. Examples of contexts include a course, activity module, or resource.

==Why isn't my role change taking effect?==

Certain capabilities e.g. [[Capabilities/moodle/user:changeownpassword|moodle/user:changeownpassword]] may only be applied in the system context, so giving such permissions by assigning a role in the course context will have no effect.

==Why do some users I know are in my course not appear in ''Participants''?==

Users assigned roles in a higher context, for example users assigned the role of teacher in the course category are technically not enrolled in the course and so will not appear in the Participants link in the [[Navigation block]] but can be found via ''Course administration > Users > Other users''.

==How can I prevent a user from changing their own password?==

==== Using roles ====

To prevent a user from changing their own password, you must make sure they do not have [[Capabilities/moodle/user:changeownpassword|moodle/user:changeownpassword]] = Allow in the System context. The Authenticated user role (which is assigned to users in the System context) has moodle/user:changeownpassword = Allow by default, so you have two choices:
# Edit Authenticated user, setting moodle/user:changeownpassword = Not set
# Create a new role CannotChangeOwnPassword with moodle/user:changeownpassword = Prevent and all other permissions Not set. Choose "system" for the context type and assign the role to selected users in the System context via ''Administration>Site administration -> Users -> Permissions -> Assign system roles).''

Choice (1) will prevent ''all'' users from changing their passwords (except for the administrator, who can do anything). To selectively allow selected users (say teachers) to change their passwords, you could create a new role CanChangeOwnPassword with moodle/user:changeownpassword = Allow and all other permissions not set and assign the role to selected users in the System context (Site administration -> Users -> Permissions -> Assign system roles).

Choice (2) allows you to be selective, but if you have a lot of users that you want to prevent (say, all students), you will have to make a lot of role assignments in the System context. There is currently no convenient way to do this, so you might consider choice (1).

Note that you MUST deal with this permission in the System context.

==== Alternative solution ====

Go to Site administration > Plugins > Manage authentication plugins. Find the 'forgottenpasswordurl' setting and point it to a static HTML page on your server (or even a Moodle Page resource on the front page). Explain your password policy on that page. This stops users changing passwords. This applies to ALL users, however, so admins will need to fix any lost passwords for the whole site.

==How can I prevent a user from editing their own profile?==

See [[Roles_FAQ#How can I prevent a user from changing their own password? | How can I prevent a user from changing their own password?]] The answer to this question is the same if you substitute ''edit their own profile'' for ''change their own password'' and ''[[Capabilities/moodle/user:editownprofile|moodle/user:editownprofile]]'' for ''moodle/user:changeownpassword.''

== How can I allow a "test" Student user to see courses that are hidden?==

Having a test user to try out courses before you open them to regular students is useful. But if the course is hidden, then the enroled test student will not be able to see it. The solution to this problem, if you do not wish to make the hidden course visible yet, is to create a ''Student tester rol'', a clone of the default Student role and then set the ability to see hidden courses to Allow.

* Create a new role in ''Site administration > Users > Permissions > Define roles > Add a new role'', then for ''Use role or archtype'' choose ''ARCHETYPE: Student'' (or Student if you have customized the default Student role already)
* Give the role a new shortname and fullname as appropriate, e.g. studenttester, Student Tester
* Change the 'View hidden courses' [[Capabilities/moodle/course:viewhiddencourses|course:viewhiddencourses]] capability from Not Set to Allow
* Click the 'Create this role button'

Now enrol your test student in the course using this new role instead of the Student role, and they will be able to see and work in the course as a normal student even when the course is hidden. They will not be able to see other hidden courses in which they are not enroled.

==How do I change the name for "teacher" in the course description?==

Either
* Edit the role of Teacher via ''Site administration > Users > Permissions > Define roles'' and rename it. The new name will apply site-wide.
Or
* Create a duplicate teacher role with an alternative name and assign users the duplicate teacher role as appropriate in the course context. In ''Site administration > Appearance > Course contact'' select the alternative name for teacher that you wish to be displayed in the course description when courses are listed. For example, copy the standard teacher role and call it Instructor and only show that role as the course contact.
Or
* Create a new "dummy" role (no capabilities) with those names and assign them to teachers along with the real roles. select the alternative name for teacher that you wish to be displayed in the course description when courses are listed. For example, copy the guest role, call it Lead Teacher and make this the course contact. You may have 5 teachers in the course but only one name will appear as Lead Teacher. If nobody is assigned the role Lead Teacher, no course contact will show.
Or
*Names for different roles in a course may be changed in the [[Course settings|Course administration > edit settings]] "Role renaming" fields. For example, some courses the teacher wants the title "Professor", or "Chief" or "Mentor".
Or
*[[Language customization|Edit the language files]] and change any word you want.

==How do I enable teachers to set role overrides?==

#Access ''Site administration > Users > Permissions > Define roles''.
#Edit the teacher role and change the capability [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Site administration > Users > Permissions > Define roles'').
#Check the appropriate box(s) in the teacher row to set which role(s) teachers can override. Most likely it will just be the student role (you don't want teachers to be able to override admins!), so check the box where the teacher row intersects with the student column.
#Click the button "Save changes".

==How do I enable teachers to assign other teachers in a course?==

This is disabled by default but it can be switched on by modifying the teacher's role. In ''Site administration > Users > Permissions > Define roles'' select the "Allow role assignments" tab and tick the checkbox where Teacher and Teacher intersect.

==Why doesn't "Switch role to.." within a course seem to work properly?==

This feature is intended for teachers so that they can see how their course appears for students. It isn't a reliable view however, as some features do not display correctly when viewed by a teacher who has switched their role to a student. Certain actions (specifically submitting assignments) are excluded from working with 'switch roles' (as the submitted work would not be visible on the grading pages, due to the user not having the 'submit' permission when they have not switched roles). For that reason it is always preferable where possible to have a "test" student log in to use.

==How can I allow a non-editing teacher to "switch role to " a student?==

# In ''Site administration > Users > Permissions > Define roles'', edit the non-editing teacher role and set the capability "moodle/role:switchroles" to "allow". This will then allow them to switch their role to a student or a guest (as defined on the ''Allow role switches'' screen.)

==I accidentally deleted a default role. How do I get it back?==

# Go to ''Site administration > Users > Permissions > Define roles'' and click the 'Add a new role' button
# Select the role e.g. Teacher to use
# Click continue
# Fill in the short name and custom full name
# Click the 'Create this role' button

==Are there any example roles?==

Yes. See [[Creating_custom_roles#Example_custom_roles| the current list]].

==How do I enable logged-in users to participate in front page activities?==

Either:

# Go to ''Administration > Site administration > Users > Permissions > Define roles'' and edit the 'Authenticated user on frontpage' role
# Allow capabilities for the front page activities
# Click the 'Save changes' button

Or:

# Go to ''Administration > Site administration > Front Page > Front Page settings''
# Set the default front page role to student
# Click the 'Save changes' button

==How can I prevent students from editing their profile?==

If you only want students to be prevented from editing their profile, and not all users, you can create a new role, such as Restricted user as described in the [[Demo teacher role]], with moodle/user:editownprofile set to prevent, and assign it to all students in the system context.

Alternatively, you could change moodle/user:editownprofile to not set for the [[Authenticated user role]], then create a new role for teachers with moodle/user:editownprofile set to allow.

==Why can't I add teachers or students site wide in Moodle?==

You can, however teachers and students typically work in one or more individual courses. It is unusual for a student to be studying every single course on your Moodle and unusual for a teacher to be teaching every single course. Therefore, the default Moodle does not use these as system wide roles. The Manager role might be one that makes sense to assign on a system or category context.

To assign a teacher or student site-wide

# Go to ''Site administration > Users > Permissions > Define roles'' and edit the role to include the ''system'' context.
#Then search for and allow the capability [[Capabilities/moodle/course:view|moodle/course:view]]
#Then assign users to this role via ''Administration>Site administration>Users>Permissions>Assign system roles''

It might be preferable to create a new role based on the teacher or student and assign this in the System context. Then assign individuals to that role.

==Why isn't my custom role listed as an available role for assigning?==

When adding/editing a custom role, be sure to tick one or more context types where the role may be assigned.

[[File:context types where role may be assigned.png]]

==How can I set a role back to default?==

# Go to ''Site administration > Users > Permissions > Define roles'' and click on the name of the role
# Click the Reset button
# Select items for reset as desired
# Click the continue button.

==Permissions don't seem to be working correctly. What can I do?==

[[File:reviewing badge permissions.png|thumb|Reviewing role permissions]]It is recommended that permissions for each role are reviewed and set according to the role archetype.

# Go to ''Administration > Site administration > Users > Permissions > Define roles'' and click the edit icon opposite a role
# Click the 'Show advanced' button to reveal the different permission settings
# Review permissions (filtering for particular permissions as appropriate) and, unless there is a good reason to do otherwise, change permissions so that all are set to the highlighted value
# Click the 'Save changes' button
# Repeat steps 1 to 4 for each role

==Is there a role that can be safely used for a government inspector/supervisor ?==
The [https://github.com/3-bits/moodle-role_sepe SEPE] role is used for a (Spanish) government supervisor who can access all Moodle courses without being able to change anything. It can be used in any other country/ language.

==What is the "none" role?==
It is possible to enrol users into a course so they appear as participants, but since they do not have a standard role such as student, they do not have any particular permissions. They cannot for example, engage in course activities. For discussion about the "none" role, see MDL-29599

==Any further questions?==

Please visit the [http://moodle.org/mod/forum/view.php?id=6826 Roles and Capabilities forum] on moodle.org.

[[Category:FAQ]]

[[de:Rollen FAQ]]
[[es:FAQ_roles]]
[[fr:FAQ des rôles]]
[[ja:ロールFAQ]]

Competencies FAQ

2023-02-07T10:53:36Z

Leonstr: /* How can students create their own learning plans? */

{{Competencies}}

==Can a competency be added to more than one course or activity?==
Definitely - and your organisation might well need to do this, if certain competencies need to be met in a series of courses or several activities within one course.
==I can't see evidence uploaded by my students==
*Are you a course teacher? You will not be able to see evidence of prior learning unless your administrator has given you a role with the capability moodle/competency:userevidenceview set to ''Allow'' .
==How does 'Attach evidence' work?==
*A teacher can set "Attach evidence" as an option when an activity or a course is completed. Once an activity or course has been completed, the activity or course in question will display as Evidence at the bottom of the competency in question in a student's learning plan. A manager or other user with the capability moodle/competency:userevidenceview set to ''Allow'' will be able to see this evidence.

[[File:evidencedisplayed.png|center]]

*However, they will not be alerted that the evidence is available, so the student should request a review, as below.
==How does "Request review" work?==
* A student can request a review of a competency, for example if they have submitted a piece of work as attached evidence and they wish to alert their course tutor to this. The student accesses the competencies from their learning plan and clicks'"Request review" from the Edit menu.
[[File:studentrequestreview.png|center]]
*The student will then see 'waiting for review' next to that competency.
*The course tutor/supervisor or anyone who is [[Capabilities/moodle/competency:usercompetencyreview| allowed to review competencies]] will see the request from the learning plans block on their dashboard:
[[File:sendforreview1.png|center]]
*They click the link to access the student's requested competency and (''1 in screenshot below'') click to start the review.
*When the review is in progress, the words the student sees change from 'waiting for review' to 'in review'.
*The course tutor can then review the evidence (''2 in screenshot below'') and then (''3'') click to finish the review. The message 'in review' no longer displays for the student.
*The course tutor can then rate the competency if required ''(4):''
[[File:sendforreview2.png|center|thumb|600px]]

==How can a course teacher review competencies?==
See the [[Competency reviewer]] role.

==How can a course teacher view their students' learning plans?==
See the [[Learning plan viewer]] role.
==How can a course teacher manage their students' learning plans?==
See the [[Learning plan supervisor]] role.

==How do teachers rate competencies?==
Competencies may be met automatically upon activity completion (with the 'Default' scale as above) or teachers may rate competencies manually with a customised 'Proficient' scale.
*A teacher accesses the [[Competency breakdown report]], selects a student and clicks on a particular competency which has not yet been rated:
[[File:ratecompetencies12.png|center]]
*The teacher then clicks the 'Rate' button:
[[File:ratecompetencies2.png|center]]
*The teacher then chooses from the desired rating from the available options:
[[File:ratecompetencies3.png|center]]
*Once saved, the Proficient scale will change if the competency was met:
[[File:ratecompetencies4.png]]
*The competency breakdown report will reflect this, using the wording of the scale:
[[File:ratecompetencies5.png|center]]
*In the example below, the first competency was manually rated "Highly competent"; the second competency was automatically met upon activity completion and the third competency was manually rated "Not competent".
[[File:ratecompetencies6.png|center]]

==I can't see the Learning plans block==
*Are you a course teacher? You will not be able to see the [[Learning plans block]] unless your administrator has set the capability block/lp:view to Allow for teachers. However, administrators additionally need to set other capabilities in the system context relating to viewing learning plans and evidence for the block to display any useful information.
*It might be helpful to create a custom role, such as 'Supervisor', with the capabilities you wish to allow in the system context.
*If students have no learning plans, or if teachers/supervisors have no competencies needing reviewing, then the Learning plans block is not visible when editing is not turned on.

== I can't see competencies when trying to add them to a learning template==
Make sure you are in the right part of the site. If you added competencies to a category you will need to add the learning template to that category. If you added competencies to the system you will need to add your learning plan template to the system.

==The learning plan shows all competencies met but the course competencies screen shows some are still incomplete.==
*Competencies exist outside a course,so it might be that the competency has been met in another course but not the one you are in
*If a manager or other user who is [[Capabilities/moodle/competency:usercompetencyreview| allowed to review competencies]] chooses to ''rate'' a competency from the learning plan, then the competency will not show as complete inside the course, but it will display as complete in the learning plan.

==The progress bar shows 100% complete but the learning plan is not marked complete.==
*A learning plan does not automatically display as "complete" once all competencies have been met.
*It may be manually marked as complete by a user with the relevant capabilities - or -
* a due date may be set for completion when a learning plan template is created.
==What is the difference between 'default' and 'proficient' when setting up scales in a competency framework?==
*The default value is what is displayed in the breakdown report and for a student in their learning plan when a competency is automatically met upon activity completion. In the example below, 'competent" will display when a student completes a task satisfactorily.
*Items in the Proficient list can be displayed when a teacher rates a competency manually. There may be several different levels which can all be competent. In the example below, 'Just competent','Competent' or 'Highly competent' will result in the student achieving that competency:
[[File:levels.png|center|Custom competency scale]]

Note that the above is a custom created scale.

==How can students create their own learning plans?==
*If authenticated users have the capability ''[[Capabilities/moodle/competency:planviewowndraft|competency:planviewowndraft]]'' and ''[[Capabilities/moodle/competency:planmanageowndraft|competency:planmanageowndraft]]'' set to "Allow" then they will see a button "Add new learning plan" when they access their learning plans from their profile.
*They can then create a draft learning plan and request a review of it by a manager or other user with the capability ''[[Capabilities/moodle/competency:planmanagedraft|moodle/competency:planmanagedraft]]''.

==How can I export or import competency frameworks?==

See [[Competency frameworks]].

==Any further questions?==

Please post in the [https://moodle.org/mod/forum/view.php?id=8266 Competencies forum] on moodle.org

[[de:Kompetenzen FAQ]]
[[es:Competencias FAQ]]
[[fr:FAQ des compétences]]

Override permissions

2023-01-29T08:47:53Z

Leonstr: Spaces

{{Roles}}
Overrides are specific permissions designed to override a role in a specific context, allowing you to "tweak" your permissions as required.

Overrides may be used to "open up" areas by giving users extra permissions. For example, an override may be used to enable students to rate forum posts (see [[Forum settings]] for details).

Overrides may also be used to prevent actions, such as starting new discussions in an archived forum.

==Permissions==
[[File:override permissions.png|thumb|Override permissions with overridden permission highlighted]]
There are four settings for each permission capability:

;Inherit
:The default setting. If a capability is set to inherit, the user's permissions remain the same as they are in a less specific context, or another role where the capability is defined. For example, if a student is allowed to attempt quiz questions at the course level, their role in a specific quiz will inherit this setting. Ultimately, if permission is never allowed at any level, then the user will have no permission for that capability.

;Allow
:This enables a user to use a capability in a given context. This permission applies for the context that the role gets assigned plus all lower contexts. For example, if a user is assigned the role of student in a course, they will be able to start new discussions in all forums in that course (unless a forum contains an override with a prevent or prohibit value for the capability).

;Prevent
:By choosing this you are removing permission for this capability (only for this role), even if the users with this role were allowed that permission in a higher context. If any other role allows the same capability, even for a higher or lower context, this prevent will have no effect.

;Prohibit
:This is rarely needed, but occasionally you might want to completely deny permissions to a role in a way that can NOT be overridden at any lower context or by another role. An example of when you might need this is when an admin wants to prohibit one person from starting new discussions in any forum on the whole system. In this case they can create a role with that capability set to "Prohibit" and then assign it to that user in the system context.

==Conflict resolution of permissions==

Permissions at a "lower" context will generally override anything at a "higher" context (this applies to overrides and assigned roles). The exception is PROHIBIT which can not be overridden at lower levels.

If two roles are assigned to a person in the same context, and for a particular permission one role has ALLOW and one has PREVENT, then ALLOW will win.

===Special exceptions===

Note that the guest user account will generally be prevented from posting content (e.g. forums, calendar entries, blogs) even if it is given the capability to do so.

==Locations for overriding permissions==

*Front page context: ''Administration > Front Page settings > Users > Permissions''
*Course category context (when used): ''Category > Administration > Permissions''
*Course context: ''Administration > Course administration > Users > Permissions''
*Module context: (from the chosen module) ''Administration > Module administration > Permissions''
*Block context: (from the chosen block) ''Administration > Block administration > Permissions''
*User context: (from the user's profile) ''Administration > Roles > Permissions''

==Ability to override permissions==

Users who have the capability [[Capabilities/moodle/role:override|moodle/role:override]] allowed or the capability [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed) can override permissions for selected roles (as set in [[Allow role overrides]]).

The default manager role has the capability moodle/role:override allowed, and can override permissions for all other roles.

The default teacher role has the capability moodle/role:safeoverride allowed, and can override permissions for the roles of non-editing teacher, student and guest.

==Enabling non-editing teachers to override safe permissions==

#Access ''Administration > Site Administration > Users > Permissions > Define roles''.
#Edit the non-editing teacher role and change the capability [[Capabilities/moodle/role:safeoverride]] to allow.
#Click the button "Save changes".
#Click the tab "Allow role overrides" (in ''Administration > Site administration > Users > Permissions > Define roles'').
#Check the appropriate box(s) in the non-editing teacher row to set which role(s) they can override. Most likely it will just be the student role (you don't want non-editing teachers to be able to override managers), so check the box where the non-editing teacher row intersects with the student column.
#Click the button "Save changes".

If preferred, a new role for overriding permissions may be created and selected non-editing teachers assigned to it.

==Overriding permissions for selected students==
Sometimes a teacher will want to override permissions for selected students. Typically they will assign a student a role locally. For example, assign a student as a non-editing teacher. However, managers can override specific permission in a role. This does not create a new role. It modifies an existing specific role and affects all users assigned to that role in the context.

Sometimes the administrator (or someone with the permissions to) will create a new role. For example, the administrator will copy all the student permissions to a new role, then change specific permissions. The teacher then assigns specific students to this role without having to worry about checking off the correct role permissions.

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=199435 Course role which revokes capability granted in a sitewide role] forum discussion

[[es:Anular permisos]]
[[eu:Baimenak kendu]]
[[fr:Définir des dérogations aux rôles]]
[[ja:ロールのオーバーライド]]
[[de:Zugriffsrechte ändern]]

PHP

2022-12-18T14:42:58Z

Leonstr: /* PHP Extensions and libraries */ GD has been required since Moodle 2.5 (MDL-34331)

{{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 Versions==
* Moodle 3.0.1 and later support PHP 7, however
** Moodle 3.1 and earlier does not support PHP 7.1 or later (this means that there is currently no combination of releases of Moodle and PHP that are still supported before Moodle 3.4);
* Moodle 3.4 and Moodle 3.5 '''require''' PHP 7.0 or PHP 7.1 or PHP 7.2
* Moodle 3.6 '''requires''' PHP 7.0 or later
* Moodle 3.7 '''require''' PHP 7.1 or later
* Moodle 3.9 '''require''' PHP 7.2 or later
* Moodle 3.11 and later '''require''' PHP 7.3 or later
==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.
* ''memory_limit'' needs to be at least 96M (although some functions may not work if this low). Moodle will refuse to install if lower. 128M is recommended. Large systems may need an even higher setting.
* ''session.save_handler'' needs to be set to FILES.
* ''magic_quotes_runtime'' needs to be OFF. (DEPRECATED in PHP 5.3.0, and REMOVED as of PHP 7.0.0.)
* ''file_uploads'' needs to be ON.
* ''session.auto_start'' needs to be OFF.
* 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 installations 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.ini file:
* '''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 required.
* 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 required.
* 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 required.
* 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
* [[MoodleDocs:Style_guide#PHP_syntax_highlighting]] to highlight PHP syntax
* [[Code syntax highlighting]] that uses the GeSHi (Generic Syntax Highlighter) filter.
[[de:PHP]]
[[es:PHP]]

admin/environment/php extension/gd

2022-12-18T14:16:51Z

Leonstr: /* Installing */ Add instructions for Windows

{{Environment}}
== GD extension for PHP ==

This extension provides functionality for handling graphics directly from PHP scripts. It supports the PNG, JPEG, XPM formats as well as FreeType/ttf fonts.

== Installing ==
Package names below may vary if using third party package repositories or the PHP version is different from the operating system's default.

=== Ubuntu ===
Download and install gd:

sudo apt-get install php-gd

You might need to restart Apache (not necessary):

sudo /etc/init.d/apache2 restart

=== CentOS ===
Download and install gd:

dnf install php-gd

You might need to restart PHP-FPM to apply the change in configuration:

systemctl restart php-fpm

If you are unable to find the correct package try searching with:

dnf search 'php*-gd'

=== Microsoft Windows ===
The gd extension is normally included in the ''ext'' folder with PHP for Microsoft Windows. If Moodle reports this is missing ensure the following line is in ''php.ini'':

extension=gd

There must be no ';' at the start of this line.

You will probably need to restart your web server to apply this change: for XAMPP run ''xampp_stop'' then ''xampp_start''.

[[Category:Environment|PHP]]

[[es:admin/environment/php extension/gd]]

Cron with Unix or Linux

2022-12-14T20:10:16Z

Leonstr: /* Using the crontab program on Unix/Linux */ Capitalisation

{{Installing Moodle}}
On Unix and Linux use the built in ''cron'' program which is standard on nearly all systems. You are required to add a command to the 'crontab' (the table that holds cron commands) for the web server user.

There are two different methods that can be used to invoke the Moodle cron process:

'''NOTE:''' The commands shown need to be added to the crontab to function (described in a moment). However, you can - and should - run them on the command line to check they work first.

== Method 1: The command line (cli) cron ==

If you have a choice, this is normally the best way to run Moodle cron.

PHP is also capable of running programs directly from the command line. Your system needs to be set up to do this; specifically you need the 'CLI' version of PHP to be installed. Most systems with PHP installed will have this by default. If you have the PHP CLI version installed then this is the recommended method of invoking cron. The correct command will be something like...
<pre>
/usr/bin/php /path/to/moodle/admin/cli/cron.php
</pre>
(substitute the correct path to moodle and for php as required)

You can simply type this on the command line this to see if it works. If you are not sure about the path to PHP you can type "<code>which php</code>".

'''Tip:''': If you have problems, see the [[PHP]] page. In particular, suspect an alternate php.ini for the CLI PHP command which may not have suitable settings.

== Method 2: Web based cron ==

'''NOTE:''' In order to use the web based cron script you must first check [[Cron settings]] to make sure this method is permitted.

The idea is to call the following web page (you can try this from your browser):
<pre>
http://url.of.your/moodle/admin/cron.php
</pre>

A command line (text based) browser is needed to run this on the server. Possibilities are as follows (OSX, for example, only ships with curl)...
<pre>
/usr/bin/wget -q -O /dev/null/ http://url.of.your/moodle/admin/cron.php
</pre>
(no output is displayed - remove the ''-O /dev/null/'' to test)

...OR...

<pre>
/usr/bin/curl http://url.of.your/moodle/admin/cron.php -o /dev/null/ -silent
</pre>
(no output is displayed - remove the ''-o /dev/null/ -silent'' to test)

==Using the crontab program on Unix/Linux==

Once you have selected (and tested!) an appropriate command to invoke the Moodle cron it must be added to the web users 'crontab' to schedule it to run regularly. 'Crontab' is both a file containing the user's cron commands and is also the name of the (command line) program used to edit it. Use the following command (as root) substituting the correct user in place of 'www-data' (e.g. 'apache' for CentOS, 'www-data' for Debian/Ubuntu, '_www' for macOS—Google will know!)
<pre>
# crontab -u www-data -e
</pre>
This will bring up an editor window (the first time it may ask you which editor to use). Add the command onto the end of the file in this way (it may be empty or it may have some instructional comments):
<pre>
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php
</pre>
The first five * entries specify the times, followed by the command, to run. This says to run the command as often as possible, i.e. every minute.

See https://en.wikipedia.org/wiki/Cron#CRON_expression for details on cron expressions.

== See also ==

* [http://linuxweblog.com/node/24 A basic crontab tutorial]
* [http://www.freebsd.org/cgi/man.cgi?query=crontab&apropos=0&sektion=5&manpath=FreeBSD+6.0-RELEASE+and+Ports&format=html Online version of the man page]

[[es:Cron con Unix o Linux]]

Quiz FAQ

2022-12-05T21:52:37Z

Leonstr: /* Can I print the quiz results without the answers history? */ Spelling/grammar

{{Quiz}}
==General==
===How can guests answer a Moodle quiz?===

It is not possible for guests to use [[Activities|activities]] in Moodle.

But you can build a quiz on Google Forms and give a link from within Moodle.

===How can I try a quiz before it is released?===

You have prepared a quiz exam for your students. It is currently in a hidden state. The exam opens on the day of the exam, at a time that the students know about. However, to satisfy yourself that it is doable in the time allotted, You wish to do a dry run yourself before that date. How can You accomplish this?

Method 1: Use the Preview feature available to you as a teacher as you are making the quiz.

Method 2:

# Make a dummy account with a name like "Test Student".
# Enrol that user in the course as a student.
# Add a "User override" to the quiz, so "Test Student" can attempt the quiz before it is open to everyone else.
# Log in as "Test student".
# Attempt the quiz.
# Log back in as teacher.
# Review the attempt.
# Go to Results -> Grades and delete the test attempt.
# Un-enrol "Test Student" from your course.

Method 3: Set up a Moodle Playground course for your teachers. Add teachers with dual role (teacher and student). Teachers can later copy the quiz/assignment/whatever over to their live class.

===How can I enable notification of quiz submissions?===

See [[Quiz submission notification]].

===How do I send a bulk message to all students who haven't completed a quiz?===
*From your navigation block, click ''Reports>Course participation''
*From the drop down, choose your quiz.
*In ''Show only'', choose "Student" and in ''Actions'', choose "post"
*In the list that appears, tick/check the boxes next to those you wish to message.
*In the bottom dropdown ''With selected users'', choose "send message"

[[File:quizemail.png|500px]]

===How can build a quiz that picks X questions randomly from a larger question bank?===
See the section on adding random questions in [[Building Quiz]].

===How can I print a copy of a quiz?===

Use your browser printer option (for example by right-clicking and selecting Print) When a student prints their finished quiz, responses and feedback will also be printed.

[[File:browserquizprint29.png|thumb|center|400px|Print preview of finished quiz - Click to enlarge]]

You can also export the question as Moodle XML, or GIFT format. If you open either of those files in a text-editor, you should be able to see most of the details of each question.

=== How can I print all the students' quiz questions and answers?===
*Two options are available:
** Install the [https://moodle.org/plugins/quiz_archive quiz archive report] additional plugin - Moodle quiz report plugin to achieve archiving your test, by printing out all attempts at once.
** Install the [https://moodle.org/plugins/quiz_answersheets Export quiz attempts] additional plugin - This quiz report allows you to get view of a quiz attempt that is formatted for easy printing.
=== How can I optimize a Moodle server for performing more concurrent quizzes? ===

See [[Performance recommendations]], also the forum discussion [https://moodle.org/mod/forum/discuss.php?d=418615 Quiz with 400+ concurrent users: what‘s best?]

=== Can I release the answers to students who did not attempt a quiz? ===
Yes. One way to handle this with standard Moodle would be to open the quiz after the deadline and add a time limit to the quiz of one second. Unless students are extremely quick they will not be able to gain any points, but would see the general feedback.

=== How can I make Moodle quizzes if my school does not have enough computers / fast internet / a good Moodle server? ===
* Check the [[Offline quiz activity]] additional plugin.
* Check the [https://moodle.org/plugins/mod_exam exam] additional plugin. It allows the teacher to build quizzes with multiple choice question based on Quiz module. Main purpose of Exam module is to improve performance of quiz and to reduce database overhead, so that a large number of users can attempt quiz simultaneously. Warning - Technically it is possible for students to manipulate their exam grades if they know right parameters or they could see correct answers if they could read javascript objets being transmitted in their browser. Use with Caution.
* Read about the use of Chromebooks and iPad in the [[https://docs.moodle.org/38/en/Safe_Exam_Browser | Safe Exam Browser]] Moodle documentation for version until 3.8.
* Visit the page for [https://www.eventbrite.com.au/o/transforming-exams-e-exams-symposium-17431618115 Transforming Exams] - Transforming Exams is an Australian Government funded research project looking at approaches to conducting authentic digital assessment in the exam rooms of Australian universities via the use of Bring-your-own laptops. The project involves 10 Australian university partners and is lead out of Monash University. See [http://transformingexams.com/ TransformingExams.com] for project information.

===Can I print the quiz results without the answers history?===
If you want to print the results of all the student attempts, but omit the answers history, as it might take much space, you can do so by accessing the settings on Site admin -> Appearance -> Additional HTML. In the 'Within head' setting, put something like:

<style type="text/css">
@media print {
.que .history {
display: none;
}
}
</style>

===Is it possible for a teacher to add a personal/private note to a student's quiz submission?===
Not really, but as a workaround, you can use the buit-in [[Notes]] feature.

===Copying a quiz===
When you add questions to a quiz, you are not actually adding questions, but rather links or pointers to questions in the question bank. When you copy a quiz, two things can happen depending on where the questions are placed:

* If the questions are placed in a question category of the quiz, for example the "Default category for questions shared in the quiz context", the quiz is copied as well as the question category together with the questions it contains. See [[https://docs.moodle.org/402/en/Question_contexts#How_to_access_the_Quiz_activity_context How to access the Quiz activity context]].
* If the questions are not placed in a question category of the quiz, the quiz is copied but not the questions. However, the links to the original questions are copied. Therefore, when editing the quiz copy, you are also editing the questions of the original quiz, because the question links point to the same questions. Be careful!

=== Can I know the marks per each section of a quiz?===
An additional plugin [https://moodle.org/plugins/quiz_markspersection Marks per section] does exactly that.

==Setup==

===Why am I no longer allowed to add or remove questions?===
Most likely it is because you have students that have already attempted the quiz. You will need to delete all of the attempts by selecting them and choosing to delete them if you need to add/remove questions from a quiz.

If you are developing a new quiz where the attempts have just been trials then deleting the previous attempts will have no consequences in the grade book.

There are several ways of getting to the “attempts #” which you need to click on to delete the previous attempts. Use which ever works for you.
#Click on the quiz that you want to amend. It will take you to a page with “attempts #" at the top.
#If you are on a page with this message “You cannot add or remove questions because the quiz has been attempted (attempts #)” Click on "attempts #".
#If you have navigated away from the page with the message go to the Settings block > Quiz Administration > Edit Quiz.
Whichever way you find “attempts #” click on it and you will go to a page with a drop down menu at the top. Select “all users who have attempted the quiz”. There are several other click boxes select whatever applies to your situation.
Click “Show Report” and then “select all”. Click “Delete selected attempts” and confirm selection.

Go back to Quiz Administration > Edit Quiz and you will now be able to add or delete questions.

===How can I remove a problem question after the quiz has been taken?===

You can not remove a question once a quiz has been taken by one student or more. However you can change the score and flag the question so you know it has problems.

Set the score for that question to 0.
*Caution: In some versions of Moodle if you use this question in an other quiz, this will potentially change the question in that quiz as well. A trick is to score the question as 0, then regrade the just completed quiz. This will establish the new grade for gradebook. Now go back and change the score to the original value.

Find the question in Question Bank. Maybe edit the title (e.g. 'Do not use in Bio101'). Or if you do not share the question category with other teachers, create a sub category, move the offending question there, and perhaps create a better question to replace the one you just moved. Create a new quiz and if necessary hide the old one.
*Caution: if other departments or teachers use a question category it might be wise to check with the team before moving or changing any question. This is one reason importing questions in a course is a good best practice in some situations.

===How can I turn off glossary auto-linking in a quiz? ===
*In the Quiz administration settings block there will be a link "filter".
*Click the link and you will have the option to disable filters just for that particular quiz:

===Can I make a second quiz start right away after a first quiz is finished?===
By using a hack (See [https://moodle.org/mod/forum/discuss.php?d=377382 this forum thread]).

In the 'Overall feedback' for the first quiz, add some code which redirects to the second quiz. Make a big button to make that obvious:

<nowiki><div style="text-align:center;padding:20px;">
<a href="https://--your domain--/mod/quiz/view.php?id=--quiz 2 no--" target="_blank">
<button type="button" style="height:100px;font-size:24px;">Click here to access Quiz 2</button>
</a>
</div></nowiki>

It would look like this:

[[File:Click here to access Quiz 2.png|200px]]

Notes:

* The button will not appear in the gradebook.
* In the quiz settings and under Review options, select 'Overall feedback' under 'Immediately after the attempt'. Deselect 'Overall feedback' under 'Later, while the quiz is still open' and 'After the quiz is closed'.

===Prevent entry to a quiz some time after its start===
Suppose a quiz is set to open at 13:00 and the time limit is set to 45 minutes or some other value. Students have to enter the quiz from 13:00 to 13:15, otherwise they should not be able to do so. Proceed as follows to prevent students from entering the quiz after 13:15.

Create another quiz, let's call it an 'entry' quiz, containing a simple multiple choice, true or false, or short answer question, such as "Do you want to take the quiz? Y or N" or any other similar question. Tell students that they must answer and "Submit all and finish" in order to access the main quiz. In the settings of this entry quiz, set "Open the quiz" to 13:00 and "Close the quiz" to 13:15, that is, it is only open for the first 15 minutes.

In the main quiz settings and under "Restrict access", add a "Grade" restriction and select the entry quiz. If you do not specify a grade, the restriction is satisfied regardless of the grade obtained in the entry quiz.

You can also add "Date" restrictions to both the entry quiz and the main quiz to control their display.

Thus, punctual students will have access to the entry quiz from 13:00 to 13:15 and therefore to the main quiz throughout its 45 minutes duration. Latecomers will not have access to the entry quiz after 13:15 and therefore they will not be able to access the main quiz at all.

==Attempts==

===How can I give particular students extra time or numbers of attempts?===
*In the Quiz administration there is a link "User overrides"
*Click this link and you will be able to choose one or more users and change quiz dates, times or number of attempts.

[[File:quizuseroverride.png|500px]]

===Can I have different start times/timings/numbers of attempts for different groups?===
*In the Quiz administration settings block, there is a link "group overrides" that allows you to do things like grant extensions to certain groups of students.
*Click this link and you will be able to select your groups and change the quiz dates, times and number of attempts:

[[File:quizgroupoverride.png|500px]]

===What happens if students submit answers after the quiz closing date?===
It is possible for students to still submit answers after the quiz has closed (for example if they started the attempt before the closing date but then took a long time before submitting). These responses are stored by the quiz module, but the students are not given any credit for them. The teacher can see these answers when reviewing the student's attempts and can give the student credit for them by manually entering a grade in the gradebook. Also the teacher could change the closing date after the fact and regrade the attempts. The students' answers would then get graded.

===How can a "Never submitted quiz" attempt be submitted?===
Currently there is no way to retrieve an attempt that was "Never Submitted", and get it back into the "In progress" state. Perhaps the best solution is to plan ahead and set your quiz to set your quiz to be submitted automatically. Alternatively, you can
# Update the quiz : set the "close the quiz" date after today
# Set "When time expires" to "There is a grace period ..."
#Under Grade set "Attempts allowed" to "unlimited"
#Question behavior: Each attempt builds on the last "Yes"
# Invite the students who did not close their exams
# Allow them to start a new attempt, and close it immediately.

===Why can't people (guests) attempt a quiz without creating an account and logging in?===

This is difficult to implement for technical reasons.

To explain: The quiz has to link all information about an attempt to a particular 'user' record in the database, and each user can only have one open quiz attempt at a time. All not-logged-in users share the same 'guest' user database record. Therefore, two guests could not attempt the quiz at the same time, and even if they could, it would be difficult to prevent one guest seeing another guest's attempts.

Of course, given enough work, it would be possible to change some of those assumptions, and so make it possible for guests to attempt quizzes. Indeed, some of the obstructions to implementing this have already been removed while doing other work on the quiz, but there is still some way to go. If you would like to see this implemented, please vote for MDL-17892.

A workaround is to create a visitor account, say with username = guest, password = visitor, for everyone to share.

===How can I prevent a student from reviewing or jumping around questions in a quiz?===
You can block the quiz navigation block and the summary of quiz page with CSS code in a theme. However, if a student fails to answer a question, they will not know if you implement this "solution". Also if others on the site do not want this patch, make sure the theme you select for the course is not used by others.

For example using the Afterburner theme, enter this in the CSS code area:

:div#mod_quiz_navblock {visibility:hidden;}
:table.quizsummaryofattempt {visibility:hidden;}

There are other CSS solutions.

===How can I force my students to answer all the question in a quiz before they submit?===

There are various ways to answer this:
# You can't.
# Your students are not stupid. They know they will get zero marks for any question they do not answer, so they already have a strong incentive to answer every question. Furthermore, at the end of the quiz there is the summary page where they can easily check that they have answered all the questions before they submit, so they won't accidentally miss questions.
# OK, so you want us to write code that won't let students submit before they have answered each question. Well, all that does is forces the student to put random junk like "asdf" into each question before they click the button, or randomly make a choice in each multiple choice question. There is no educational benefit in this. You get more meaningful information if students leave those questions blank rather than putting in random responses.

=== Can I force a user to reattempt only incorrect questions in subsequent attempts?===

The easiest way to implement this solution is to use javascript or modify the source code on your Moodle site. The javascript solution described in [https://moodle.org/mod/forum/discuss.php?d=395125 this forum thread] is as follows:

* Insert the following code in the HTML of the text of a description question.
* Include this description question in the quizzes. If the quizzes are displayed on multiple pages, add the description question on each page.
* If you are using the [[Adaptable theme]] you can put the JS in the JS section of the [[Adaptable theme]]. With the standard [[Boost theme]] or [[Classic theme]] place the script in the Site Administration / Appearance / Additional HTML section. This way you don't have to include the script in every quiz.

<nowiki><h3>Title of the quiz</h3> // optional
<p>Give some info.</p> // optional

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script>
$(document).ready(function() {
// Clear sessionStorage after a certain delay
if (sessionStorage.getItem("setTime") != "set") {
nd = new Date();
lastTime = nd.getTime().toString();
sessionStorage.setItem("time", lastTime);
sessionStorage.setItem("setTime", "set");
}
// Set the delay to say 5 minutes: aferXmin = 5
// (Use 0.33 minutes, i.e. 20 sec, for demonstration purposes)
afterXmin = 5;
maxDelay = afterXmin * 60 * 1000;
d = new Date();
newTime = d.getTime()
lastTime = sessionStorage.getItem("time")
delay = newTime - lastTime;
if (delay > maxDelay) {
sessionStorage.clear();
}
// Show or hide correct or incorrect questions in the previous attempt:
i = 0;
$(".que").each(function() {
i++;
var x = i.toString();
if ($(this).hasClass("correct")) {
sessionStorage.setItem(x, "correct");
}
if ($(this).hasClass("incorrect")) {
sessionStorage.setItem(x, "incorrect");
}
if ($(this).hasClass("answersaved") && sessionStorage.getItem(x) == "correct") {
$(this).hide();
}
if ($(this).hasClass("answersaved") && sessionStorage.getItem(x) == "incorrect") {
$(this).show();
}
});
});
</script></nowiki>

===Prevent students from taking the quiz some time after its opening time===

Suppose a quiz opens at 14:00 on April 12, 2022. You don't want students to be able to start it after 14:10. Here is one way to do it. Note that the solution below is a workaround until a custom quiz access rule plugin is developed.

*Create a [[Label|label]] just above the quiz.
*In the label settings and in the "Label text", insert a message such as "Click the [Mark as done] button below to access the quiz:"
*Under "[[Restrict access]]", add a "Date" restriction "until 12 April 2022 14 10" as shown below.
*Under "[[Activity completion]]", set "Completion tracking" to "Students can manually mark the activity as completed" as shown below.

<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1528.png|850px]]</div>

*In the quiz settings and under "[[Restrict access]]", set an "[[Activity completion]]" to "Click the [Mark as done] button below to access th... must be marked complete" as shown below.

<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1536.png|800px]]</div>

Between 14:00 and 14:10, students will see the following.
*If they do not click the [Mark as done] button, the quiz is not visible nor accessible:
<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1554.png|750px]]</div>

*If they click the [Mark as done] button, the quiz is visible and accessible:
<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1556.png|750px]]</div>

After 2:10 pm, the "Click the [Mark as done] button below to access th..." label is no longer visible. So for students who have not clicked the [Mark as done] button, the quiz is no longer visible nor accessible. For students who clicked the [Mark as done] button, the quiz is accessible and remains accessible even if they temporarily quit and return to the quiz.

You could add another [[Label|label]] with the text "It is past 2:10 PM so you missed the opening of the quiz. It is no longer available.", with "Date" and "[[Activity completion]]" restrictions set in such a way that this label is displayed after 2:10 pm and only to students who have not clicked the [Mark as done] button.

==Grades==

===Why is my quiz not displaying in the gradebook?===

Go to the editing quiz page and check that you have a maximum grade that is more than 0 - if your score is 0, then the quiz will not appear in the gradebook.

===I've entered quiz grades manually in the gradebook. How can I allow students to improve on these grades?===

When a grade is entered directly in the gradebook, an "overridden" flag is set, meaning that the grade can no longer be changed from within the quiz.

However, the flag can be removed by turning editing on in the [[Grader report|grader report]], then clicking the edit grade icon, unchecking the overridden box and saving the changes.

===How can I set a grade to pass?===

See the section 'Setting a grade to pass for a quiz' in [[Activity completion settings]] for details.

===How can I have a quiz that is not graded?===

On the Edit quiz page, change the total score and each question's score to 0 instead of the defaults of 10 and 1 per question:
[[File:quizscore0.png|600px]]

==Appearance==

===How can I turn off question flagging?===
By default, flags are available in quiz questions.

[[File:flag.png|119px]]

There is a capability attached to this: [[Capabilities/moodle/question:flag]]. Remove this capability from roles that you don't want to see the flags. You can either do that by editing the role definitions globally, or by overriding the permissions in just one quiz or course.

===How can I hide the number of marks available for each question?===

This is not really possible unless you are prepared to edit the code.

If you have a custom theme, you can add CSS like this:
<syntaxhighlight lang="css">
.que .info .grade { display: none; }
</syntaxhighlight>
or you could try to make it more specific, and only hide the grade before the question is answered:
<syntaxhighlight lang="css">
.que.answersaved .info .grade,
.que.invalidanswer .info .grade,
.que.notyetanswered .info .grade { display: none; }
</syntaxhighlight>
You can also add this CSS using the [[Header_and_footer|Additional HTML admin setting]].

Alternatively, you can alter the PHP code here: https://github.com/moodle/moodle/blob/4de51c25ae227a727dcba7c39f6f644a5d47ce7a/mod/quiz/locallib.php#L1820. Change that line to give the behaviour you want, e.g.
<syntaxhighlight lang="php">
$options->marks = self::extract($quiz->reviewmarks, $when,
self::MARK_AND_MAX, self::HIDDEN);
</syntaxhighlight>

Be warned that any of these approaches will affect every quiz in the Moodle site.

===How can I delay the quiz feedback after the quiz has passed===
* Suppose the students take a "Main" one-hour quiz from 2 April 14:00 to 2 April 15:00. They shall not have any feedback during and after the quiz until the following week.
* Students take a "Follow up" quiz a week later, starting 9 April 14:00. If they succeed the "Follow up" quiz, they can then review the "Main" quiz and get their points.

This can be done by editing the "Main" and "Follow up" quiz settings, and the Gradebook set up as follows:

[[File:MoodleDocs201904041052.png|280px|thumb|right]]
'''"Main" quiz settings''' ''See also the image on the right'' ->

Timing
Open the quiz: 2 April 14:00
Close the quiz: 9 April 14:00
Review options
During the attempt
Uncheck feedbacks
Immediately after the attempt
Uncheck feedbacks
Later, while the quiz is still open
Uncheck feedbacks
After the quiz is closed
Check feedbacks
Restrict access
Student must match any of the following
Date: until 2 April 15:00
or
Student must match all of the following (restriction set)
Date: from 9 April 14:00
and
Grade: Follow up
Check must be ≥ 1 %

'''"Follow up" quiz settings'''

Timing
Open the quiz: 9 April 14:00

'''Gradebook set up'''
Main quiz: Weight 0.0, ID number "main"
Follow up quiz: Weight 0.0, ID number "followup"
Grade item "Total": Weight 100.0, Calculation = [[main]] + [[followup]] ''(<- do not copy/paste this equation, rewrite it)''

===Is there a way to display submitted images instead of titles of Images on the review page for the quiz?===
Yes. See [https://moodle.org/mod/forum/discuss.php?d=392623#p1582739 this forum post].

==Errors==

===I obtain the error 'The number of random questions required is more than are still available in the category!'===

Review your quiz and verify Moodle has enough questions from each category of questions it will be pulling from. You may have inadvertently selected more questions than what exists in the category. Also make sure you're not pulling questions from a category that has zero questions. Because you are picking random questions, rather than a specific question, it may not be apparent at first that you have run out of questions to ask!

==Quiz plugins==

There are a number of ways to extend quizzes, such as adding new reports and questions types. See [https://moodle.org/plugins/browse.php?list=category&id=28 Moodle plugins directory: Plugin type: Quiz].

==See also==

* [[Effective quiz practices]]
* [[Questions FAQ]]

==Any further questions?==

Please post in the [https://moodle.org/mod/forum/view.php?id=737 Quiz forum] on moodle.org.

[[Category:FAQ]]

[[de:Test FAQ]]
[[es:Examen FAQ]]
[[fr:FAQ sur les tests]]

Quiz FAQ

2022-12-05T21:46:18Z

Leonstr: Replaced <code> with <pre>/<syntaxhighlight>

{{Quiz}}
==General==
===How can guests answer a Moodle quiz?===

It is not possible for guests to use [[Activities|activities]] in Moodle.

But you can build a quiz on Google Forms and give a link from within Moodle.

===How can I try a quiz before it is released?===

You have prepared a quiz exam for your students. It is currently in a hidden state. The exam opens on the day of the exam, at a time that the students know about. However, to satisfy yourself that it is doable in the time allotted, You wish to do a dry run yourself before that date. How can You accomplish this?

Method 1: Use the Preview feature available to you as a teacher as you are making the quiz.

Method 2:

# Make a dummy account with a name like "Test Student".
# Enrol that user in the course as a student.
# Add a "User override" to the quiz, so "Test Student" can attempt the quiz before it is open to everyone else.
# Log in as "Test student".
# Attempt the quiz.
# Log back in as teacher.
# Review the attempt.
# Go to Results -> Grades and delete the test attempt.
# Un-enrol "Test Student" from your course.

Method 3: Set up a Moodle Playground course for your teachers. Add teachers with dual role (teacher and student). Teachers can later copy the quiz/assignment/whatever over to their live class.

===How can I enable notification of quiz submissions?===

See [[Quiz submission notification]].

===How do I send a bulk message to all students who haven't completed a quiz?===
*From your navigation block, click ''Reports>Course participation''
*From the drop down, choose your quiz.
*In ''Show only'', choose "Student" and in ''Actions'', choose "post"
*In the list that appears, tick/check the boxes next to those you wish to message.
*In the bottom dropdown ''With selected users'', choose "send message"

[[File:quizemail.png|500px]]

===How can build a quiz that picks X questions randomly from a larger question bank?===
See the section on adding random questions in [[Building Quiz]].

===How can I print a copy of a quiz?===

Use your browser printer option (for example by right-clicking and selecting Print) When a student prints their finished quiz, responses and feedback will also be printed.

[[File:browserquizprint29.png|thumb|center|400px|Print preview of finished quiz - Click to enlarge]]

You can also export the question as Moodle XML, or GIFT format. If you open either of those files in a text-editor, you should be able to see most of the details of each question.

=== How can I print all the students' quiz questions and answers?===
*Two options are available:
** Install the [https://moodle.org/plugins/quiz_archive quiz archive report] additional plugin - Moodle quiz report plugin to achieve archiving your test, by printing out all attempts at once.
** Install the [https://moodle.org/plugins/quiz_answersheets Export quiz attempts] additional plugin - This quiz report allows you to get view of a quiz attempt that is formatted for easy printing.
=== How can I optimize a Moodle server for performing more concurrent quizzes? ===

See [[Performance recommendations]], also the forum discussion [https://moodle.org/mod/forum/discuss.php?d=418615 Quiz with 400+ concurrent users: what‘s best?]

=== Can I release the answers to students who did not attempt a quiz? ===
Yes. One way to handle this with standard Moodle would be to open the quiz after the deadline and add a time limit to the quiz of one second. Unless students are extremely quick they will not be able to gain any points, but would see the general feedback.

=== How can I make Moodle quizzes if my school does not have enough computers / fast internet / a good Moodle server? ===
* Check the [[Offline quiz activity]] additional plugin.
* Check the [https://moodle.org/plugins/mod_exam exam] additional plugin. It allows the teacher to build quizzes with multiple choice question based on Quiz module. Main purpose of Exam module is to improve performance of quiz and to reduce database overhead, so that a large number of users can attempt quiz simultaneously. Warning - Technically it is possible for students to manipulate their exam grades if they know right parameters or they could see correct answers if they could read javascript objets being transmitted in their browser. Use with Caution.
* Read about the use of Chromebooks and iPad in the [[https://docs.moodle.org/38/en/Safe_Exam_Browser | Safe Exam Browser]] Moodle documentation for version until 3.8.
* Visit the page for [https://www.eventbrite.com.au/o/transforming-exams-e-exams-symposium-17431618115 Transforming Exams] - Transforming Exams is an Australian Government funded research project looking at approaches to conducting authentic digital assessment in the exam rooms of Australian universities via the use of Bring-your-own laptops. The project involves 10 Australian university partners and is lead out of Monash University. See [http://transformingexams.com/ TransformingExams.com] for project information.

===Can I print the quiz results without the answers history?===
If you want to to print the results of all the student attempts, but ommit the answers history, as it might take much space, you can do so by accessing the settings on Site admin -> Appearance -> Additional HTML. In the 'Within head' setting, put something like:

<style type="text/css">
@media print {
.que .history {
display: none;
}
}
</style>

===Is it possible for a teacher to add a personal/private note to a student's quiz submission?===
Not really, but as a workaround, you can use the buit-in [[Notes]] feature.

===Copying a quiz===
When you add questions to a quiz, you are not actually adding questions, but rather links or pointers to questions in the question bank. When you copy a quiz, two things can happen depending on where the questions are placed:

* If the questions are placed in a question category of the quiz, for example the "Default category for questions shared in the quiz context", the quiz is copied as well as the question category together with the questions it contains. See [[https://docs.moodle.org/402/en/Question_contexts#How_to_access_the_Quiz_activity_context How to access the Quiz activity context]].
* If the questions are not placed in a question category of the quiz, the quiz is copied but not the questions. However, the links to the original questions are copied. Therefore, when editing the quiz copy, you are also editing the questions of the original quiz, because the question links point to the same questions. Be careful!

=== Can I know the marks per each section of a quiz?===
An additional plugin [https://moodle.org/plugins/quiz_markspersection Marks per section] does exactly that.

==Setup==

===Why am I no longer allowed to add or remove questions?===
Most likely it is because you have students that have already attempted the quiz. You will need to delete all of the attempts by selecting them and choosing to delete them if you need to add/remove questions from a quiz.

If you are developing a new quiz where the attempts have just been trials then deleting the previous attempts will have no consequences in the grade book.

There are several ways of getting to the “attempts #” which you need to click on to delete the previous attempts. Use which ever works for you.
#Click on the quiz that you want to amend. It will take you to a page with “attempts #" at the top.
#If you are on a page with this message “You cannot add or remove questions because the quiz has been attempted (attempts #)” Click on "attempts #".
#If you have navigated away from the page with the message go to the Settings block > Quiz Administration > Edit Quiz.
Whichever way you find “attempts #” click on it and you will go to a page with a drop down menu at the top. Select “all users who have attempted the quiz”. There are several other click boxes select whatever applies to your situation.
Click “Show Report” and then “select all”. Click “Delete selected attempts” and confirm selection.

Go back to Quiz Administration > Edit Quiz and you will now be able to add or delete questions.

===How can I remove a problem question after the quiz has been taken?===

You can not remove a question once a quiz has been taken by one student or more. However you can change the score and flag the question so you know it has problems.

Set the score for that question to 0.
*Caution: In some versions of Moodle if you use this question in an other quiz, this will potentially change the question in that quiz as well. A trick is to score the question as 0, then regrade the just completed quiz. This will establish the new grade for gradebook. Now go back and change the score to the original value.

Find the question in Question Bank. Maybe edit the title (e.g. 'Do not use in Bio101'). Or if you do not share the question category with other teachers, create a sub category, move the offending question there, and perhaps create a better question to replace the one you just moved. Create a new quiz and if necessary hide the old one.
*Caution: if other departments or teachers use a question category it might be wise to check with the team before moving or changing any question. This is one reason importing questions in a course is a good best practice in some situations.

===How can I turn off glossary auto-linking in a quiz? ===
*In the Quiz administration settings block there will be a link "filter".
*Click the link and you will have the option to disable filters just for that particular quiz:

===Can I make a second quiz start right away after a first quiz is finished?===
By using a hack (See [https://moodle.org/mod/forum/discuss.php?d=377382 this forum thread]).

In the 'Overall feedback' for the first quiz, add some code which redirects to the second quiz. Make a big button to make that obvious:

<nowiki><div style="text-align:center;padding:20px;">
<a href="https://--your domain--/mod/quiz/view.php?id=--quiz 2 no--" target="_blank">
<button type="button" style="height:100px;font-size:24px;">Click here to access Quiz 2</button>
</a>
</div></nowiki>

It would look like this:

[[File:Click here to access Quiz 2.png|200px]]

Notes:

* The button will not appear in the gradebook.
* In the quiz settings and under Review options, select 'Overall feedback' under 'Immediately after the attempt'. Deselect 'Overall feedback' under 'Later, while the quiz is still open' and 'After the quiz is closed'.

===Prevent entry to a quiz some time after its start===
Suppose a quiz is set to open at 13:00 and the time limit is set to 45 minutes or some other value. Students have to enter the quiz from 13:00 to 13:15, otherwise they should not be able to do so. Proceed as follows to prevent students from entering the quiz after 13:15.

Create another quiz, let's call it an 'entry' quiz, containing a simple multiple choice, true or false, or short answer question, such as "Do you want to take the quiz? Y or N" or any other similar question. Tell students that they must answer and "Submit all and finish" in order to access the main quiz. In the settings of this entry quiz, set "Open the quiz" to 13:00 and "Close the quiz" to 13:15, that is, it is only open for the first 15 minutes.

In the main quiz settings and under "Restrict access", add a "Grade" restriction and select the entry quiz. If you do not specify a grade, the restriction is satisfied regardless of the grade obtained in the entry quiz.

You can also add "Date" restrictions to both the entry quiz and the main quiz to control their display.

Thus, punctual students will have access to the entry quiz from 13:00 to 13:15 and therefore to the main quiz throughout its 45 minutes duration. Latecomers will not have access to the entry quiz after 13:15 and therefore they will not be able to access the main quiz at all.

==Attempts==

===How can I give particular students extra time or numbers of attempts?===
*In the Quiz administration there is a link "User overrides"
*Click this link and you will be able to choose one or more users and change quiz dates, times or number of attempts.

[[File:quizuseroverride.png|500px]]

===Can I have different start times/timings/numbers of attempts for different groups?===
*In the Quiz administration settings block, there is a link "group overrides" that allows you to do things like grant extensions to certain groups of students.
*Click this link and you will be able to select your groups and change the quiz dates, times and number of attempts:

[[File:quizgroupoverride.png|500px]]

===What happens if students submit answers after the quiz closing date?===
It is possible for students to still submit answers after the quiz has closed (for example if they started the attempt before the closing date but then took a long time before submitting). These responses are stored by the quiz module, but the students are not given any credit for them. The teacher can see these answers when reviewing the student's attempts and can give the student credit for them by manually entering a grade in the gradebook. Also the teacher could change the closing date after the fact and regrade the attempts. The students' answers would then get graded.

===How can a "Never submitted quiz" attempt be submitted?===
Currently there is no way to retrieve an attempt that was "Never Submitted", and get it back into the "In progress" state. Perhaps the best solution is to plan ahead and set your quiz to set your quiz to be submitted automatically. Alternatively, you can
# Update the quiz : set the "close the quiz" date after today
# Set "When time expires" to "There is a grace period ..."
#Under Grade set "Attempts allowed" to "unlimited"
#Question behavior: Each attempt builds on the last "Yes"
# Invite the students who did not close their exams
# Allow them to start a new attempt, and close it immediately.

===Why can't people (guests) attempt a quiz without creating an account and logging in?===

This is difficult to implement for technical reasons.

To explain: The quiz has to link all information about an attempt to a particular 'user' record in the database, and each user can only have one open quiz attempt at a time. All not-logged-in users share the same 'guest' user database record. Therefore, two guests could not attempt the quiz at the same time, and even if they could, it would be difficult to prevent one guest seeing another guest's attempts.

Of course, given enough work, it would be possible to change some of those assumptions, and so make it possible for guests to attempt quizzes. Indeed, some of the obstructions to implementing this have already been removed while doing other work on the quiz, but there is still some way to go. If you would like to see this implemented, please vote for MDL-17892.

A workaround is to create a visitor account, say with username = guest, password = visitor, for everyone to share.

===How can I prevent a student from reviewing or jumping around questions in a quiz?===
You can block the quiz navigation block and the summary of quiz page with CSS code in a theme. However, if a student fails to answer a question, they will not know if you implement this "solution". Also if others on the site do not want this patch, make sure the theme you select for the course is not used by others.

For example using the Afterburner theme, enter this in the CSS code area:

:div#mod_quiz_navblock {visibility:hidden;}
:table.quizsummaryofattempt {visibility:hidden;}

There are other CSS solutions.

===How can I force my students to answer all the question in a quiz before they submit?===

There are various ways to answer this:
# You can't.
# Your students are not stupid. They know they will get zero marks for any question they do not answer, so they already have a strong incentive to answer every question. Furthermore, at the end of the quiz there is the summary page where they can easily check that they have answered all the questions before they submit, so they won't accidentally miss questions.
# OK, so you want us to write code that won't let students submit before they have answered each question. Well, all that does is forces the student to put random junk like "asdf" into each question before they click the button, or randomly make a choice in each multiple choice question. There is no educational benefit in this. You get more meaningful information if students leave those questions blank rather than putting in random responses.

=== Can I force a user to reattempt only incorrect questions in subsequent attempts?===

The easiest way to implement this solution is to use javascript or modify the source code on your Moodle site. The javascript solution described in [https://moodle.org/mod/forum/discuss.php?d=395125 this forum thread] is as follows:

* Insert the following code in the HTML of the text of a description question.
* Include this description question in the quizzes. If the quizzes are displayed on multiple pages, add the description question on each page.
* If you are using the [[Adaptable theme]] you can put the JS in the JS section of the [[Adaptable theme]]. With the standard [[Boost theme]] or [[Classic theme]] place the script in the Site Administration / Appearance / Additional HTML section. This way you don't have to include the script in every quiz.

<nowiki><h3>Title of the quiz</h3> // optional
<p>Give some info.</p> // optional

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script>
$(document).ready(function() {
// Clear sessionStorage after a certain delay
if (sessionStorage.getItem("setTime") != "set") {
nd = new Date();
lastTime = nd.getTime().toString();
sessionStorage.setItem("time", lastTime);
sessionStorage.setItem("setTime", "set");
}
// Set the delay to say 5 minutes: aferXmin = 5
// (Use 0.33 minutes, i.e. 20 sec, for demonstration purposes)
afterXmin = 5;
maxDelay = afterXmin * 60 * 1000;
d = new Date();
newTime = d.getTime()
lastTime = sessionStorage.getItem("time")
delay = newTime - lastTime;
if (delay > maxDelay) {
sessionStorage.clear();
}
// Show or hide correct or incorrect questions in the previous attempt:
i = 0;
$(".que").each(function() {
i++;
var x = i.toString();
if ($(this).hasClass("correct")) {
sessionStorage.setItem(x, "correct");
}
if ($(this).hasClass("incorrect")) {
sessionStorage.setItem(x, "incorrect");
}
if ($(this).hasClass("answersaved") && sessionStorage.getItem(x) == "correct") {
$(this).hide();
}
if ($(this).hasClass("answersaved") && sessionStorage.getItem(x) == "incorrect") {
$(this).show();
}
});
});
</script></nowiki>

===Prevent students from taking the quiz some time after its opening time===

Suppose a quiz opens at 14:00 on April 12, 2022. You don't want students to be able to start it after 14:10. Here is one way to do it. Note that the solution below is a workaround until a custom quiz access rule plugin is developed.

*Create a [[Label|label]] just above the quiz.
*In the label settings and in the "Label text", insert a message such as "Click the [Mark as done] button below to access the quiz:"
*Under "[[Restrict access]]", add a "Date" restriction "until 12 April 2022 14 10" as shown below.
*Under "[[Activity completion]]", set "Completion tracking" to "Students can manually mark the activity as completed" as shown below.

<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1528.png|850px]]</div>

*In the quiz settings and under "[[Restrict access]]", set an "[[Activity completion]]" to "Click the [Mark as done] button below to access th... must be marked complete" as shown below.

<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1536.png|800px]]</div>

Between 14:00 and 14:10, students will see the following.
*If they do not click the [Mark as done] button, the quiz is not visible nor accessible:
<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1554.png|750px]]</div>

*If they click the [Mark as done] button, the quiz is visible and accessible:
<div style="border:6px solid #eee;">[[{{ns:file}}:MoodleDocs_20210412_1556.png|750px]]</div>

After 2:10 pm, the "Click the [Mark as done] button below to access th..." label is no longer visible. So for students who have not clicked the [Mark as done] button, the quiz is no longer visible nor accessible. For students who clicked the [Mark as done] button, the quiz is accessible and remains accessible even if they temporarily quit and return to the quiz.

You could add another [[Label|label]] with the text "It is past 2:10 PM so you missed the opening of the quiz. It is no longer available.", with "Date" and "[[Activity completion]]" restrictions set in such a way that this label is displayed after 2:10 pm and only to students who have not clicked the [Mark as done] button.

==Grades==

===Why is my quiz not displaying in the gradebook?===

Go to the editing quiz page and check that you have a maximum grade that is more than 0 - if your score is 0, then the quiz will not appear in the gradebook.

===I've entered quiz grades manually in the gradebook. How can I allow students to improve on these grades?===

When a grade is entered directly in the gradebook, an "overridden" flag is set, meaning that the grade can no longer be changed from within the quiz.

However, the flag can be removed by turning editing on in the [[Grader report|grader report]], then clicking the edit grade icon, unchecking the overridden box and saving the changes.

===How can I set a grade to pass?===

See the section 'Setting a grade to pass for a quiz' in [[Activity completion settings]] for details.

===How can I have a quiz that is not graded?===

On the Edit quiz page, change the total score and each question's score to 0 instead of the defaults of 10 and 1 per question:
[[File:quizscore0.png|600px]]

==Appearance==

===How can I turn off question flagging?===
By default, flags are available in quiz questions.

[[File:flag.png|119px]]

There is a capability attached to this: [[Capabilities/moodle/question:flag]]. Remove this capability from roles that you don't want to see the flags. You can either do that by editing the role definitions globally, or by overriding the permissions in just one quiz or course.

===How can I hide the number of marks available for each question?===

This is not really possible unless you are prepared to edit the code.

If you have a custom theme, you can add CSS like this:
<syntaxhighlight lang="css">
.que .info .grade { display: none; }
</syntaxhighlight>
or you could try to make it more specific, and only hide the grade before the question is answered:
<syntaxhighlight lang="css">
.que.answersaved .info .grade,
.que.invalidanswer .info .grade,
.que.notyetanswered .info .grade { display: none; }
</syntaxhighlight>
You can also add this CSS using the [[Header_and_footer|Additional HTML admin setting]].

Alternatively, you can alter the PHP code here: https://github.com/moodle/moodle/blob/4de51c25ae227a727dcba7c39f6f644a5d47ce7a/mod/quiz/locallib.php#L1820. Change that line to give the behaviour you want, e.g.
<syntaxhighlight lang="php">
$options->marks = self::extract($quiz->reviewmarks, $when,
self::MARK_AND_MAX, self::HIDDEN);
</syntaxhighlight>

Be warned that any of these approaches will affect every quiz in the Moodle site.

===How can I delay the quiz feedback after the quiz has passed===
* Suppose the students take a "Main" one-hour quiz from 2 April 14:00 to 2 April 15:00. They shall not have any feedback during and after the quiz until the following week.
* Students take a "Follow up" quiz a week later, starting 9 April 14:00. If they succeed the "Follow up" quiz, they can then review the "Main" quiz and get their points.

This can be done by editing the "Main" and "Follow up" quiz settings, and the Gradebook set up as follows:

[[File:MoodleDocs201904041052.png|280px|thumb|right]]
'''"Main" quiz settings''' ''See also the image on the right'' ->

Timing
Open the quiz: 2 April 14:00
Close the quiz: 9 April 14:00
Review options
During the attempt
Uncheck feedbacks
Immediately after the attempt
Uncheck feedbacks
Later, while the quiz is still open
Uncheck feedbacks
After the quiz is closed
Check feedbacks
Restrict access
Student must match any of the following
Date: until 2 April 15:00
or
Student must match all of the following (restriction set)
Date: from 9 April 14:00
and
Grade: Follow up
Check must be ≥ 1 %

'''"Follow up" quiz settings'''

Timing
Open the quiz: 9 April 14:00

'''Gradebook set up'''
Main quiz: Weight 0.0, ID number "main"
Follow up quiz: Weight 0.0, ID number "followup"
Grade item "Total": Weight 100.0, Calculation = [[main]] + [[followup]] ''(<- do not copy/paste this equation, rewrite it)''

===Is there a way to display submitted images instead of titles of Images on the review page for the quiz?===
Yes. See [https://moodle.org/mod/forum/discuss.php?d=392623#p1582739 this forum post].

==Errors==

===I obtain the error 'The number of random questions required is more than are still available in the category!'===

Review your quiz and verify Moodle has enough questions from each category of questions it will be pulling from. You may have inadvertently selected more questions than what exists in the category. Also make sure you're not pulling questions from a category that has zero questions. Because you are picking random questions, rather than a specific question, it may not be apparent at first that you have run out of questions to ask!

==Quiz plugins==

There are a number of ways to extend quizzes, such as adding new reports and questions types. See [https://moodle.org/plugins/browse.php?list=category&id=28 Moodle plugins directory: Plugin type: Quiz].

==See also==

* [[Effective quiz practices]]
* [[Questions FAQ]]

==Any further questions?==

Please post in the [https://moodle.org/mod/forum/view.php?id=737 Quiz forum] on moodle.org.

[[Category:FAQ]]

[[de:Test FAQ]]
[[es:Examen FAQ]]
[[fr:FAQ sur les tests]]

Language FAQ

2022-11-02T21:38:52Z

Leonstr: Added "Error writing to database when opening language pack" (MDL-73571)

{{Language}}

== General ==

=== Which is the official language for Moodle? ===
The [http://lang.moodle.org/mod/forum/discuss.php?d=2617 "official"] language for Moodle is actually the Australian English (''hey mate!''), which is 100% the same as UK English. The default language on a new installation of Moodle, unless you change it, will be this version of English, denoted by the language code "en".

=== What do codes like "en" and "en_us" or "es" and "es_mx" and "es_ve" mean?? ===

These are the language codes for each language. There is a standard for these, see [https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO language code list].

The second part, "_us" or "_mx" and "_ve" for example, represent localisations of the main language for a particular country or dialect. Typically these will include variant spellings and other preferred local terminology and phrasing. So "es_mx" has spellings and idioms (and a very important [[Decimal separator]]) used in Mexican Spanish which are distinct from international Spanish. The es_ve has small differences from the international Spanish that are of significance to Moodle users in Venezuela.

"en_us" is the English - United States language pack; "en" is Australian English, which is practically the same as British English.

=== I found a mistake or typo in a language pack. Or my language is only partial, much of it is still English. What do I do? ===

Language packs have maintainers and Moodle has its own language translation toolkit, known as AMOS. Other than some core languages maintained by Moodle HQ, most languages are maintained by volunteer maintainers.

See the [https://docs.moodle.org/dev/Translation_FAQ Translation FAQ page] for how to report issues and [https://lang.moodle.org/mod/page/view.php?id=9 the AMOS for newcomers page] for more information.

== Default Language ==

=== Where can I set the default language for the site? ===

''Site Administration > Language > [[Language settings]]''

Note you can only choose to set as default a Language pack that is already installed. If the language you want is not on the list, you will need to install the language pack first. See [[Language packs]].

=== When I change to a new default language, users still have the old language. ===

Correct. When you change to a new site default language, this does not update the language setting in the profile for already existing users. It only sets a new default for new user accounts you create from now on.

To do updates for already existing users, you can:

* Tell users how to change it themselves in their user profiles by setting their Preferences > Preferred language
* Use the [[Upload users]] tool to do a mass update from a csv file changing the lang field
* If you have access to the database, you can change this with a simple query. See [[ad-hoc contributed reports#List of users with language|here for an example]] of how to do this.

=== When I log in, the language switches to English. Why? ===

* For logged-in users, the language is set to the one they have set as their preferred language (Preferences > User account > Preferred language).
* For logged-out visitors (before they log in) the situation depends on whether the language auto-detection is enabled. They can either get the language their browser claims to be the requested one, or the site default language.

=== I've set a default site language, but the Moodle calendar is in English. Why? ===

* If your Moodle calendar is not translated, then the string 'locale' (for *nix and Mac servers) or the string 'localewin' (for Windows servers) in the 'langconfig.php' file is wrong (or your server is not configured to support the language).
* There are quite a few languages that are not supported by Windows servers and the localewin server can not be set. In that case, you have to run your Moodle on a *nix server to make the translation of your Moodle calendar work.
* Mac OSs have very poor locale support.
* See [[:dev:Translation langconfig]] for details.

Actually, the one and only place where Moodle requires some locales to be installed on the machine is when handling date translation (according to [https://tracker.moodle.org/browse/MDL-31622 this information]).

=== How can I disable (hide) the language dropdown menu on the site front page? ===

Go to ''Site administration > Language > Language settings'' and un-tick the 'Display language menu' checkbox.

Because it is a customisation, Moodle will not erase the xx_local language files in Moodledata with an upgrade. Moodle will upgrade any language folders it finds in the moodle/lang folder.

==Warning message: Your server does not seem to fully support the following languages==
When you install or update a language pack, your server might display the following warning:
Your server does not seem to fully support the following languages:
followed by a list of non-supported languages and the text:
Instead, the global locale (en_AU.UTF-8) will be used to format certain strings such as dates and numbers.
[[File:Your_server_does_not_seem_to_fully_support.png|400px]]

* This is caused by either:
** a problem with the locale (Linux and Mac) or localewin (windows) setting in langconfig.php for your language pack (you can contact your language pack maintainer listed in the [https://lang.moodle.org/local/amos/credits.php translation credits])
** or the configuration of your server.
* If you have a Linux server (or a [[MoodleBox]]), see the documentation about [https://docs.moodle.org/dev/Table_of_locales installing additional locales].
* If you have a Windows or a Mac Moodle server that lacks the proper locales, we can not help you :(

* See the [https://docs.moodle.org/dev/Translation_langconfig developer's documentation]

== Language Customisation and Multi-language ==

=== How can I change a word or phrase used in Moodle? ===

In ''Administration > Site Administration > Language > Language customisation''.

See [[Language customisation]] for details.

=== How can I find where a language string is located? ===

See the section 'Finding the component and string identifier' in [[Language customisation]].

===Why are my changes not saved in my MoodleCloud site?===
Unfortunately customising language strings is not supported in MoodleCloud. (The same string cache is used for all sites and is read-only.)

=== Why are my changes not saved if I edit a language pack with the Moodle language pack editor? ===

This could be caused by the caching on the server. Language strings are cached into server memory for performance reasons and when you save changes, they may not be immediately picked up. First, refresh your own browser cache to refresh the pages from the site. Then if the strings are still not there, an administrator can purge the cache of the server.

Another possibility is editing one language pack but testing with another. For more possibilities, see the discussion [https://moodle.org/mod/forum/discuss.php?d=429283 Dashboard "Timeline Block" Strings].

===How can I provide course content in more than one language?===

Labels, web pages, activity descriptions etc. may be provided in more than one language using the [[Multi language content|Multi language content filter]].

Another option is to create activities in different languages and restrict access to them using the [https://moodle.org/plugins/availability_language Restriction by language plugin].

See the discussion [https://moodle.org/mod/forum/discuss.php?d=383302 Multiple Languages] for further options.

===How can I provide course headings in more than one language?===

Set the multi language content filter to apply to content AND headings in ''Site administration > Plugins > Filters > Manage filters''.

===Are there any short cuts for editing a language?===
Yes, but be careful. You can make use of the customise language process. Basically copy the php files that contain the strings you want to change to the moodledata/lang/local folder. For example, copy the /lang/en/moodle.php file to someplace. Edit the file with a search and replace with whole word and case sensitive turned on, change Teacher to Instructor and Teachers to Instructors, do the same for teacher and teachers. Now copy that saved copy of the moodle.php file to the moodledata/lang/en_local folder. Be careful not to change the String name.

===Is it possible to customise language strings per theme?===
Not by default, as when strings are customised, they are customised for the whole site. However, it is possible to make a new language pack based on your main language and apply that pack to the course which has the theme. See this forum post for more information: https://moodle.org/mod/forum/discuss.php?d=220671

===Is it possible to use a translation extension in the browser to display a Moodle site in another language===
Yes, according to [https://moodle.org/mod/forum/discuss.php?d=414236#p1669886 this forum post]:

* For Firefox:
** Install the [https://www.mozilla.org/en-US/exp/firefox/new/ Firefox brower] if not already installed on your computer.
** Open Firefox.
** Go to Firefox [https://addons.mozilla.org/en-US/firefox/ Browser Add-ons].
** Search the [https://addons.mozilla.org/en-US/firefox/addon/traduzir-paginas-web/ Translate Web Pages extension], by Filipe Ps, and add it to Firefox.
** Follow the instructions for this extension.

* For Chrome:
** Install [https://www.google.com/intl/en/chrome/ Google Chrome] if not already installed on your computer.
** Open Chrome.
** From the Google Web Store, install the [https://chrome.google.com/webstore/detail/google-translate/aapbdbdomjkkjkaonfhkkikfgjllcleb?utm_source=chrome-ntp-icon Google Translate extension].
** Turn translation on by following [https://www.howtogeek.com/407924/how-to-turn-translation-on-or-off-in-chrome/ these steps] (from How-To Geek).

===Is it possible to change the logo according to language selected, similar to multi-language content?===
Yes. See [https://moodle.org/mod/forum/discuss.php?d=345919 this forum thread]

===Error writing to database when opening language pack===
If you get the message "Error writing to database" after clicking ''Open language pack for editing'' you probably don't have full Unicode support set up in MySQL or MariaDB. Check [[Environment|the Environment report]] to see if the mysql_full_unicode_support warning appears. If so [[MySQL_full_unicode_support|follow the steps to enable full Unicode support]] in your database.

== Other Language Questions ==

===Will installing several language packs decrease my server performance?===
Installing many (20+) language packs have [https://moodle.org/mod/forum/discuss.php?d=241098 almost 0 impact] on Moodle performance. A copy of the language packs installed are stored in your site's local /mooodledata directory. Also, actively used language strings are cached in memory by your server as well to help performance, so as long as your server has sufficient RAM there will be no impact from having many language packs installed.

=== What is this Pirate version of English doing on my site? ===

It has become something of a custom in the Moodle community over the years to observe [https://en.wikipedia.org/wiki/International_Talk_Like_a_Pirate_Day 'Talk Like a Pirate Day'] (September 19) by temporarily changing the language of a site to allow the English - Pirate (en_ar) language pack. See the discussion [https://moodle.org/mod/forum/discuss.php?d=132888 here] for more.

===Lang pack download failed with 'HTTP response code: HTTP/1.1 404 Not Found' after new release ===

After we branch for a new release, Moodle will try and download the new version of lang packs, however for a while development is on-sync and no new language string differences will be introduced between the two branches. During this period, AMOS is not branched and so Moodle will fail to download new language packs.

This is expected and it will be resolved once AMOS is opened up for new changes in the new version. See MDL-34028 for example.

===Why do the characters for my language (not English) show up as hollow squares ?===

[[File:Language_pack_name_not_displayed.png|400px]]

This problem may be caused by a missing/wrong character set or using a font that does not support the character map needed (see [https://moodle.org/mod/forum/discuss.php?d=327521 this forum thead]).

[[File:Language pack name is displayed.png|400px]]

===Are there statistics for language packs downloads?===
Yes. There are download stats for the past 60 days at [https://download.moodle.org/local/downloadmoodleorg/stats.php Moodle downloads stats]. See under Languages a long list of the different packs that have been downloaded:
[[File:Language packs downloads stats.png]]

===Is it possible to streamline the translation of a Moodle course?===
Kind of... See [https://docs.moodle.org/dev/Translation#Translating_a_Moodle_course Translating a Moodle course] in the developer's documentation.

===Can I disable google page translation on my Moodle site?===
Yes, according to [https://moodle.org/mod/forum/discuss.php?d=419424#p1690452 this post]:
The general answer is to add translate="no" to the html tag of your page, but that requires a code change.
So the Moodle html-page starts with (source https://stackoverflow.com/questions/12238396/how-to-disable-google-translate-from-html-in-chrome)
There are more options in the source discussion that are finer to control.
In moodle/admin/settings.php?section=additionalhtml, you can add in the section
<meta name="google" content="notranslate" />
and that should stop Google chrome to translate...
===Can I add another language key to my Windows PC?===
Yes. If you have an English keyboard in your PC, but you want to write Spanish words like "Hasta mañana" and you need to type the 'ñ' letter, see [https://support.microsoft.com/en-us/windows/manage-the-input-and-display-language-settings-in-windows-10-12a10cb4-8626-9b77-0ccb-5013e0c7c7a2 this link].

===Can I get Closed Captions in languages other than English for Moodle HQ videos in YouTube?===
'''Note: In September 2020, YouTube disabled community contributed subtitles.'''

For the Moodle HQ videos on Moodle 4.0 available in https://www.youtube.com/playlist?list=PLxcO_MFWQBDcI0BezfCOW8QRfJw6FblRn the user can choose to have automatically generated closed captions being automatically translated to a user language different from English.

The user watching a YouTube video must choose the cog symbol, choose Autotranslate and choose the target language. Obviously the CC icon must be activated for the auto-translated closed captions to be shown in these YouTube videos.
[[File:1280px-CC_autotranslated.png]]

== See also ==

Forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=131927#p604462 Edited Strings Not Visible]
* [https://moodle.org/mod/forum/discuss.php?d=316623#unread Months names in Arabic language pack]
* [https://moodle.org/mod/forum/discuss.php?d=395788#p1595968 Multilingual moodle]

* MDL-57867 - Email notification language strings lose line breaks when customised bug

==Any further questions?==

Please post in the [http://moodle.org/mod/forum/view.php?f=26 Languages forum] on moodle.org.

[[Category:FAQ]]

[[fr:FAQ de langue]]
[[de:Sprache FAQ]]
[[es:Idioma FAQ]]

NTLM authentication

2022-11-02T11:09:46Z

Leonstr: /* Using the NTLM part of Samba for Apache on Linux */ Change <code> to <pre>

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

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

==Assumptions==

#You are running MS [[Active Directory]] for Authentication.
#The Server hosting your website is a member of the Active Directory Domain that your users are also members of.
#You are able to define people inside your Network (and authenticated to the Domain) from an IP range of computers.
#You are familiar with or have read the LDAP authentication documentation.
#The Active Directory domain credentials of your users are returned as '''DOMAINNAME\username''' from your authentication service. If you are using the Winbind service from the Samba project, this can be untrue, depending on your Winbind configuration settings. If you are using Moodle 2.4 or later, you can specify the format of the domain credentials (see below). If you are using an older version and you can not modify your settings to satisfy this last assumption, then you will need to remove or comment out the line that reads:
$username = substr(strrchr($username, '\\'), 1); //strip domain info
and add the relevant lines of code to extract the username part from the domain user credentials and store it in $username.

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

==Installation==

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

*Enable NTLM SSO
*Set the IP/Subnet mask for the clients (see below)
*(Optionally) Set the "Remote username format" for your domain user credentials format (see below)
*On IIS: turn on Windows Authentication
*On Apache - use one of the 4 methods outlined below
*On the client pc's, you might need to set the moodle server ip/moodle url as being in "local intranet" (for example, in Internet Explorer: tools -> options -> security -> local intranet)

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

Thus it is needed to set the IP subnet.

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

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

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

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

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

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

====Using the NTLM part of Samba for Apache on Linux====
* If using Ubuntu 12.04 or higher you can install this using:

$ sudo apt-get install php5-ldap libapache2-mod-auth-ntlm-winbind winbind smbfs smbclient samba
$ sudo a2enmod auth_ntlm_winbind
$ sudo /etc/init.d/apache2 restart

Note: On Ubuntu 14.04 smbfs has been replaced with '''cifs-utils'''

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

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

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

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

: and executing the command (as root):

# net join DOMAINNAME -U Administrator

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

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

# net join DOMAINNAME -S DCSERVER -U Administrator

: where DCSERVER is the Domain Controller server

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

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

$ wbinfo -u

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

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

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

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

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

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

# adduser www-data winbindd_priv

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

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

* Couple of gotchas - in Fedora Core (and also in Redhat/Centos), keep alive is turned OFF by default in the httpd.conf - see this bug for further info: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=188138
simply change the line to that was:
KeepAlive Off
to:
KeepAlive On
and restart apache (/etc/init.d/http restart)
* Here are some notes from people who have the samba winbind option working
::-- I made it work using Ubuntu 7.04. That's what I've used to update the documentation. [[User:Iñaki Arenaza|Iñaki Arenaza]] 10:43, 30 September 2007 (CDT)
::-- I have this working on Ubuntu 8.04 LTS in an RM CC4 Active Directory Domain. [[User:munk3h|Ian]] 16:31 15 December 2009 (GMT)
::-- Running on Ubuntu 10.04 Lucid, Apache2 got this running in no time flat with AD v6. Worth noting that if Using Iñaki Arenaza's LDAP Clone plugin, you will need to add another copy of the Directory tag in <tt>apache2.conf</tt> pointing at the new ldap plugin. --[[User:Christopher O'Kelly|Christopher O'Kelly]] 10:09, 16 April 2012 (WST)
::-- On Ubuntu 14.04 I had to do the following to get NTLM auth working as I was getting the error "ntlm_auth reports Broken Helper: BH NT_STATUS_UNSUCCESSFUL NT_STATUS_UNSUCCESSFUL" in the Apache error logs (from [https://bugs.launchpad.net/ubuntu/+source/apache-mod-auth-ntlm-winbind/+bug/1304953 Launchpad]) [[User:ngmares|ngmares]]:

usermod -a -G winbindd_priv www-data
chgrp winbindd_priv /var/lib/samba/winbindd_privileged
ln -s /var/lib/samba/winbindd_privileged/pipe /var/run/samba/winbindd_privileged/pipe

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

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

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

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

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

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

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

If you are using an x64 version of Apache mod_auth_sspi x64 versions are available from https://www.apachehaus.net/modules/mod_auth_sspi/

These files '''do not''' work with Apache versions 2.4.x.

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

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

* Choose one of the two methods below

: '''Method 1''': This method is recommended for servers that will host a single Moodle instance. Configure NTLM from the main configuration file, add the following to httpd.conf (substitute "C:\moodle" with the path to your Moodle installation e.g. "C:\my-moodle"
<Directory "C:\moodle\auth\ldap">
<Files ntlmsso_magic.php>
AuthName "Moodle at My College"
AuthType SSPI
SSPIAuth On
SSPIOfferBasic Off
SSPIAuthoritative On
SSPIDomain <YOUR AD DOMAIN>
require valid-user
</Files>
</Directory>

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

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

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

Lastly for Internet Explorer 7 onwards you must also replace this line in your httpd-ssl.conf file:

BrowserMatch ".*MSIE.*" \

with

BrowserMatch ".*MSIE [2-5]\..*" \

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Configuring Domain user credentials format==
If you are using Moodle 2.4 and later there is a new setting that lets you configure the format of the domain user credentials, instead of using the old fixed format. The setting is called "Remote username format". If you leave this setting empty, the default '''DOMAINNAME\username''' format will be used. You can use the optional '''%domain%''' placeholder to specify where the domain name appears, and the mandatory '''%username%''' placeholder to specify where the username appears.

Some widely used formats are:
* '''%domain%\%username%''' : MS Windows default, contains the domain name, followed by a backlash character, followed by the username.
* '''%username%@%domain%''' : This is the same format used by Kerberos (domain name followed by an at sign, followed by the username).
* '''%domain%/%username%''' : Some people configure Samba+Winbind to use this format.
* '''%domain%+%username%''' : Some people configure Samba+Winbind to use this other format.
* '''%username%''' : Only contains the username, with no domain part.

==Notes/Tips==

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

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

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

autoconf apache2-threaded-dev debian-builder

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

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

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

sudo make install

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

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

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

[[Category:Contributed code]]

[[fr:Authentification NTLM]]

Guest access

2022-10-02T09:44:32Z

Leonstr: Punctuation

{{Enrolment}}
The Guest access facility allows users with the [[Guest_role |Guest role]] to view the contents of a course. This might be used, for example, if a Moodle site serves as a website where certain courses contain publicly available information, or else with a commercial Moodle site where courses with guest access can offers a "taster" of the kind of courses which may be purchased. (Note that the guest cannot participate in any activities; they can only view content.)

==Course settings for guest access==

{{MediaPlayer | url = https://youtu.be/LSVLLu7GzHE | desc = How to allow guests into courses}}
# From Course navigation, click 'Participants', and then from the dropdown, click 'Enrolment method> Guest access'. With other themes, click ''Administration > Course administration > Users > Enrolment methods'' and then Guest access.
#Enable guest access by clicking on the "eye" icon or by choosing it in the 'Add method' dropdown menu.
# If you wish to set a password, then click the configure icon and type in your password here.

==Admin settings for guest access==

{{MediaPlayer | url = https://youtu.be/_xGrJ9-aqIc | desc = How to allow guests onto your Moodle site}}

*In ''Administration > Site administration > Plugins > Enrolments > Manage enrol plugins'', ensure Guest access is enabled (has its eye open.) This enables Guest access.
* In ''Administration > Site administration > Plugins > Authentication > Manage authentication'' set the Guest login button to Show if you want the button on the Front page.
* Also Guest accounts can be logged - check the ''Administration > Site administration > Plugins > Logging > Log guest access'' setting.
* A site policy for guests may be set in ''Site administration > Security > Site policies''. Guests then have to agree to the site policy before accessing a course with guest access.

===Default settings for guest access===
*Clicking on ''Administration > Site administration > Plugins > Enrolments > Guest access'' brings up the screen where admin can set defaults for guest access in courses.
**Clicking the 'Advanced' button next to 'Allow guest access' will hide this setting in a course and will instead display a 'Show more' link to click on to access the setting.
** Guest access can be turned on by default in all new courses and you can also:
**require each course with guest access to have a password for guests. (Note: this can confuse teachers who are not aware of the requirement.)
**use or ignore your Moodle's standard password policy for guest access passwords
**offer if needed the first letter of the password as a hint.

===Auto-login guests===
*In ''Administration > Site administration > Users > Permissions > User policies'', you can tick the box so that visitors are automatically logged in as guests when accessing a course with guest access (i.e. they don't have to click the "login as guest button").
*In ''Administration > Site administration > Plugins > Authentication > Manage Authentication'', you must have "Guest login button" set to "Show".
*In ''Administration > Site administration > Security > Site policies'' you can check "Open to Google" setting so that the Google search robot will be allowed to enter your site as a Guest. In addition, people coming in to your site via a Google search will automatically be logged in as a Guest.

==See also==

* [[Guest role]]
* [https://moodle.org/mod/forum/discuss.php?d=347107#p1400235 Re: Guest access to course sections!] forum post

[[de:Gastzugang zum Kurs]]

[[es:Acceso de invitados]]

HTTP security

2022-07-05T16:06:34Z

Leonstr: Changed <code php> to indented <pre>

{{Security}}
*In Moodle 3.4 onwards, the setting 'Use HTTPS for logins' (loginhttps) has been removed.
* There is a [[HTTPS conversion tool]] for converting embedded content to HTTPS.

==Secure cookies only==

It is recommended to use secure cookies only when serving over [https://en.wikipedia.org/wiki/Transport_Layer_Security SSL]. When not serving over SSL, the setting is ignored. In Moodle 3.1.2 onwards, the 'Secure cookies only' default setting is on.

==cURL blocked hosts list==

This allows you to block Moodle's cURL implementation from accessing the specified hosts, wherever it is used to fetch content (such as by the URL downloader in the file picker). Generally it is recommended that as a minimum this is configured to prevent access to any internal network resources. The following is an example list of hosts which can be configured, which prevents access to various versions of "localhost", as well as an address commonly used by AWS and some other cloud providers to provide meta data about the server instance (169.254.169.254):

127.0.0.1
192.168.0.0/16
10.0.0.0/8
172.16.0.0/12
0.0.0.0
localhost
169.254.169.254
0000::1

In future, some logical default values such as those above will be configured automatically for new Moodle sites. See MDL-56873 for more details.

'''Note:''' In addition to configuring this at the application level via this setting, it is also recommended that sufficient firewall/network security measures are in place, including restricting access to internal network endpoints to those users/services that require them.

==cURL allowed ports list==

This allows you to restrict Moodle's cURL implementation to only access the specified list of port numbers, wherever it is used to fetch content (such as by the URL downloader in the file picker). Generally it is recommended that this is configured to only allow standard web ports, as follows:

80
443

In future, some logical default values such as those above will be configured automatically for new Moodle sites. See MDL-56873 for more details.

'''Note:''' In addition to configuring this at the application level via this setting, it is also recommended that sufficient firewall/network security measures are in place, including restricting access to open ports on the internal network to those users/services that require them.

==See also==

* MDL-55662 for removing the secure cookies only setting

[[Category:Site administration]]

[[de:HTTP-Sicherheit]]
[[es:Seguridad HTTP]]

LDAP authentication

2022-06-10T17:50:21Z

Leonstr: /* User lookup settings */ Spelling

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

==Basic Scenario==
The simple and straightforward approach for most installations.

===Assumptions===
Moodle supports several types of LDAP servers which have different directory structures, special configuration settings, etc. Even if using the same LDAP server type (e.g., MS Active Directory), each site could use a completely different directory structure to hold its user accounts, groups, etc. In order to be able to show example configuration settings in the sections below, we are going to assume a '''hypothetical''' Moodle site and LDAP server with the characteristics listed below.

'''IMPORTANT NOTICE''': be sure to check '''''your''''' Moodle site and LDAP server details (including its directory structure,) and adjust the settings to reflect your own setup.

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

===Enabling LDAP authentication===

An administrator can enable LDAP authentication as follows:

# Go to ''Site administration > Plugins > Authentication > Manage authentication'' and click the eye icon opposite LDAP Server. When enabled, it will no longer be greyed out.
# Click the settings link, configure as required (see information below), then click the 'Save changes' button.

[[Image:LDAPserversettings.png|center]]

Now, you just have to fill in the values. Let's go step by step.

====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:
* '''Novell Edirectory''' if your LDAP server is running Novell's eDdirectory.
* '''posixAccount (rfc2307)''' if your LDAP server is running a RFC-2307 compatible LDAP server (choose this is your server is running OpenLDAP, including Mac OS X server).
* '''posixAccount (rfc2307bis)''' if your LDAP server is running a RFC-2307bis compatible LDAP server.
* '''sambaSamAccount (v.3.0.7)''' if your LDAP server is running with SAMBA's 3.x LDAP schema extension and you want to use it.
* '''MS ActiveDirectory''' if your LDAP server is running Microsoft's Active Directory (MS-AD)
|-
| Contexts
| The DN of the context (container) where all of your Moodle users are found. Type '''ou=moodleusers,dc=my,dc=organization,dc=domain''' here.

On a Mac OS X Server, this is usually '''cn=users,dc=my,dc=organization,dc=domain'''.
|-
| Search subcontexts
| If you have any sub organizational units (subcontexts) hanging from '''ou=moodleusers,dc=my,dc=organization,dc=domain''' and you want Moodle to search there too, set this to '''yes'''. Otherwise, set this to '''no'''.
|-
| Dereference aliases
| Sometimes your LDAP server will tell you that the real value you are searching for is in fact in another part of the LDAP tree (this is called an alias). If you want Moodle to 'dereference' the alias and fetch the real value from the original location, set this to '''yes'''. If you don't want Moodle to dereference it, set this to '''no'''. If you are using MS-AD, set this to '''no'''.
|-
| User attribute
| The attribute used to name/search users in your LDAP tree. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in</u>.

By the way, it's usually '''cn''' (Novell eDirectory and MS-AD) or '''uid''' (RFC-2037, RFC-2037bis and SAMBA 3.x LDAP extension), but if you are using MS-AD you could (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. <u>So unless you need something special, you don't need to fill this in.</u>

By the way, the usual values are '''member''' and '''memberUid'''.
|-
| Member attribute uses dn
| Whether the member attribute contains distinguished names (Yes) or not (No). This must be set to Yes for Active Directory.
|-
| Object class
| The type of LDAP object used to search for users. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
* If you leave it blank, the 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 Novell 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
|}

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

<u>As you don't want your users to change their passwords in their first login, leave this set to ''No''</u>
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its own standard password change page, everytime users want to change their passwords.
* Setting this to ''No'' makes Moodle use 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 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.

<u>So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.</u>
|-
| Expiration warning
| This value sets how many days in advance of password expiration the user is warned that her password is about to expire.
|-
| Expiration attribute.
| The LDAP user attribute used to check password expiration. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Grace logins
| This setting is specific to Novell eDirectory. If set to ''Yes'', enable LDAP gracelogin support. After password has expired the user can login until gracelogin count is 0.

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

<u>So you don't need to fill this in.</u>
|}

====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 ''Site administration > Plugins > Authentication > Manage authentication''. Otherwise the new users won't be able to self-create new accounts.

Novell eDirectory and MS-AD can create users externally. 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.
|}

====Assign system roles====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| System role mapping
| This section lists all roles that have can be assigned in the System context - by default this will be "Manager context" and "Course creator context", but can be customisable in the [[Creating custom roles|role definitions]].

To assign LDAP users to any of the roles, specify the DN containing all users who should be granted that role at the system level.

Thie DN 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.

This section replaces the "Course creator" section found in Moodle 3.3. The upgrade process should migrate any DN specified to the new approach.

|}

====User account synchronisation====
{| 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.
|}

====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).
|}

====Data Mapping====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| First name
| The name of the attribute that holds the first name of your users in your LDAP server. This is usually '''givenName''' or '''displayName'''

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

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

<u>This setting is optional</u>
|-
| City/town
| The name of the attribute that holds the city/town of your users in your LDAP server. This is usually '''l''' (lowercase L) or '''localityName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Country
| The name of the attribute that holds the country of your users in your LDAP server. This is usually '''c''' or '''countryName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Language
| '''preferredLanguage'''

<u>This setting is optional</u>
|-
| Description
| '''description'''

<u>This setting is optional</u>
|-
| Webpage
| <u>This setting is optional</u>
|-
| ID Number
|

<u>This setting is optional</u>
|-
| Institution
|

<u>This setting is optional</u>
|-
| Department
| The name of the attribute that holds the department name of your users in your LDAP server. This is usually '''departmentNumber''' (for posixAccount and maybe eDirectory) or '''department''' (for MS-AD).

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

<u>This setting is optional</u>
|-
| Phone 2
| The name of the attribute that holds an additional telephone number of your users in your LDAP server. This can be '''homePhone''', '''mobile''', '''pager''', '''facsimileTelephoneNumber''' or even others.

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

<u>This setting is optional</u>
|}

=====Custom User profile fields=====

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

==Enabling the LDAP users sync job==

The LDAP users sync job (''\auth_ldap\task\sync_task'') [[Scheduled tasks|scheduled task]] (new in Moodle 3.0; previously there was a CLI script, see MDL-51824 for more info) is responsible for creating and updating user information, and suspending and deleting LDAP accounts.

After enabling LDAP server authentication, an administrator needs to enable and configure the LDAP users sync job as follows:

# Go to ''Site administration > Server > Scheduled tasks'' and click the gear icon opposite LDAP users sync job.
# Select the desired frequency of running and enable the task by un-ticking the disabled checkbox.
{{Warning|It is important to make sure that all LDAP settings are working properly before enabling the LDAP users sync job (as well as backing up your database and moodledata folders), since incorrect LDAP configuration can result in 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 than Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions in http://support.microsoft.com/kb/315071 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.

==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] forum discussion

===Using a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more than 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 always 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.

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

==Any questions?==

Please post in the [http://moodle.org/mod/forum/view.php?id=42 Authentication forum] on moodle.org.

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

Forum discussions:
* [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

2022-06-10T17:47:45Z

Leonstr: /* User lookup settings */ Spelling

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

==Basic Scenario==
The simple and straightforward approach for most installations.

===Assumptions===
Moodle supports several types of LDAP servers which have different directory structures, special configuration settings, etc. Even if using the same LDAP server type (e.g., MS Active Directory), each site could use a completely different directory structure to hold its user accounts, groups, etc. In order to be able to show example configuration settings in the sections below, we are going to assume a '''hypothetical''' Moodle site and LDAP server with the characteristics listed below.

'''IMPORTANT NOTICE''': be sure to check '''''your''''' Moodle site and LDAP server details (including its directory structure,) and adjust the settings to reflect your own setup.

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

===Enabling LDAP authentication===

An administrator can enable LDAP authentication as follows:

# Go to ''Site administration > Plugins > Authentication > Manage authentication'' and click the eye icon opposite LDAP Server. When enabled, it will no longer be greyed out.
# Click the settings link, configure as required (see information below), then click the 'Save changes' button.

[[Image:LDAPserversettings.png|center]]

Now, you just have to fill in the values. Let's go step by step.

====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:
* '''Novell Edirectory''' if your LDAP server is running Novell's eDdirectory.
* '''posixAccount (rfc2307)''' if your LDAP server is running a RFC-2307 compatible LDAP server (choose this is your server is running OpenLDAP, including Mac OS X server).
* '''posixAccount (rfc2307bis)''' if your LDAP server is running a RFC-2307bis compatible LDAP server.
* '''sambaSamAccount (v.3.0.7)''' if your LDAP server is running with SAMBA's 3.x LDAP schema extension and you want to use it.
* '''MS ActiveDirectory''' if your LDAP server is running Microsoft's Active Directory (MS-AD)
|-
| Contexts
| The DN of the context (container) where all of your Moodle users are found. Type '''ou=moodleusers,dc=my,dc=organization,dc=domain''' here.

On a Mac OS X Server, this is usually '''cn=users,dc=my,dc=organization,dc=domain'''.
|-
| Search subcontexts
| If you have any sub organizational units (subcontexts) hanging from '''ou=moodleusers,dc=my,dc=organization,dc=domain''' and you want Moodle to search there too, set this to '''yes'''. Otherwise, set this to '''no'''.
|-
| Dereference aliases
| Sometimes your LDAP server will tell you that the real value you are searching for is in fact in another part of the LDAP tree (this is called an alias). If you want Moodle to 'dereference' the alias and fetch the real value from the original location, set this to '''yes'''. If you don't want Moodle to dereference it, set this to '''no'''. If you are using MS-AD, set this to '''no'''.
|-
| User attribute
| The attribute used to name/search users in your LDAP tree. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in</u>.

By the way, it's usually '''cn''' (Novell eDirectory and MS-AD) or '''uid''' (RFC-2037, RFC-2037bis and SAMBA 3.x LDAP extension), but if you are using MS-AD you could (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. <u>So unless you need something special, you don't need to fill this in.</u>

By the way, the usual values are '''member''' and '''memberUid'''.
|-
| Member attribute uses dn
| Whether the member attribute contains distinguished names (Yes) or not (No). This must be set to Yes for Active Directory.
|-
| Object class
| The type of LDAP object used to search for users. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
* If you leave it blank, the 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
|}

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

<u>As you don't want your users to change their passwords in their first login, leave this set to ''No''</u>
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its own standard password change page, everytime users want to change their passwords.
* Setting this to ''No'' makes Moodle use 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 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.

<u>So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.</u>
|-
| Expiration warning
| This value sets how many days in advance of password expiration the user is warned that her password is about to expire.
|-
| Expiration attribute.
| The LDAP user attribute used to check password expiration. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Grace logins
| This setting is specific to Novell eDirectory. If set to ''Yes'', enable LDAP gracelogin support. After password has expired the user can login until gracelogin count is 0.

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

<u>So you don't need to fill this in.</u>
|}

====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 ''Site administration > Plugins > Authentication > Manage authentication''. Otherwise the new users won't be able to self-create new accounts.

Novell eDirectory and MS-AD can create users externally. 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.
|}

====Assign system roles====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| System role mapping
| This section lists all roles that have can be assigned in the System context - by default this will be "Manager context" and "Course creator context", but can be customisable in the [[Creating custom roles|role definitions]].

To assign LDAP users to any of the roles, specify the DN containing all users who should be granted that role at the system level.

Thie DN 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.

This section replaces the "Course creator" section found in Moodle 3.3. The upgrade process should migrate any DN specified to the new approach.

|}

====User account synchronisation====
{| 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.
|}

====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).
|}

====Data Mapping====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| First name
| The name of the attribute that holds the first name of your users in your LDAP server. This is usually '''givenName''' or '''displayName'''

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

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

<u>This setting is optional</u>
|-
| City/town
| The name of the attribute that holds the city/town of your users in your LDAP server. This is usually '''l''' (lowercase L) or '''localityName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Country
| The name of the attribute that holds the country of your users in your LDAP server. This is usually '''c''' or '''countryName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Language
| '''preferredLanguage'''

<u>This setting is optional</u>
|-
| Description
| '''description'''

<u>This setting is optional</u>
|-
| Webpage
| <u>This setting is optional</u>
|-
| ID Number
|

<u>This setting is optional</u>
|-
| Institution
|

<u>This setting is optional</u>
|-
| Department
| The name of the attribute that holds the department name of your users in your LDAP server. This is usually '''departmentNumber''' (for posixAccount and maybe eDirectory) or '''department''' (for MS-AD).

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

<u>This setting is optional</u>
|-
| Phone 2
| The name of the attribute that holds an additional telephone number of your users in your LDAP server. This can be '''homePhone''', '''mobile''', '''pager''', '''facsimileTelephoneNumber''' or even others.

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

<u>This setting is optional</u>
|}

=====Custom User profile fields=====

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

==Enabling the LDAP users sync job==

The LDAP users sync job (''\auth_ldap\task\sync_task'') [[Scheduled tasks|scheduled task]] (new in Moodle 3.0; previously there was a CLI script, see MDL-51824 for more info) is responsible for creating and updating user information, and suspending and deleting LDAP accounts.

After enabling LDAP server authentication, an administrator needs to enable and configure the LDAP users sync job as follows:

# Go to ''Site administration > Server > Scheduled tasks'' and click the gear icon opposite LDAP users sync job.
# Select the desired frequency of running and enable the task by un-ticking the disabled checkbox.
{{Warning|It is important to make sure that all LDAP settings are working properly before enabling the LDAP users sync job (as well as backing up your database and moodledata folders), since incorrect LDAP configuration can result in 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 than Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions in http://support.microsoft.com/kb/315071 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.

==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] forum discussion

===Using a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more than 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 always 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.

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

==Any questions?==

Please post in the [http://moodle.org/mod/forum/view.php?id=42 Authentication forum] on moodle.org.

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

Forum discussions:
* [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]]

Activity completion FAQ

2022-05-18T08:59:50Z

Leonstr: /* Can I move the activity completion checkboxes to the left instead of the right? */ Changed <code> to <syntaxhighlight>

{{Activity completion}}
==What happens when completion conditions are unlocked?==

Once you unlock options and then click 'Save changes', all completion information for the activity will be deleted and, if possible, regenerated according to the new settings. See the section 'What happens when you unlock' in [[Activity completion settings]] for further details.
==Can I change the default completion settings for activities in my course?==
Yes. See [[Activity completion settings]] for how to do this.

==Activity completion status does not change==
Check ''Site administration > Server > Scheduled tasks'' and the task Calculate completion data. This should ideally be once a minute.

==Can I move the activity completion checkboxes to the left instead of the right?==
[[File:checkboxleft.png]]

Please see MDL-34729 and MDL-31603

This is a not-fully tested solution, based on adapting Christian Herman's tip from Moodle 2.0 to 2.5 and discussion in https://moodle.org/mod/forum/discuss.php?d=263661
If you are using Clean or More theme, add the following to the Custom CSS box in ''Appearance>Themes>Clean' (or More)

<syntaxhighlight lang="css">/* Completion Checkbox Left of Activity Icon and Align Checkboxes Full Left */
.section .activity .actions { position: relative; }

.path-course-view li.activity span.autocompletion, .path-course-view li.activity form.togglecompletion
{ float: left; margin-left: -15px;}

/* Small Space Between Checkbox & Icon */
.path-course-view .section .activity img.activityicon
{ padding-left: 1em; }</syntaxhighlight>

[[Category:FAQ]]

[[de:Aktivitätsabschluss FAQ]]
[[es:Finalización de actividad FAQ]]
[[fr:FAQ sur l'achèvement des activités]]

Talk:Activity completion report

2022-01-22T17:51:36Z

Leonstr: Added note about the previous key for activity completion status icons

I was looking for a key for the icons in the Activity Completion Report and couldn't find one. So here's a draft based on my understanding of this. [[User:Leon Stringer|Leon Stringer]] ([[User talk:Leon Stringer|talk]]) 12:11, 10 June 2021 (UTC)
{|
!colspan="3" style="text-align:left"|Automatic versus manual completion
|-
|[[File:completion-auto-n.svg|16x16px|Dashed line box]]
|Box with dashed line
|Activity is completed automatically. For example: a quiz with ''Completion tracking'' set to "Show activity as complete when conditions are met".
|-
|[[File:completion-manual-n.svg|16x16px|Solid line box]]
|Box with solid line
|Activity is completed manually by learner. For example: a file with ''Completion tracking'' set to "Students can manually mark the activity as completed".
|-
!colspan="3" style="text-align:left"|Completion status
|-
|[[File:completion-auto-n.svg|16x16px|Dashed line box]] [[File:completion-manual-n.svg|16x16px|Solid line box]]
|Empty box
|Activity not complete.
|-
|[[File:completion-auto-y.svg|16x16px|Dashed line box, blue tick]] [[File:completion-manual-y.svg|16x16px|Solid line box, blue tick]]
|Blue tick
|Activity completed and no passing grade applies. For example: passing grade does not apply to this activity type, or passing grade has not been set as part of the activity's completion criteria.
|-
|[[File:completion-auto-pass.svg|16x16px|Dashed line box, green tick]]
|Green tick
|Completed, activity has passing grade which was achieved.
|-
|[[File:completion-auto-fail.svg|16x16px|Dashed line box, red cross]]
|Red cross
|Activity not completed and completion not possible. For example: all quiz attempts have been used without achieving the passing grade.
|-
!colspan="3" style="text-align:left"|Override completion status
|-
|[[File:completion-auto-y-override.svg|16x16px|Dashed red line box, blue tick]] [[File:completion-manual-y-override.svg|16x16px|Solid red line box, blue tick]] [[File:completion-manual-n-override.svg|16x16px|Solid red line box, empty]]
|Box with red border
|Completion status has been manually set by teacher, manager or site administrator.
|}

For anybody interested (and as a memo to myself) the above list of icons was [https://docs.moodle.org/402/en/index.php?title=Using_Activity_completion&oldid=139704#Activity_completion_icons previously in Using Activity completion] but was removed. [[User:Leon Stringer|Leon Stringer]] ([[User talk:Leon Stringer|talk]]) 17:50, 22 January 2022 (UTC)

Performance settings

2022-01-21T10:09:20Z

Leonstr: /* config.php settings which may affect performance */ Change <code> to <syntaxhighlight>

{{Performance}}
==Performance settings==

Various performance settings can be changed by an administrator in ''Administration > Site administration > Server > Performance''.

The setting "Maximum time limit" lets you restrict the maximum PHP execution time that Moodle will allow without any output being displayed. If you have a front-end server with its own time limit, set this value lower to receive PHP errors in logs.

==Other site administration settings which may affect performance==

* Enable the '''language cache'''.
* Large log files can cause overall performance to degrade over time. If you observe that the site has gradually got slower loading pages in the browser, '''reduce your Log life time''' setting in ''Administration > Site administration > Server > Cleanup''
* Check your filters. Having too many filters active can have serious effects on server load, especially on lower-end systems. The number of active filters has a direct effect on the perceived latency of your site; that is the time taken for each page impression. Check if any of the filters can be disabled. For example, if your site does not need to be able to display mathematical equations you can disable the [[MathJax filter]].

* Enable the '''text cache''' but do not "Filter all strings" unless you have a specific need. If in doubt profile the performance, and see how your changes affect the processing time.
* Check your '''anti-virus''' measures on the server. Although they are useful for preventing security holes being exploited, some "On-Demand" scanners can affect performance by scanning page content (word, ppt files etc).
* Check your '''forum settings'''. To improve performance set forum_trackreadposts = No and forum_usermarksread = Yes (this will impact on the convenience of your users' forum experience). Also consider setting the time of the day when old posts are cleared from the read table (forum_cleanreadtime) to when your site is less busy.
* Don't use database sessions unless you really need them. On-disc sessions tend to be much faster.

===config.php settings which may affect performance===
Increasing the value of CONTEXT_CACHE_MAX_SIZE '''may''' reduce the number of database queries for certain pages. It will also increase memory usage, so be careful.

<syntaxhighlight lang="php">
// Moodle 2.3: Increasing this from the default saved about > 1000 db queries on the course/index.php page for
// a Moodle having 1250 course categories.
// This value is specified in lib/accesslib.php, but it's OK to add a define for it in config.php:
define('CONTEXT_CACHE_MAX_SIZE', 7500);
</syntaxhighlight>

==See also==
* [https://moodle.org/mod/forum/discuss.php?d=225617 setting innodb buffer pool from 100mb to 3gb] resulted in outstanding performance.

[[de:Geschwindigkeitseinstellungen]]
[[es:Configuraciones para desempeño]]
[[fr:Réglages de performance]]

Apache

2022-01-18T18:09:43Z

Leonstr: /* Hiding internal paths */ Removed '#' comment prefixes

{{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, Nginx on Linux, MacOS) 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 function ''slash arguments'' is required for various features in Moodle to work correctly, as described in [[Using slash arguments]].

To turn it on, add this line to your ''httpd.conf'', or to a ''.htaccess'' file in your local directory:

<syntaxhighlight lang="apacheconf">
AcceptPathInfo On
</syntaxhighlight>

''Note:'' When using ".htaccess" in your local Moodle install folder, you may need to include/enable "AllowOverride Directive" in "httpd.conf", first.

''Note:'' Using .htaccess file will cause performance hit on your server!

If you are using Ionos (formerly 1&1) shared webhosting, the above does not work, there is a known bug when using PHP as CGI. The solution is to create a php.ini file in the moodle directory with this content:

<syntaxhighlight lang="ini">
cgi.fix_pathinfo = 0
</syntaxhighlight>

Also Ionos requires that this php.ini be in every directory that a script executes. Use the procedure below to link a php.ini in every subdirectory back to your original php.ini file.

<syntaxhighlight lang="bash">
cd your_moodle_directory
find -type d -exec ln -s $PWD/php.ini {}/php.ini \;
</syntaxhighlight>

Source: [https://www.ionos.com/help/hosting/using-php-for-web-projects/applying-php-settings-to-all-subdirectories/ Ionos php.ini Help]

This may affect other shared hosting providers as well.

== Handling 40x errors ==

This enables missing files to be themed by Moodle

<pre>
ErrorDocument 404 /error/index.php

# This sends any 403 from apache through to the same page, but also
# overrides the http status with 404 instead for better security.
ErrorDocument 403 /error/index.php?code=404
</pre>

== Hiding internal paths ==

<pre>
RewriteEngine On

RewriteRule "(\/vendor\/)" - [F]
RewriteRule "(\/node_modules\/)" - [F]
RewriteRule "(^|/)\.(?!well-known\/)" - [F]
RewriteRule "(composer\.json)" - [F]
RewriteRule "(\.lock)" - [F]
RewriteRule "(\/environment.xml)" - [F]
Options -Indexes
RewriteRule "(\/install.xml)" - [F]
RewriteRule "(\/README)" - [F]
RewriteRule "(\/readme)" - [F]
RewriteRule "(\/moodle_readme)" - [F]
RewriteRule "(\/upgrade\.txt)" - [F]
RewriteRule "(phpunit\.xml\.dist)" - [F]
RewriteRule "(\/tests\/behat\/)" - [F]
RewriteRule "(\/fixtures\/)" - [F]
</pre>

==SSL==

Moodle has an option to enable HTTPS for the whole site or for just the login pages; either option requires that your web server is configured for SSL.

* Whole site HTTPS is enabled by changing http://<url> to https:// <url> in your config.php 'wwwroot' parameter.
* Login only HTTPS is enabled by setting the 'loginhttps' parameter, where the wwwroot schema should remain as http://

NOTE: Login only https was deprecated and removed from Moodle 3.4: https://tracker.moodle.org/browse/MDL-42834

Login only https is available in Moodle 3.3 and earlier in the admin interface via Administration>Security>HTTP Security and checking the button. (Note the warning and see ssl section below)

Prior to Moodle 2.3 It was not advised to run the whole site over HTTPS due to legacy restrictions with client-side caching. This is no longer the case assuming client browsers support the 'Cache-Control: public' method, which all supported browsers for this version of Moodle do.

To use HTTPS you will need to obtain an SSL certificate, you have two options:

* Generate a self-signed certificate. This is fine on (say) an Intranet but unsuitable for the public internet, but users will we warned the certificated is untrusted when used publicly.
* 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.

Debian provides instructions for installing a self-signed certificate [https://wiki.debian.org/Self-Signed_Certificate on their wiki] and includes general information on configuring Apache for SSL.
If you purchase a vendor certificate you will normally receive instructions for installing it.

A basic Apache SSL configuration can be summarised as:

Listen 443
NameVirtualHost *:443
<VirtualHost *:443>
SSLEngine On
SSLCertificateFile /path/to/your/certificate.crt
SSLCertificateKeyFile /path/to/your/certificate.key
...
</VirtualHost>

== Load Balancer Hints (AWS) ==

If you're using an AWS load balancer in front your infrastructure, you can set up some of the configuration above, preventing traffic to go forward. Here is the configuration applied to hide files, with a few considerations due to known limitations:
* 100 total rules per application load balancer
* 5 condition values per rule
* 5 wildcards per rule
* 5 weighted target groups per rule:
<small>
<pre>
[
{
"Conditions": [
{
"Field": "path-pattern",
"Values": [
"*/.*",
"*/upgrade.txt",
"*/db/install.xml",
"*/README.md"
],
"PathPatternConfig": {
"Values": [
"*/.*",
"*/upgrade.txt",
"*/db/install.xml",
"*/README.md"
]
}
}
],
"Actions": [
{
"Type": "fixed-response",
"Order": 1,
"FixedResponseConfig": {
"ContentType": "text/html",
"MessageBody": "<html>\n<head><title>404 Not Found</title></head>\n<body>\n<center><h1>404 Not Found</h1></center>\n<hr>\n</body>\n</html>",
"StatusCode": "404"
}
}
]
},
{
"Conditions": [
{
"Field": "path-pattern",
"Values": [
"*/composer.json",
"*/Gruntfile.js",
"*.lock",
"*/environtment.xml",
"*/readme.txt"
],
"PathPatternConfig": {
"Values": [
"*/composer.json",
"*/Gruntfile.js",
"*.lock",
"*/environtment.xml",
"*/readme.txt"
]
}
}
],
"Actions": [ #### Same as above
...
]
},
{
"Conditions": [
{
"Field": "path-pattern",
"Values": [
"*/fixtures/*",
"*/behat/*",
"*/phpunit.xml"
],
"PathPatternConfig": {
"Values": [
"*/fixtures/*",
"*/behat/*",
"*/phpunit.xml"
]
}
}
],
"Actions": [ #### Same as above
...
]
}
]
</pre></small>

== 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]]
[[es:Apache]]

File:phpMyAdmin3.png

2021-12-24T10:53:32Z

Leonstr: Screenshot from phpMyAdmin of the output from SHOW GLOBAL VARIABLES ... on MySQL 8.0.21.

== Summary ==
Screenshot from phpMyAdmin of the output from SHOW GLOBAL VARIABLES ... on MySQL 8.0.21.

MySQL

2021-12-24T10:51:51Z

Leonstr: /* Configure full UTF-8 support */ Improve wording based on https://moodle.org/mod/forum/discuss.php?d=430261

{{Installing Moodle}}
MySQL is one of the supported databases that underpins a Moodle installation.

== Installing MySQL ==

* If you are running Linux your preference should be to install using your distribution's package manager. This ensures you will get any available updates. However, you can also use apt-get or yum depending on the distribution that you are running.
* There are installers available for most popular operating systems at http://www.mysql.com/downloads/mysql/.
* It is possible and reasonably straightforward to build mysql from source but it is not recommended (the pre-built binaries are supposedly better optimised).
* Make sure you set a password for the 'root' user (see http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html).
* Consider installing and configuring my.cnf (the MySQL settings file) to suit your needs. The default configuration is usually very conservative in respect of memory usage versus performance. Increase the 'max_allowed_packet' setting to at least 4 megabytes.
* If you are going to use Master/Slave replication, you must add binlog_format = 'ROW' into your my.cnf within [mysqld]. Otherwise, Moodle will not be able to write to the database.

=== Configure full UTF-8 support ===

It's recommended that full UTF-8 support is configured in MySQL. If this is not done some character sets – notably emojis – cannot be used. It is possible to do this after installing your site but is much easier and quicker before installation.

Check if this is already configured by running the following statement, e.g. at the '''mysql>''' prompt or in phpMyAdmin:
<pre>SHOW GLOBAL VARIABLES WHERE variable_name IN ('innodb_file_format', 'innodb_large_prefix', 'innodb_file_per_table');</pre>

[[File:phpMyAdmin1.png|alt=innodb_file_format=Barracuda;innodb_file_per_table=ON;innodb_large_prefix=ON]] or [[File:phpMyAdmin2.png|alt=innodb_file_format=(blank);innodb_file_per_table=ON;innodb_large_prefix=(blank)]] or [[File:phpMyAdmin3.png|alt=innodb_file_per_table=ON]]

If the settings you see match any list above then no changes are needed and you can skip to [[#Creating_Moodle_database| Creating Moodle database]].

If your settings do not match any list you will have to edit the MySQL configuration file. On Linux this may be '''/etc/my.cnf''', '''/etc/mysql/my.cnf''', or '''/etc/my.cnf.d/mariadb-server.cnf'''; on Microsoft Windows it may be '''my.ini'''.

* Note: Back up the configuration file before changing it.
* Note: Back up all databases before making this change.
* Note: Other systems with databases on this server may be impacted by this change.

Add the following settings to the configuration file, do not add '''innodb_file_format = Barracuda''' and '''innodb_large_prefix = 1''' if these were blank or missing when you ran '''SHOW GLOBAL VARIABLES''' above:
<pre>[client]
default-character-set = utf8mb4

[mysqld]
innodb_file_format = Barracuda # Remove line if not needed
innodb_file_per_table = 1
innodb_large_prefix = 1 # Remove line if not needed

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
skip-character-set-client-handshake

[mysql]
default-character-set = utf8mb4</pre>

Restart the MySQL server process to apply these settings (for example with MariaDB on Linux: '''systemctl restart mariadb''').

If you have any difficulty applying these settings, see [[MySQL_full_unicode_support]] for further information.

If for some reason you cannot change to the settings described here you can continue to install Moodle but you must select '''utf8''' and '''utf8_unicode_ci''' for the default character set and collation respectively.

== Creating Moodle database ==

These are the steps to create an empty Moodle database. Substitute your own database name, user name and password as appropriate.

The instructions assume that the web server and MySQL server are on the same machine. In this case the 'dbhost' is 'localhost'. If they are on different machines substitute the name of the web server for 'localhost' in the following instructions and the 'dbhost' setting will be the name of the database server.
Databases have a "Character set" and a "Collation". For Moodle, we recommend the Character Set be set to '''utf8mb4''' and the Collation '''utf8mb4_unicode_ci'''. You may get the option to set these values when you create the database. If you are not given a choice, the default options are probably good. An install on an old server may have the wrong settings.

=== Command line ===

* To create a database using the 'mysql' command line client, first log into MySQL
<pre>
$ mysql -u root -p
Enter password:
</pre>
(Enter the password you previously set - or been given - for the MySQL 'root' user). After some pre-amble this should take you to the ''mysql>'' prompt.
* Create a new database (called 'moodle' - substitute your own name if required).
If you have successfully configured the recommended full UTF-8 support as described above run:
<pre>
mysql> CREATE DATABASE moodle DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
</pre>
If you do not have the recommended full UTF-8 support run:
<pre>mysql> CREATE DATABASE moodle DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;</pre>
* Add a user/password with the minimum needed permissions:
<pre>
mysql> CREATE USER moodleuser@localhost IDENTIFIED BY 'yourpassword';
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,CREATE TEMPORARY TABLES,DROP,INDEX,ALTER ON moodle.* TO moodleuser@localhost;
mysql> FLUSH PRIVILEGES;
</pre>
...which creates a user called 'moodleuser' with a password 'yourpassword'. Make sure you invent a strong password and resist the temptation to 'GRANT ALL'.
* Exit from mysql:
<pre>
mysql> quit
</pre>

=== phpMyAdmin ===

[http://www.phpmyadmin.net/ phpMyAdmin] is a web based administration tool for MySQL. If this is available you can use it to create a new database. If you have successfully configured the recommended full UTF-8 support as described above select collation '''utf8mb4_unicode_ci'''. If you do not have the recommended full UTF-8 support select collation '''utf8_unicode_ci'''.

==Which database belongs to which Moodle==
If you have installed several Moodle installations on the same server, there will be several databases in your MySQL server. The names might be quite poor reflections of the content like _mdl1 _mdl2 _mdl3 . So how do I see which database goes with which Moodle installation? You can go in with phpMyAdmin and in the various databases check for the table "mdl_course". There you will easily see the name of that Moodle Installation. In table mdl_config you can see the Moodle version. The main URL for the site is not in the database except where there are absolute links.

== See also ==

* [[MariaDB]]
* [[MySQL full unicode support]]
* [http://www.mysql.com/ The MySQL homepage]
* [http://en.wikipedia.org/wiki/MySQL Wikipedia article about ''MySQL'']
* [http://forums.mysql.com/read.php?24,92131,92131 List of articles on MySQL performance tuning]

[[Category:SQL databases]]

[[ja:MySQL]]
[[de:MySQL]]
[[es:MySQL]]

Upload users

2021-12-16T12:11:14Z

Leonstr: Grammar/missing words

{{Accounts}}
==Uploading users via text file==

There are many options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[roles]] to updating user information in the [[User profile]] to deleting users from the site.

''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the users create their own accounts ([[Self enrolment]]). See [[Authentication]] for more information.

{{MediaPlayer | url = https://youtu.be/blUw-ZbhFqw| desc = How to bulk upload users and add to courses}}

==File formats for upload users file==
The upload users file has fields separated by a comma (or other delimiter) ONLY - no space. The first line contains the valid field names. The rest of the lines (records) contain information about each user.

''Tip:'' Avoid special characters in field information like quotes or other commas. Test a file with only one record before a large upload.

''Tip:'' You can use a spread sheet program to create the file with the required columns and fields. Then save the file as "CSV (comma delimited)". These files can be opened with simple text editors (e.g., [https://notepad-plus-plus.org/ Notepad++]) for verification.

===Valid upload file for testing===

*From Site administration / Users / Upload users, an example text (.csv) file is available. It includes can be downloaded and adapted to your needs.

username,firstname,lastname,email

student1,Student,One,s1@example.com

student2,Student,Two,s2@example.com

student3,Student,Three,s3@example.com

*Additional fields can be added as below. The course and cohort must already have been manually created.

username,firstname,lastname,email,course1,group1,cohort1

student1,Student,One,s1@example.com,math102,groupA,cohortZ

student2,Student,Two,s2@example.com,math102,groupB,cohort Y

student3,Student,Three,s3@example.com,math102,groupA,cohortZ

== User Fields that can be included==

''Tip:'' We strongly recommend that you test a file that contains fields you proposed to use with one user before attempting a file upload for the first time.

===Required fields===

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

===Passwords===

The "password" field is optional if the 'New user password' setting on the upload screen is set to "Create password if needed and send via email" but is required if the setting is "Field required in file".

If included, values should meet the requirements for the site's [[Site policies#Password policy|Password policy]].

To force password change for a particular user, set the password field to '''changeme'''. If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out. The text for the welcome e-mail is in the language settings in ''Site administration > Language > Language customisation'' with a String identifier of 'newusernewpasswordtext'.

===Optional user fields===

Note: Commas within a field must be encoded as &#44 - the script will decode these back to commas.
Tip: For Boolean fields with only two values, use '''0''' for false and '''1'''for true.

To provide values other than the default you can include one or more of these optional user fields:

<pre>institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,maildigest,htmleditor,autosubscribe,interests,theme</pre>

Most of the these are user profile fields or user preference fields that belong to the user profile and are the filled in the user or at manual creation. Some however require specific formats:

See [[Additional name fields]] for more details. Key things to note are:

'''country''' - use the country TWO LETTER CODE, in upper case, e.g. AU,ES,GB,US. These are all UPPER CASE. Using "au" or "es" or "USA" as a country code will result in a database error. If you are having trouble working out the two-letter code for a country, you can consult the list of [https://www.iso.org/obp/ui/#search country names and code elements] available on the ISO Website. A common error is to use UK for United Kingdom; it should be GB.

'''lang''' - use the two letter (or extended four lettter) code as defined in the Moodle language packs, e.g. en, es, en_us, de, in ''Site administration > Language > Language packs''.

'''auth''' - The auth field must be used if the site uses an alternative authentication method, such as LDAP, as otherwise the authentication method will default to manual and users using a different auth method won't be able to log in.
Use the shortname codes defined in Plugins > Authentication for the various types, e.g. manual, nlogin, ldap, cas, mnet, db, none. If you do not include an auth column, then newly created users will be created with the manual account type.

You can set "auth" to "nologin" in your csv file which will mean that then created users cannot login.

'''timezone''' - Should be in the format as found in the Location settings in terms of Zone/Region, e.g. Australia/Sydney, Asia/Kathmandu, Europe/Madrid, etc. The entry is case sensitive so Europe/London will work but europe/london will not.

NOTE: Needed: settings for '''mailformat''','''maildisplay''','''htmleditor''','''autosubscribe'''

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

'''maildisplay''' allows you to set the email display option for a user. The options for this field are 0 = Hide my email address from non-privileged users, 1 = Allow everyone to see my email address and 2 = Allow only other course members to see my email address.

'''theme''' User themes may be added by using 'classic', 'boost' or the name of any other installed theme. The value should be the short name of the theme, e.g. 'boost' not 'Boost', 'fordson' not 'Fordson'.

===Custom profile field names===

These are optional and depend on whether you have created any custom profile fields in your site. The name of the header in file is of the form 'profile_field_xxxxx' where xxxx is the unique shortname of custom user profile field name as you created it.

The field name should match the case of the profile field shortname. So, for instance if the shortname of your custom profile field is all upper case, for example, ''DOB'', then use a header of ''profile_field_DOB'' to match the case, not ''profile_field_dob'', which will produce a "is not a valid field name" error. Likewise, a mixed case shortname such as ''Dob'' should have a header of ''profile_field_Dob''. (The exception to this is if the shortname is all lower case, then any case will work in the field header, which is a historical quirk: but best practice is to match the case and you will avoid errors.)

<pre>profile_field_xxxxx</pre>

'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.

For custom profile fields that are dates, use the ISO standard format YYYY-MM-DD, e.g. 2014-06-19 which will then be properly localized in the interfaced. For example, a field called dohire for date of hire, the fields could be:
<pre>
username,firstname,lastname,email,profile_field_dohire
blumbergh,Bill,Lumbergh,blumbergh@example.com,1990-02-19
pgibbons,Peter,BGibbons,pgibbons@example.com,1996-06-05
tsmykowski,Tom,Smykowski,tsmykowski@example.com,1970-01-01
</pre>

For custom profile fields that are a menu, use the corresponding value in the menu list from field as you defined it. For example: a custom field 'corporatedivision' with one of three values 'Management', 'Development' or 'Training'. Just insert one of those three words (e.g. 'Training') as the value for that field. E.g.

<pre>
username,firstname,lastname,email,profile_field_corporatedivision
blumbergh,Bill,Lumbergh,blumbergh@example.com,Management
pgibbons,Peter,BGibbons,pgibbons@example.com,Development
tsmykowski,Tom,Smykowski,tsmykowski@example.com,Training
</pre>

=== Special user change fields===

Three special fields are used for managing user accounts, '''oldusername''', '''deleted''' and '''suspended'''. [[#Allow_renames|See below for details]].

===Enrolment fields===

You may optionally enrol users in already existing courses using manual enrolment. Only manual enrolment is done this way; if the manual enrolment method is disabled in a course, then no enrol is done.

You use fields in the upload file of this type:

<pre>course1,type1,role1,group1,enroltimestart1,enrolperiod1,enrolstatus1,course2,type2,role2,group2,enroltimestart2,enrolperiod2,enrolstatus2</pre> etc.

Header fields '''must''' have a numeric suffix such that type1,role1,group1,enrolperiod1 and enrolstatus1 all apply to course1 for course'''1''' to course'''n'''. Even if you are just doing one course enrolment, you must still use the number 1 on the heading name, i.e. course1,role1, etc. Do not use the bare headings without numbers, e.g. course,role, etc. as those will generate an error.

'''course#''' is the shortname of the course, if present the user will be enrolled in that course. Do not use the fullname of the course or it will generate an error. This field is the ONLY required field for a successful enrolment. All the others are optional.

'''type#''' sets the role to be used for the enrolment. A value of 1 is default course role, 2 is legacy Teacher role and 3 is legacy Non-editing Teacher.

'''role#''' may be used to specify roles directly, using either role short name or the role id (numeric names of roles are not supported). Usually you will use the role name that is the shortname of the role as defined in Users > Permissions > Define roles, e.g. student, editingteacher. If the role column is left out, the users will be enroled in the course with the default role, which is normally student.

'''group#''' may be used to assign users to groups in course, using name or id (numeric group names are not supported). NOTE: if the group does not already exist, it will be created.

'''enroltimestart#''' may be used to set the enrolment start time, for each course. If not explicitly set here, the enrolment start time is set to be today. To set a date: "2021-02-15" and to set a date and time "2021-02-15 15:30"

'''enrolperiod#''' may be used to set the enrolment duration, in days, for each course. If not explicitly set here, all the users will get the duration as set in the Manual enrolment method of the course (which defaults to 0 meaning unlimited.)

'''enrolstatus#''' is optional as by default all newly enrolled users are set to active. If used a value of 1, it will suspend users in the course and if a user is previously set as inactive / suspended then a value of 0 will unsuspend them and make them active again.

=== Cohort membership assignment===

You can assign users to any already existing Cohort by using only the "username" and the "Cohort ID" with just two fields in the file. Note that this is an exception to the usual case where the firstname, lastname and email address of the user are required.

'''cohort#''' is the form to use and like enrolment in courses, you have to add a number to each header, so cohort1,cohort2, etc.

Internal cohort ID numbers or non-numeric Cohort IDs of existing cohorts must be used; do not use the full name as this is not allowed. (Note that cohort ID is what is usually known elsewhere as the "shortname".)

Here is a sample CSV file:

<pre>
username,cohort1,cohort2
student1,nursing,2016class
student2,nursing,2014class
student3,nursing,2014class
</pre>

=== MNet ===

Existing [[MNet]]users can be added to courses, groups or cohorts as below by using the field header '''mnethostid'''

#enrolling to courses: username+mnethostid+course required
#adding to group: username+mnethostid+course+group required
#adding to cohort: username+mnethostid+cohort required
#suspending/reviving accounts: username+mnethostid+suspended required

All other operations are ignored. You can not add users, delete them or update them (such as change names or email, profile fields, etc.)

=== Set system roles ===
Users may also be assigned to already defined system roles, using the shortname of the system role as defined in ''Site administration > Users > Permissions > Define roles'' for roles with a system context defined.

<code>sysrole1,sysrole2,sysrole3</code> etc.

Users may be uploaded to a system role (usually Manager or Course creator) by entering the shortname of that role. Other roles can only be uploaded if they have already been assigned in the 'system' context. See [[Creating custom roles]]. Multiple roles can be assigned using sysrole2, sysrole3, etc. fields. Note that the number suffix in no way relates to the number suffixes on the enrolment fields. The numbers must go up in sequence starting at 1.

Unassigning system roles
Users can also be removed from a given system role by entering the shortname of that role prefixed with a minus symbol: '-'. If the user is currently assigned to that role, they are removed from it. If the user is not currently assigned to that system role, the field value is ignored. However, the field value must refer to a system role that does exist on the system, otherwise an error will occur.
[[File:GlobalRoles1.png|thumb|500px|center|Example of a file for uploading users with global/system roles]]

==Upload user process==

# Create file for uploading
# Go to ''Site administration > Users > Accounts > Upload users''
# Add file to upload
# Upload users preview - check settings and default user profile settings
# Upload users preview - click "Upload users"
# Upload users results - shows list of users, exceptions made in upload and summary of number of users
# Upload users results - click "Continue"
# Returns to Upload users screen

==Updating users preview==
There are various settings to better control the desired upload behaviour. These settings are found on the "Upload users preview" page.

'''Warning''': errors updating existing accounts can affect your users badly. '''''Be careful''''' when using the options to update.

====Upload type====
The Upload type specifies how to handle existing accounts.

;Add new only, skip existing users : is the default Moodle upload type. It creates a new user account for each new record in the uploaded file. If an existing username is found in the uploaded file matches an existing username, that record is '''skipped'''. By skipping the existing user account, the data in the existing record is not touched (in contrast to the "Add new and update existing users" option) and a second new user account is '''not''' created (in contrast to the "Add all, append number to usernames if needed" option).

;Add all, append number to usernames if needed : creates a new user account for each record in the uploaded file. If an existing user account is found, a new account will be created with a number appended to the username. For example, if a user account for username 'jsmith' already exists and a new record in the uploaded file contains a record forusername 'jsmith' an additional user account is created with a 1 '''appended''' to the username to produce user 'jsmith1'.

;Add new and update existing users : creates a new user account for each new user in the upload file. If an existing user account with the same username is found, the account information is '''updated''' by the data in the uploaded file.

;Update existing users only : ignores any new users found in the upload file and updates the user account if a matching username record is found in the uploaded file.

====New user password====
When creating a new user account Moodle can create a new password (if one is not provided) or require a password in the uploaded file.

;Create password if needed and send via email: creates a random default password for each new user account if one is not provided in the uploaded file, and emails the user their user information and new password.

;Field required in file : requires that a password be provided in the uploaded file in order. If a password is not provided, an error is generated and the user account is not created. No notification of this user information or password is sent to the user.

====Existing user details====
The Existing user details options are only available when the Upload type allows existing user accounts to be updated. It specifies how Moodle should process user detail information for existing users.

;No changes : ignores user detail data in the uploaded file and leaves the existing user account data unchanged.
;Override with file : overwrites data in the existing user account with the data provided in the uploaded file.
;Override with file and defaults : overwrites data in the existing user account with data provided in the uploaded file and fills in the default values for existing user details when no data is provided in the uploaded file.
;Fill in missing from file and defaults : adds data in the existing user account with data provided in the uploaded file if the field is empty (does not already contain data) and fills in the default values for existing user details when no data is provided in the uploaded file.

====Existing user password====
The Existing user password option appears when you you have set the "Existing user details" setting to "Overwrite with file". It specifies how to handle password data for existing user accounts, to change them or leave them as it. This is a bit of insurance to make sure that you really want to mass change user passwords.

;No changes : ignores password field in the uploaded user file and leaves the existing user account password untouched
;Update : overwrites the existing user account password with the password provided in the uploaded file

====Force password change====
The Force password change option specifies when to tag a user account so that the next login attempt will require the user to change the user's password.

;Users having a weak password : If the user account has a weak password as defined by the site's [[Password policy#Password policy|Password policy]] then the user will be forced to change the password during the next login attempt. This option is not shown if there the site does not have a [[Password policy#Password policy|Password policy]].
;None : None of the users in the uploaded file will be forced to change the password during the user's next login attempt.
;All : All of the users in the uploaded file will be forced to change the password during the user's next login attempt.

====Allow renames====
If the uploaded file contains the special '''oldusername''' field, it is possible to rename a user from the '''oldusername''' to a new '''username'''. The default setting is to '''not''' allow renames. Keep in mind that renaming a user will require the user to use the new username when logging in.
;No : ignores the '''oldusername''' field and leaves the existing user account's username field unchanged.
;Yes : allows the existing user account's username to be changed by the data provided in the uploaded file's username field. The '''oldusername''' will be searched for and then updated with the data provided in the username column.

====Allow deletes====
If the uploaded file contains the '''deleted''' special field, it is possible to use the upload file to delete existing user accounts. The default setting is to '''not''' allow deletes. Keep in mind that deleting a user account will prevent that user from logging in. As a protection, site administrator user accounts cannot be deleted with this method.
;No : ignores the '''deleted''' special field in the uploaded file and leaves the existing user account unchanged
;Yes : allows the existing user account to be deleted when the value of the '''deleted''' field is 1.

====Allow suspending and activating of accounts====
If the uploaded file contains the '''suspended''' special field, it is possible to use the upload file to either suspend or make active (unsuspend) existing user accounts. The default setting is to allow suspending/activating of existing user accounts. Keep in mind that suspending an existing user account will prevent that user from logging in.
;Yes : allows the existing user account to be suspended when the value of the '''suspended''' field is 1.
;No : ignores the '''suspended''' special field in the uploaded file and leaves the existing user account status unchanged.

====Prevent email address duplicates====
It is possible, but '''not''' recommended to upload users with duplicate email addresses. By default, uploading users with duplicate email addresses is prevented. To allow duplicate email addresses, go to Site administration ► Plugins ► Authentication ► Manage authentication. You can tick "Allow accounts with same email". Then on the upload users screen you will be allowed to change the "Prevent email address duplicates" setting.

However, doing this is not recommended for file uploads. Test thoroughly any user uploads before implementing.

For more info, see the [[Managing authentication#Allow accounts with same email|Managing authentication]] docs page
;Yes : prevents user accounts from being created from the uploaded if an existing user account already has the same email address as found in the uploaded file's '''email''' column.
;No : allows user accounts to be created if an existing user account already has the same email address found in the uploaded file's '''email''' column.

====Standardise usernames====
Standardise usernames is used by default to convert the username to all lower case and to strip out illegal characters. It is possible to not standardise the usernames; however, doing so is '''not''' recommended.
;Yes : standardises usernames found in the uploaded file before updating existing or creating new user accounts so that the username contains only lowercase letters and numbers.
;No : skips standardising usernames found in the uploaded file so that the newly created or updated usernames will be exactly as they are in the uploaded file ('''not recommended''').

For those seeking a more technical explanation, the process for standardising the usernames consists of ensuring the characters are all UTF-8 (fix_utf8) encoded, converting the username to lower case, and then stripping out non-letters/non-number characters (unless ''Site administration > Security > Site policies > Allow extended characters in usernames'' is set on) with something similar to:

<code>$username = preg_replace('/[^-\.@_a-z0-9]/', '', $username);</code>

====Select for bulk user actions====
After the uploaded file has finished being processed (all new accounts have been created and existing accounts updated as specified by the previous settings), there is an option to select some of those user accounts to perform additional [[admin/user/user bulk|bulk user actions]] such as
*Confirm user accounts created through Email-based self-registration which are not yet confirmed by the user
*Send a message (requires Messaging to be enabled)
*Delete user accounts
*Display a list of users on a page
*Download user data in text, ODS or Excel file format
*Force users to change their passwords
*Add users to a cohort

By default, no users are selected for [[admin/user/user bulk|bulk user actions]].

;No : No users are selected for [[admin/user/user bulk|bulk user actions]]
;New users : Only newly created users are selected for [[admin/user/user bulk|bulk user actions]]
;Updated users : Only updated user accounts are selected for [[admin/user/user bulk|bulk user actions]]
;All users : All users found (existing updated users and newly created user accounts) in the uploaded file are selected for [[admin/user/user bulk|bulk user actions]]

===Default values===

You can provide default user values for some fields not included in the uploaded file. Some fields include:

*Email display
*Forum auto-subscribe
*City/town
*ID number
*Institution
*Department

By clicking the '''Show more....''' link, other default user profile fields will show up. You can set 17 different fields here, including the Authentication method, Country. Language, Timezone, as well as most other standard User profile fields.

'''Other fields'''

If you have created any custom profile fields for your users, they will show up here.

==Upload user results ==
After accepting the preview settings by clicking on "Upload users", you should see the Upload users results screen.
[[File:Upload users results 2.0.JPG|thumb|center|The results screen; everything went well!]]
This screen will show you any exceptions or changes that were made to each user in the upload process. For example, if you were updating user information, the updated information will be shown. Or if a user was not added that record will be highlighted.

The screen will summarize how many users were uploaded or updated, indicate the number of weak passwords and the number of errors.

==Advanced potentials of Upload user==
===Templates===

''Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.''

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

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

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

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

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

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

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

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

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

===Deleting accounts===

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

''Tip:'' A similar field is available for '''suspended'''. This enables a user account to be temporarily disabled rather than completely removed.

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

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

==Encoding file format==
On the initial Upload user screen, you may select the file encoding format from a pull down list. These include UTF-8 (the default), ASCII, ISO-8859-1 to ISO-8859-11 or any one of over 36 formats.

==Hints==

===Spreadsheet===

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

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

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

The upload will also fail if you have trailing spaces at the end of your data fields. Often, this can not be removed with a simple Find " " and Replace with "". If information has been copied from web sources than it is possible to include non-breaking spaces which will prevent your upload from being completed correctly. To find these invisible spaces, use the Find and Replace function in Excel. In the find field, hold alt and type 0160. Leave the replace field blank.

===Field size limits===
Some fields have maximum character lengths, as defined in the database fields. Typically the file will import to the preview list screen but not finish the process. Turn on debug to see the fields that are too long. The error will be "User not added - error".

The sizes of some common fields, in number of characters, are currently (3.2):

*username - 100
*password - 255
*idnumber - 255
*firstname - 100
*lastname - 100
*lastnamephonetic - 255
*firstnamephonetic - 255
*middlename - 255
*alternatename - 255
*institution - 255
*department - 255
*address - 255
*city - 120
*icq -15
*skype - 50
*yahoo - 50
*aim - 50
*msn - 50
*phone1 - 20
*phone2 - 20

===All user fields listed here===
:All the user fields that are valid in an upload file are listed below, except for any custom fields you may have created (for which see below.)

<pre>firstname,lastname,username,email,password,auth,idnumber,institution,department,city,country,timezone,lang,mailformat,maildisplay,maildigest,htmleditor,autosubscribe,skype,msn,aim,yahoo,icq,phone1,phone2,address,url,description,descriptionformat,interests,oldusername,deleted,suspended,alternatename,lastnamephonetic,firstnamephonetic,middlename</pre>

The enrolments into courses information are <pre>course1,type1,role1,group1,enrolperiod1,enrolstatus1</pre>
where each enrolment is grouped by number.

===Capabilities===

You may wish to create a limited role to allow some users access to this function. Create a role at the system/site level with the following capabilities allowed:
* moodle/site:uploadusers
* moodle/role:assign

And
* In 'Allow role assignments' tab of this new role, permit it to assign the required roles that it may be uploading, especially Student, but also Teacher, Non-editing Teacher, and any other custom roles you may have created, which will be used in the uploads to assign users to.

In particular, don't forget the moodle/role:assign capability (even if these users have it in the courses they will be enrolling users in - it won't work).

==Upload users via CLI==

In Moodle 3.10 onwards, an administrator can upload users via a CLI script.

To obtain instructions on how to use the script, in the command line from the moodle directory run
php admin/tool/uploaduser/cli/uploaduser.php --help

== See also ==
* [[Flat file]] enrolment
* [[User profile fields]] for details of how to include data about custom user profile fields in the upload users file
* [[Upload courses]]

Forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish

[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[de:Nutzerliste hochladen]]
[[es:Subir usuarios]]

Administration via command line

2021-12-05T14:40:39Z

Leonstr: /* Scheduled tasks */ Added ad hoc tasks script

{{Installing Moodle}}
==Running CLI scripts==
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 may provide CLI functionality via scripts in their own <code>cli</code> folder.

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 www-data 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

{{Note|These scripts are supposed to be run under the identity of the web server user. Examples on this page use the <tt>apache</tt> user for illustration. The particular value depends on your OS distribution and local set-up. Typical values may be <tt>apache</tt>, <tt>www-data</tt> or <tt>httpd</tt>.}}

== Upgrading ==

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

There are two modes of installing Moodle from the command line. 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

If your arguments contain some specials characters for Linux-based systems, don't forget to ''escape'' them with a backslash. For example, if you want to create an admin with ''pa$sword'' as password you should wrote ''pa\$sword'' instead!

If required, the database install may be skipped, with just config.php populated.

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

== 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 maintenance mode off, execute the same script with the --disable parameter:

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

If you don't want to enable maintenance mode immediately, but show a countdown to your users, execute the same script with the --enablelater parameter and the number of minutes which the countdown should run:

$ sudo -u apache /usr/bin/php admin/cli/maintenance.php --enablelater=10

This script will also create and remove the climaintenance.html file for "Offline" mode.

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

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

These defaults are used during install, upgrade and are also displayed as defaults on 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 on the site), 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

==Converting InnoDB tables to Barracuda==

Sites using MySQL with database tables using Antelope as the file format are recommended to convert the tables to the Barracuda file format.

This is because tables using Antelope as the file format cannot handle more than 10 text columns. This file formats only supports ''compact'' and ''redundant'' row formats for backward compatibility reasons. This may cause a problem on larger sites when restoring a course, in which case the following error will be displayed:

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

Barracuda is the newest innoDB file format. In addition to supporting ''compact'' and ''redundant'' row formats, Barracuda also supports ''compressed'' and ''dynamic'' row formats.

However, converting tables to Barracuda is only recommended, and not required, since not all MySQL users are affected. (It may only be a problem for larger sites.)

===Tool for converting tables===

A command line tool is included in Moodle for converting tables to Barracuda.

To view tables requiring conversion, use the list option:

$ php admin/cli/mysql_compressed_rows.php --list

Here is an example output:

mdl_data Compact (needs fixing)
mdl_data_fields Compact (needs fixing)
mdl_enrol_paypal Compact (needs fixing)

To proceed with the conversion, run the command using the fix option:

$ php admin/cli/mysql_compressed_rows.php --fix

Successful table conversion will be reported in the output, for example:

mdl_data ... Compressed
mdl_data_fields ... Compressed
mdl_enrol_paypal ... Compressed

Please note that the commands must be executed on your moodle directory. Once tables are fixed, the warning message will no longer be displayed.

For further information on InnoDB file formats see the [http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_antelope MySQL InnoDB glossary - Antelope] and the [http://dev.mysql.com/doc/innodb/1.1/en/glossary.html#glos_barracuda MySQL InnoDB glossary - Barracuda].

If you get errors due to having insufficient privileges to run these commands (this is quite likely) then the easiest solution is to generate the required SQL commands using,

$ php admin/cli/mysql_compressed_rows.php --showsql

You can then copy the generated SQL into your mysql client running as the 'root' user.

==Converting to the new character set and collation==

$ php admin/cli/mysql_collation.php --collation=utf8mb4_unicode_ci

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

Scheduled tasks are automatically run by the cron script, 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/cli/scheduled_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.

--showsql - Shows sql queries before they are execute

--showdebugging - Shows developer debugging info

'''Note:''' You must escape the "\" with an extra \ when using the --execute command. Take the following for example:
<pre>php admin/cli/scheduled_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

php admin/cli/scheduled_task.php --execute='\enrol_imsenterprise\task\cron_task'

Be aware of the single quotes. Without them, you would need to use double backlashes to avoid escaping by the shell.

=== Ad hoc tasks ===
[[Cron#Low_latency_adhoc_tasks|Ad hoc tasks]] are low-latency tasks that are normally run by the cron. You can run just the queued ad hoc tasks with admin/cli/adhoc_task.php.

This script accepts the following options and arguments:

<pre>
-h, --help Print out this help
--showsql Show sql queries before they are executed
--showdebugging Show developer level debugging information
-e, --execute Run all queued adhoc tasks
-k, --keep-alive=N Keep this script alive for N seconds and poll for new adhoc tasks
-i --ignorelimits Ignore task_adhoc_concurrency_limit and task_adhoc_max_runtime limits
-f, --force Run even if cron is disabled
</pre>

For example to run the currently queued ad hoc tasks:

sudo -u apache php admin/cli/adhoc_task.php -e

==Database transfer==

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

==Purge caches==

You can purge caches using this script:

php admin/cli/purge_caches.php

==Kill all sessions==
If needed for administrative reasons, you can kill all user sessions using this script:

php admin/cli/kill_all_sessions.php

As a result, all users will be logged out from Moodle.

==Backup and restore of large courses==

See Backup via CLI in [[Course backup]] and Restore via CLI in [[Course restore]] (new in 3.10 onwards).

==Fix course / module sequences==

In rare cases (such as after upgrading from a very old version of Moodle), the course / section / module sequence data can be out of sync. This can cause various problems for affected courses, such as sections not appearing, backups failing, pages not displaying etc. There is a specific check to check for errors caused by this problem, and to fix the data in the database if they are found. To run this script please use the command below:

php admin/cli/fix_course_sequence.php -c=* --fix

This will check every course in Moodle and report which ones had errors and were fixed.

==Fix orphaned question categories==

When a quiz is created, a new question category for the quiz is automatically created. In versions of Moodle prior to 2.9.1, if the quiz is deleted, the question category and any questions in the category remain in database. These orphaned question categories may be fixed by running the admin/cli/fix_orphaned_question_categories.php script with the --fix option.

==Search and replace text==

This script can be used to search and replace text throughout the whole database. Use carefully and backup first always. More info in [[Search and replace tool]].

php admin/tool/replace/cli/replace.php --search=//oldsitehost --replace=//newsitehost

==Build theme CSS cache==

If Moodle is not running in theme designer mode it will keep a copy of the compiled CSS on local disk and serve that to the browser when it requests a page. If there isn't a copy on local disk then a copy will be built the first time a page within Moodle is requested.

With this script you can pre-compile the cached CSS files for themes within Moodle to avoid having a user wait for the theme to compile during the first page request.

php admin/cli/build_theme_css.php --themes=boost

==Get and set configuration values==

Displays the current value of the given setting, or set the given setting to the specified value.

$ php admin/cli/cfg.php [--component=<componentname>] [--json] [--shell-arg]
$ php admin/cli/cfg.php --name=<configname> [--component=<componentname>] [--shell-arg] [--no-eol]
$ php admin/cli/cfg.php --name=<configname> [--component=<componentname>] --set=<value>
$ php admin/cli/cfg.php --name=<configname> [--component=<componentname>] --unset
$ php admin/cli/cfg.php [--help|-h]

Examples:
$ php admin/cli/cfg.php --name=langmenu
will display the value of ''Display language menu'' in ''Site administration > Language > Language settings'' (0 for ''No'' or 1 for ''Yes'').
$ php cfg.php --name=maxsizetodownload --component=folder
will display the value of ''Maximum folder download size (MB)'' accessible from ''Site administration > Plugins > Activity modules > Folder''.
$ php admin/cli/cfg.php --name=langmenu --set=0
will disable the ''Language menu''.

==See also==

* MDL-35736 - Manage plugins via command line
* MDL-36237 - Resort course list via CLI
* [http://moosh-online.com/ MOOSH] - MOOdle SHell. It is a commandline tool that will allow you to perform most common Moodle tasks.

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

Standard themes

2021-09-13T09:12:51Z

Leonstr: "Note:" prefix added by wiki, changed <code> to <syntaxhighlight>

{{Themes}}
{{Note|Clean, More and Bootstrapbase have been removed from core in Moodle 3.7. You are advised to use the [[Classic theme]] instead.}}
==Standard themes==

Moodle has two standard themes: ''[[Boost theme|Boost]]'' and ''[[Classic theme|Classic]],'' a responsive, bootstrap-based theme combining the navigation structure of the deprecated Clean and More themes and the customisation options of the Boost theme.

Other themes are available from the [https://moodle.org/plugins/browse.php?list=category&id=3 Themes section of the Moodle plugins directory].

===Example of a customised Boost theme===
[[File:SchoolDemoBoost.png|thumb|center|600px]]

The Moodle School demo site, [http://school.moodledemo.net Mount Orange], uses standard Boost with customisations as follows:
* An image for the front page and a background image need to be uploaded and referenced in the code.
*'''Front page topic section:'''

<syntaxhighlight lang="html">
<div class="frontpage container-fluid">

<div class="jumbotron jumbotron-fluid" style="background-image: url('YOUR UPLOADED FRONT PAGE IMAGE.jpg');">
<div class="texts">
<h2>YOUR HEADING</h2>
<p class="lead">SENTENCE/TAG LINE</p>
</div>
</div>

<div class="row-fluid">
<div class="fp-block col-md-6">
<h3>SMALLER HEADING</h3>
<p>Paragraph of text</p>
<p class="button"><a class="btn btn-primary" href="BUTTON LINK URL">BUTTON TEXT »</a></p>
</div>
<div class="fp-block col-md-6">
<h3>SMALLER HEADING</h3>
<p>Paragraph of text.</p>
<p class="button"><a class="btn btn-primary" href="BUTTON LINK URL">BUTTON TEXT »</a></p>
</div>
</div>

</div>
</syntaxhighlight>

*'''Boost theme Advanced settings - Raw initial SCSS:'''

<syntaxhighlight lang="css">
$brand-primary: #0070a8;
$body-color: #336;
$font-family-sans-serif: "Helvetica Neue", Helvetica, Arial, sans-serif;
$breadcrumb-bg: #fff;
</syntaxhighlight>

*'''Boost theme Advanced settings - Raw SCSS:'''

<syntaxhighlight lang="css">
body {
background-image: url("YOUR UPLOADED BACKGROUND IMAGE.png");
background-size: cover;
background-repeat: no-repeat;
background-attachment: fixed;
letter-spacing: .3px;
}
h1, h2, h3, h4, h5, h6 {
color: #f98012;
font-weight: normal;
}
.navbar-brand {
display: none;
}
#nav-drawer {
background-color: rgba(236, 238, 239, .9);
}
#page-header.row {
margin-left: -30px;
margin-right: -30px;
}
#page-header .card {
background-color: transparent;
border: none;
margin-bottom: 0;
}
#page-header h1 {
color: #fff;
font-weight: 500;
text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.2);
}
#page-header .breadcrumb {
padding: .50rem 1rem;
}
.block-region .card-block .card-title {
color: #f98012;
font-size: 1.07rem;
font-weight: 400;
}
#page-footer a {
color: #f98012;
}
#page-site-index #page-header {
display:none;
}
#page-site-index #region-main .card.card-block {
padding: 0;
border: 0;
background-color: transparent;
}
#page-site-index #block-region-side-pre {
margin-top: 15px;
}
#page-site-index .label {
padding: 0;
}
#page-site-index .activity > div {
padding: 0;
}
#page-site-index .mod-indent-outer {
padding-left: 0;
}
#page-site-index .contentwithoutlink {
padding-right: 0;
}
.frontpage.container-fluid {
padding: 0;
}
.frontpage .jumbotron {
padding:0;
border-radius:0;
background: transparent no-repeat right bottom / cover;
line-height: 250px;
}
.frontpage .jumbotron .texts {
color: #fff;
letter-spacing: .5px;
background-color: rgba(255, 99, 0, 0.70);
padding: 0 20px;
margin-bottom:20px;
display: inline-block;
vertical-align: bottom;
}
.frontpage .jumbotron h2 {
color: #fff;
font-size: 32px;
font-weight: 300;
text-shadow: 1px 1px 1px #444;
margin-bottom: 0;
margin-top: 10px;
}
.frontpage .jumbotron .lead {
text-shadow: 1px 1px 1px #333;
line-height: 30px;
font-size: 21px;
}
.frontpage .row-fluid {
line-height: 24px;
background-color: #fff;
padding: 10px 20px 20px;
box-sizing: border-box;
}
.frontpage .row-fluid::after {
display: table;
content: "";
clear: both;
line-height: 0;
}
.frontpage .fp-block {
padding: 10px 20px 0;
}
.frontpage h3 {
font-size: 26px;
line-height: 30px;
font-weight: 300;
margin-top: 20px;
margin-bottom: 20px;
}
.frontpage .button {
text-align: right;
}
.empty-region-side-pre.empty-region-side-post #region-main-box,
.empty-region-side-pre.empty-region-side-post #region-main {
width: 100%;
}

#settingsnav.box.block_tree_box.p-y-1 {
padding-top: 0!important;
}</syntaxhighlight>

==Theme selector==

An administrator can set a theme for the site in ''Administration > Site administration > Appearance > Themes > Theme selector''.

Different themes may be set according to 'device type' - default, legacy (for older browsers), mobile and tablet.

Go to ''Administration > Site administration > Appearance > Themes > Theme selector''
*Click on the "Select theme" button next to the type you wish to change
*Scroll down to see the previews of the available themes and click on the "Use theme" button to chose the theme
*The next screen will provide information about the theme. Click "Continue"

Note 1: Moodle caches themes so if you don't immediately see changed settings that you were expecting, click the "Clear theme caches" button at the top of the Theme selector page.

Note 2: The selected theme may be overridden if user/course or category themes have been allowed in the [[Theme settings]].

==See also==

* [[Boost theme]]
* [[More theme]]
* [[Theme credits]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=189573 What counts as a 'legacy' device type?] forum discussion

[[de:Standard-Designs]]
[[es:Temas estándar]]
[[fr:Thèmes standards]]

Universal Office Converter (unoconv)

2021-08-31T14:31:19Z

Leonstr: /* Installing unoconv on Windows */ Tidied up formatting and changes for clarity

{{Document converters}}
==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 18.04 LTS===
<pre>
apt-get install unoconv
mkdir /var/www/.config
chown www-data:www-data /var/www/.config
</pre>

===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).
On Debian Stable, the cleanest method to install [https://packages.debian.org/jessie-backports/unoconv unoconv] is using Jessie-backports. First, enable backports repo line in /etc/apt/sources.list:
<pre>
#### Jessie-backports ####
deb http://ftp.debian.org/debian jessie-backports main
</pre>

Then, update and install unoconv from jessie-backports:
<pre>
apt-get update
apt-get install -t jessie-backports unoconv
</pre>

The package will bring all necessary dependencies for you.

===Ubuntu 14.04 LTS===

1) Navigate to opt directory
<pre>
cd /opt
</pre>

2) Download unoconv
<pre>
sudo wget https://raw.githubusercontent.com/dagwieers/unoconv/master/unoconv
</pre>

3) Modify the Python unoconv file by changing 'python' in the first line to 'python3'
<pre>
sudo nano /opt/unoconv
</pre><br>
eg. <pre>#!/usr/bin/env python3</pre>

4) Make unoconv executable
<pre>
sudo chmod ugo+x /opt/unoconv
</pre>

5) Add LibreOffice PPA to your system and install the latest version
<pre>
sudo add-apt-repository ppa:libreoffice/ppa
sudo apt-get update
sudo apt-get install libreoffice
</pre>

6) Change permissions so apache can write to its home directory
<pre>
sudo chown www-data /var/www
</pre>

7) From your browser navigate to
''Site administration > Server > System paths'' and add the path to unoconv<br>
/opt/unoconv
*Note: if you would like to preserve the default path add a symbolic link to /usr/bin:
<pre>
sudo ln -s /opt/unoconv /usr/bin/
</pre>

8) Navigate to
''Site administration > Plugins > Activity modules > Assignment > Feedback plugins > Annotate PDF > Test unoconv path'' <br>
You should see: <br>
"The unoconv path appears to be properly configured."<br>
*Download the converted pdf test file. (if the PDF fails to load ensure that www-data can write to its home directory: /var/www)

===CentOS / RedHat===
Just before you start, you might like to consider installing the latest [http://www.tecmint.com/install-libreoffice-on-rhel-centos-fedora-debian-ubuntu-linux-mint/ LibreOffice 6.3.2] directly from RPM packages, that are not part of the distribution you are using.
As of nov-2016, CentOS and RedHat 7.2 comes with OpenOffice 4.3 . so if you are not interested in using this version and would like to install latest 6.3 independent LibreOffice 6.3 , please remove any openoffice packages you might have on your OS by issuing:
<pre>
yum remove openoffice* libreoffice*
</pre>
It is recommended to chose your localized libreoffice version for better document conversions.
<pre>
yum install libreoffice libreoffice-pyuno
git clone https://github.com/dagwieers/unoconv.git
# copy
cp unoconv/unoconv /usr/bin
# or link unoconv to /usr/bin
ln -s unoconv/unoconv /usr/bin/unoconv
</pre>
Note: depends on what version you are installing, openoffice or libreoffice, make sure you installed the *-pyuno package. (the headless package is already compiled into the core)

Make sure it is properly configured:
http://your-moodle/admin/search.php?query=unoconv

Production servers should consider running unoconv in listener mode, see [[Installing_unoconv#Run_a_unoconv_listener]] or follow directions bellow
<pre>
vi /etc/systemd/system/unoconv.service
</pre>
And then copy and paste the following configuration into it:
<pre>
[Unit]
Description=Unoconv listener for document conversions
Documentation=https://github.com/dagwieers/unoconv
After=network.target remote-fs.target nss-lookup.target

[Service]
Type=simple
Environment="UNO_PATH=/usr/lib64/libreoffice/program"
ExecStart=/usr/bin/unoconv --listener

[Install]
WantedBy=multi-user.target
</pre>
And then enable and start the above service
<pre>
systemctl enable unoconv.service
systemctl start unoconv.service
</pre>
If your selinux is enable yous should set
<pre>
#setsebool -P httpd_execmem on
</pre>

== 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. Open Office will work just as well, but the documentation for unonconv is set to Libre Office.

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 '''unoconv.py''' and copy it to a folder in either '''C:\Program Files''' or '''C:\Program Files (x86)'''.

Create a batch file in the same folder as '''unoconv.py''' name it something like '''unoconv.bat''', it must be a batch file, with these contents:

@"C:\Program Files\LibreOffice\program\python.exe" c:\unoconv\unoconv.py %*

or:

@"C:\Program Files\OpenOffice\program\python.exe" c:\unoconv\unoconv.py %*

Next, you have to '''Set paths in Moodle.'''

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

Set:
''Path to Ghostscript (pathtogs)'' to <code>C:\Program Files\gs\gsversion\bin\gswin64c.exe</code>.
Do not use gswin32.exe or gswin64.exe, these are not command line programs - use gswin32c.exe or gswin64c.exe.

Set:
''Path to Python (pathtopython)'' to <code>C:\Program Files (x86)\OpenOffice\program\python.exe</code> or <code>C:\Program Files (x86)\LibreOffice\program\python.exe</code>.
Identify in the path whichever program you use and include the full exe name for both Ghostscript and Python.

Save the pathto statements and a green tick should appear if Moodle is communicating with the required files.

Go to ''Site administration > Plugins > Document converters'' and enable '''Unoconv''' then select ''Settings''

Enter the path statement to
''Path to unoconv document converter'': <code>C:\Program Files (x86)\unoconv\unoconv.bat</code>.
Include the full name of the .bat file.

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

[[mod/assign/feedback/editpdf/testunoconv/initdcentos6 | Init script for CentOS/RedHat 6.x]]

[[mod/assign/feedback/editpdf/testunoconv/systemd | SystemD service script for CentOS/RedHat 7.x]]

== 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). By default, unoconv will only listen on localhost (127.0.0.1): if you want to connect to the listener process from another server, you need to start the unoconv listener process with the "--server" argument too!

An example command for starting a listener on a remote server (0.0.0.0 listens on all interfaces):
<pre>
unoconv --listener --server 0.0.0.0 --port 2002
</pre>

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

[https://github.com/dagwieers/unoconv GitHub dagwieers/unoconv] has additional information on installation of unoconv and troubleshooting tips.

==Troubleshooting==
* [http://webnetkit.com/soffice-bin-using-100-cpu-moodle/ soffice.bin using 100% of CPU MOODLE]

==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:Universal Office Converter (unoconv)]]
[[de:Universal Office Konverter]]
[[fr:Universal Office Converter]]

Nginx

2021-08-31T12:15:20Z

Leonstr: Undo revision 141607 by Matmercer (talk) I think previous revision is incorrect, details in https://moodle.org/mod/forum/discuss.php?d=413492#p1716224

{{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 flavours. It also has a proof of concept port for Microsoft Windows.

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

== Nginx configuration ==

=== PHP-FPM ===

Nginx is usually configured to interface with PHP via [http://php.net/manual/en/install.fpm.php php-fpm]. This is both fast and robust.

PHP-FPM's default behaviour for pools is usually to restrict the execution of scripts to a specific extension, i.e. .php. You should ensure that this behaviour is configured within your particular package/distribution, e.g. for debian,

'''/etc/php5/fpm/pool.d/www.conf'''
security.limit_extensions = .php

=== Nginx ===

Add the following 'slash arguments' compatible 'location' block to your vhosts 'server' in your nginx configuration (further explanation at '[[Using slash arguments]]').

'''nginx.conf location:'''
<pre>
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000 (or your php-fpm socket);
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
</pre>

If the above does not work try the following:
Note: This was for CentOS 7.6 (1804), MariaDB 10.3, Nginx 1.15 and PHP 7.3.5
<pre>
location ~ ^(.+\.php)(.*)$ {
root /usr/share/nginx/html/moodle/;
fastcgi_split_path_info ^(.+\.php)(.*)$;
fastcgi_index index.php;
fastcgi_pass 127.0.0.1:9000;
include /etc/nginx/mime.types;
include fastcgi_params;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
</pre>

If you find that this does not work (scripts, styles, and images not loading) '''and''' that there are <code>open() "..." failed (20: Not a directory)</code> lines appearing in your logs: Check whether there are any directives related to static content '''before''' this block and try moving them '''after''' this block.

Another potential pitfall is the use of '''try_files'''. Many guides recommend configurations like <pre>try_files $fastcgi_script_name =404;</pre>. But if try_files is used, nginx deletes the content of the '''$fastcgi_path_info''' variable (this is [https://trac.nginx.org/nginx/ticket/321 intended behavior]). This causes '''PATH_INFO''' to also be empty, so slash arguments don't work.
An alternative is the use of <pre>if(!-f $document_root$fastcgi_script_name) {return 404;}</pre> [https://www.nginx.com/resources/wiki/start/topics/examples/phpfcgi/#connecting-nginx-to-php-fpm as recommended] by the nginx documentation, although the nginx documentation also recommends [https://www.nginx.com/resources/wiki/start/topics/depth/ifisevil/ not using if].

==== Error pages ====

<pre>
# This passes 404 pages to Moodle so they can be themed
error_page 404 /error/index.php; error_page 403 =404 /error/index.php;
</pre>

==== Hiding internal files ====

<pre>
# Hide all dot files but allow "Well-Known URIs" as per RFC 5785
location ~ /\.(?!well-known).* {
return 404;
}

# This should be after the php fpm rule and very close to the last nginx ruleset.
# Don't allow direct access to various internal files. See MDL-69333
location ~ (/vendor/|/node_modules/|composer\.json|/readme|/README|readme\.txt|/upgrade\.txt|db/install\.xml|/fixtures/|/behat/|phpunit\.xml|\.lock|environment\.xml) {
deny all;
return 404;
}
</pre>

==== XSendfile aka X-Accel-Redirect ====

Setting Moodle and Nginx to use XSendfile functionality is a big win as it frees PHP from delivering files allowing Nginx to do what it does best, i.e. deliver files.

Enable xsendfile for Nginx in Moodles config.php, this is documented in the config-dist.php, a minimal configuration look like this,
<pre>
$CFG->xsendfile = 'X-Accel-Redirect';
$CFG->xsendfilealiases = array(
'/dataroot/' => $CFG->dataroot
);
</pre>
Accompany this with a matching 'location' block in your nginx server configuration.
<pre>
location /dataroot/ {
internal;
alias <full_moodledata_path>; # ensure the path ends with /
}
</pre>
The definition of 'internal' here is '''critical''' as it prevents client access to your dataroot.

== See also ==

* Real <tt>PATH_INFO</tt> support:
** https://moodle.org/mod/forum/discuss.php?d=278916
** https://moodle.org/mod/forum/discuss.php?d=307388
* '''[Deprecated]''' Internal rewriting to the HTTP GET <tt>file</tt> parameter:
** https://moodle.org/mod/forum/discuss.php?d=83445

[[Category:Installation]]

[[es:Nginx]]
[[pt-br:Nginx]]

LDAP authentication

2021-08-25T09:09:34Z

Leonstr: /* User lookup settings */ Updated 'Member attribute uses dn' as this must be correctly set from 3.8.5/3.9.2 onward https://tracker.moodle.org/browse/MDL-70596#comment-871688

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

==Basic Scenario==
The simple and straightforward approach for most installations.

===Assumptions===
Moodle supports several types of LDAP servers which have different directory structures, special configuration settings, etc. Even if using the same LDAP server type (e.g., MS Active Directory), each site could use a completely different directory structure to hold its user accounts, groups, etc. In order to be able to show example configuration settings in the sections below, we are going to assume a '''hypothetical''' Moodle site and LDAP server with the characteristics listed below.

'''IMPORTANT NOTICE''': be sure to check '''''your''''' Moodle site and LDAP server details (including its directory structure,) and adjust the settings to reflect your own setup.

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

===Enabling LDAP authentication===

An administrator can enable LDAP authentication as follows:

# Go to ''Site administration > Plugins > Authentication > Manage authentication'' and click the eye icon opposite LDAP Server. When enabled, it will no longer be greyed out.
# Click the settings link, configure as required (see information below), then click the 'Save changes' button.

[[Image:LDAPserversettings.png|center]]

Now, you just have to fill in the values. Let's go step by step.

====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. <u>So unless you need something special, you don't need to fill this in</u>.

By the way, it's usually '''cn''' (Novell eDirectory and MS-AD) or '''uid''' (RFC-2037, RFC-2037bis and SAMBA 3.x LDAP extension), but if you are using MS-AD you could (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. <u>So unless you need something special, you don't need to fill this in.</u>

By the way, the usual values are '''member''' and '''memberUid'''.
|-
| Member attribute uses dn
| Whether the member attribute contains distinguished names (Yes) or not (No). This must be set to Yes for Active Directory.
|-
| Object class
| The type of LDAP object used to search for users. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
* If you leave it blank, the 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
|}

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

<u>As you don't want your users to change their passwords in their first login, leave this set to ''No''</u>
|-
| Use standard Change Password Page
|
* Setting this to ''Yes'' makes Moodle use its own standard password change page, everytime users want to change their passwords.
* Setting this to ''No'' makes Moodle use 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 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.

<u>So unless you have Novell eDirectory server or MS-AD, choose ''No'' here.</u>
|-
| Expiration warning
| This value sets how many days in advance of password expiration the user is warned that her password is about to expire.
|-
| Expiration attribute.
| The LDAP user attribute used to check password expiration. This option takes a default value based on the ''User type'' value you chose above. <u>So unless you need something special, you don't need to fill this in.</u>
|-
| Grace logins
| This setting is specific to Novell eDirectory. If set to ''Yes'', enable LDAP gracelogin support. After password has expired the user can login until gracelogin count is 0.

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

<u>So you don't need to fill this in.</u>
|}

====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 ''Site administration > Plugins > Authentication > Manage authentication''. Otherwise the new users won't be able to self-create new accounts.

Novell eDirectory and MS-AD can create users externally. 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.
|}

====Assign system roles====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| System role mapping
| This section lists all roles that have can be assigned in the System context - by default this will be "Manager context" and "Course creator context", but can be customisable in the [[Creating custom roles|role definitions]].

To assign LDAP users to any of the roles, specify the DN containing all users who should be granted that role at the system level.

Thie DN 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.

This section replaces the "Course creator" section found in Moodle 3.3. The upgrade process should migrate any DN specified to the new approach.

|}

====User account synchronisation====
{| 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.
|}

====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).
|}

====Data Mapping====
{| border="1" cellspacing="0" cellpadding="5"
! Field name
! Value to fill in
|-
| First name
| The name of the attribute that holds the first name of your users in your LDAP server. This is usually '''givenName''' or '''displayName'''

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

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

<u>This setting is optional</u>
|-
| City/town
| The name of the attribute that holds the city/town of your users in your LDAP server. This is usually '''l''' (lowercase L) or '''localityName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Country
| The name of the attribute that holds the country of your users in your LDAP server. This is usually '''c''' or '''countryName''' (not valid in MS-AD).

<u>This setting is optional</u>
|-
| Language
| '''preferredLanguage'''

<u>This setting is optional</u>
|-
| Description
| '''description'''

<u>This setting is optional</u>
|-
| Webpage
| <u>This setting is optional</u>
|-
| ID Number
|

<u>This setting is optional</u>
|-
| Institution
|

<u>This setting is optional</u>
|-
| Department
| The name of the attribute that holds the department name of your users in your LDAP server. This is usually '''departmentNumber''' (for posixAccount and maybe eDirectory) or '''department''' (for MS-AD).

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

<u>This setting is optional</u>
|-
| Phone 2
| The name of the attribute that holds an additional telephone number of your users in your LDAP server. This can be '''homePhone''', '''mobile''', '''pager''', '''facsimileTelephoneNumber''' or even others.

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

<u>This setting is optional</u>
|}

=====Custom User profile fields=====

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

==Enabling the LDAP users sync job==

The LDAP users sync job (''\auth_ldap\task\sync_task'') [[Scheduled tasks|scheduled task]] (new in Moodle 3.0; previously there was a CLI script, see MDL-51824 for more info) is responsible for creating and updating user information, and suspending and deleting LDAP accounts.

After enabling LDAP server authentication, an administrator needs to enable and configure the LDAP users sync job as follows:

# Go to ''Site administration > Server > Scheduled tasks'' and click the gear icon opposite LDAP users sync job.
# Select the desired frequency of running and enable the task by un-ticking the disabled checkbox.
{{Warning|It is important to make sure that all LDAP settings are working properly before enabling the LDAP users sync job (as well as backing up your database and moodledata folders), since incorrect LDAP configuration can result in 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 than Moodle will obtain all your users correctly. If you can't upgrade to PHP 5.4 you may be able to follow the instructions in http://support.microsoft.com/kb/315071 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.

==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] forum discussion

===Using a multi-domain AD environment===
* If you're running Active Directory with multiple domains and you have users in more than 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 always 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.

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

==Any questions?==

Please post in the [http://moodle.org/mod/forum/view.php?id=42 Authentication forum] on moodle.org.

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

Forum discussions:
* [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]]

Cron

2021-08-24T16:37:45Z

Leonstr: /* Scaling up cron with multiple processes */ Tidied formatting

{{Installing Moodle}}
The Moodle 'cron' process is a PHP script (part of the standard Moodle installation) that must be run regularly in the background. The Moodle cron script runs different tasks at differently scheduled intervals.

'''IMPORTANT: Do not skip setting up the cron process on your server for your Moodle. Your site will not work properly without it.'''

It is recommended that ''the cron is run every minute'', as required for asynchronous activity deletion when using the [[Recycle bin|recycle bin]].

The cron program (that runs the Moodle script) is a core part of Unix based systems (including Linux and OSX) being used to run all manner of time-dependent services. On Windows the simplest solution is to create a task in the Windows Task Scheduler and set it to run at regular intervals. On shared hosting, you should find the documentation (or ask support) how cron is configured. Most shared hosting systems use CPanel to manage sites, and usually will have a section for Cron Jobs on the panel.

Essentially, the task involves adding a single command to the list of cron activities on your system. On Unix based systems this list is a file called a 'crontab' which all users have.
== General discussion ==
See the later sections for your server type; this section contains some general background information.

There are essentially two steps to implementing cron:
# identifying the correct command to run
# finding the right place on your system to put the command
=== Working out the Moodle cron command ===
Moodle has two different ways to deploy cron which use different scripts within the Moodle install. These are as follows...
# The CLI (command line interpreter) script. This will be at the path <pre>/path/to/moodle/admin/cli/cron.php</pre> If in doubt, this is the correct script to use. This needs to be run by a 'PHP CLI' program on your computer. So the final command may look something like <pre>/usr/bin/php /path/to/moodle/admin/cli/cron.php</pre> You can (and should) try this on your command line to see if it works. '''WARNING: Check your command-line PHP version is compatible with your chosen version of Moodle. The command-line PHP program is different to the one running your web site and is not always the same version.'''
# If, for some reason, you cannot run the CLI script there is the web based script. Note that this is now deprecated and may be removed in future versions. This needs to be run from a web browser and will be accessed via a web url something like '''http://your.moodle.site/admin/cron.php'''. You can find command line based web browser (e.g. wget) so the final command may look like <pre>/usr/bin/wget http://your.moodle.site/admin/cron.php</pre> This has the advantage that it can be run from *anywhere*. If you can't get cron to work on your machine it can be run somewhere else.
===The web based Moodle cron command===
* If you have a choice, do not use the web based cron. It is likely to be removed in a future Moodle version.
* From Moodle 2.9 onwards, the cron job can no longer be run from web by default. You will get an error message:
!!! Sorry, internet access to this page has been disabled by the administrator. !!!
* You can change this in ' Dashboard ► Site administration ► Security ► Site policies ' by deselecting 'Cron execution via command line only'.
** You will be warned that 'Running the cron from a web browser can expose privileged information to anonymous users. Thus it is recommended to only run the cron from the command line or set a cron password for remote access.'
** You can then write a 'Cron password for remote access'. If this field is left empty, no password is required.
** This means that the cron.php script cannot be run from a web browser without supplying the password using the following form of URL:
http://site.example.com/admin/cron.php?password=opensesame
=== Finding the right place to put the command ===
This really does depend on the system you are using and you should find and read the documentation for your platform or hosting. In most cases getting the Moodle cron to run consists of establishing the correct command (above) and then adding it, and the time to run the command, to some sort of file. This might be either through a specific user interface or by editing the file directly.

If using the CLI version you also need to make sure that the cron process is run as the correct user. This is not an issue with the web version.

Example... installing cron on Ubuntu/Debian Linux. Assuming logged in as root..

''use the crontab command to open a crontab editor window for the www-data user. This is the user that Apache (the web server) runs as on Debian based systems''
<pre>
$ crontab -u www-data -e
</pre>
''This will open an editor window. To run the cli cron script every 1 minute, add the line:''
<pre>
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php >/dev/null
</pre>
NOTE: the final '''>/dev/null''' sends all the output to the 'bin' and stops you getting an email every 1 minute.
== Setting up cron on your system ==
Choose the information for your server type:
*[[Cron with Unix or Linux]]- Cron services on various UNIX and Linux flavored operating systems.
*[[Cron with Windows OS]] - Cron services in Windows
*''Apple OSX'' - use the built-in 'crontab' service which is exactly the same as [[Cron with Unix or Linux]]. However, you might want to do it the 'Apple way' using launchd - see [[Cron with MAC OS X]]
*[[Cron with web hosting services]]- Cron services in various web hosting examples.
Here are some more instructions for specific hosts (please check that these are up to date):
*[[Cron on 1and1 shared servers]]
== Using third party cron service ==
Besides using cron hosted on your own server, you may use third party cron service (usually called webcron):
*[https://cron-job.org/ cron-job.org] is a free service. (1Minute cron is possible)

*[https://www.easycron.com EasyCron] - A webcron service provider that eliminates the need of crontab or other task schedulers to set cron job.

*[https://webcron.talent-factory.ch/ WebCron] - A free and easy webcron service provider.
=== Cron settings in Moodle ===
An admin can set cron execution via command line only or a cron password for remote access in 'Site security settings' in the Site administration.
===Remote cron===
Using the 'web based' version of cron it is perfectly ok to place the cron process on a different machine to the Moodle server. For example, the cron service on a Unix server can invoke the cron web 'page' on a Windows based Moodle server.
==Scheduling tasks==
An administrator can schedule cron tasks very precisely from Administration > Site administration > Server > Scheduled tasks, see [[Scheduled tasks]]
==Running cron for several Moodle servers==
* Tasks can run in parallel and processes use locking to prevent tasks from running at the same time which allows cron to be triggered from multiple web servers that serve the same Moodle instance.

* If you are running different Moodle instances on the same server, then each Moodle instance needs a cron job. (Even a single Apache web server can run different Moodle instances on different domains by using its virtual hosts capability [https://httpd.apache.org/docs/2.2/vhosts/index.html https://httpd.apache.org/docs/2.2/vhosts/index.html].)
== Debugging Scheduled Tasks ==
Sometimes, a particular cron task may not be working correctly. In Moodle versions before 2.7 - any cron task that was throwing exceptions would prevent the rest of cron from running. The only way to monitor if cron was completing each time, was to add some automated checking of the output of running cron (e.g. searching for the string "Cron completed at ").

In Moodle 2.7 and later, a single failing scheduled task will not prevent the remaining tasks from completing. When any single scheduled task fails, it is marked as a failure, and scheduled to be reattempted. If the task keeps failing, the next scheduled time will be backed off until it is attempted at most once every 24 hours. But checking the [[Scheduled tasks]] admin page, you can see if any task is currently failing (it will have a non-zero fail delay - which is the number of seconds to wait before reattempting a failed task). A simple way to debug a failing task, is to run it immediately using the [[Administration via command line#Scheduled_tasks|cli scheduled task runner]] and monitor the output.
== Logging and monitoring ==
Ideally you should also be logging the output of cron somewhere and monitoring it for issues. You can monitor the overall status of cron to make sure there are no errors by visiting:

Site administration / Reports / System status (/report/status/index.php)

You can also wire this status report up to tools like Icinga / Nagios using the Check API (https://docs.moodle.org/dev/Check_API) cli commands or with the help of plugins like https://github.com/catalyst/moodle-tool_heartbeat.

<code sh>
/admin/cli/checks.php
</code>

If there are errors then you can get more details for recently run tasks from the Logs column on the Scheduled task page, but this won't show ad hoc task failures:

Site administration / Server / Tasks / Scheduled tasks (/admin/tool/task/scheduledtasks.php)

To see ad hoc task failures you either need to rerun the task manually yourself and see the errors, or you need to have already collected the logs for review. For a Moodle running on a single box you could log to a simple log file, or for a cluster you might want to use syslogd or similar, e.g.:
<pre>
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php 2>&1 | /usr/bin/logger ...
</pre>
== Low latency adhoc tasks ==
Each time cron is run, after the scheduled tasks the ad hoc tasks are also run. While scheduled tasks can run at most once a minute, ad hoc tasks can be queued at any moment, and generally you want them processed as soon as possible and to not have to wait for the scheduled task to run first. If you only run the normal admin/cli/cron.php then not only might it have to wait to process all the scheduled tasks first, if it has already finished you will have to wait until the next minute for cron to start again for it to be processed.

Instead you can run one or more dedicated ad hoc task processors which run in parallel to the main cron process.
<pre>
* * * * * /usr/bin/php /path/to/moodle/admin/cli/adhoc_task.php --execute --keep-alive=59
* * * * * /usr/bin/php /path/to/moodle/admin/cli/adhoc_task.php --execute --keep-alive=59
...
</pre>
Starting from Moodle 3.9 the—keep-alive option runs like a daemon so when the queue is empty rather than exiting it waits for new tasks to be queued so it can start processing as soon as possible.
== Scaling up cron with multiple processes ==
As your site grows many of the scheduled tasks will take longer to complete, and also there will be more ad hoc tasks queued which need to be processed. The cron system is designed to work in parallel but each individual process can only process one task at a time so you must run multiple cron cli's. You can generally run a fairly high number of cron processes on a dedicated cron instance before needing to run multiple cron instances. To run more than one process simply spawn multiple cron processes each minute:

* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php
* * * * * /usr/bin/php /path/to/moodle/admin/cli/cron.php
⋮
* * * * * /usr/bin/php /path/to/moodle/admin/cli/adhoc_task.php --execute --keep-alive=59
* * * * * /usr/bin/php /path/to/moodle/admin/cli/adhoc_task.php --execute --keep-alive=59
* * * * * /usr/bin/php /path/to/moodle/admin/cli/adhoc_task.php --execute --keep-alive=59
⋮

It can be especially important to increase the number of adhoc_task.php processes as certain plugins and systems can generate very large numbers of ad hoc tasks, or tasks that can take a long time to process. Especially tasks like document conversions and automated backups can build up more quickly than they are processed if they are left on default settings.

By default only 3 scheduled tasks and 3 ad hoc tasks can be run concurrently so as you add more processes you need to increase the level of allowed concurrency:

Site administration > Server > Tasks > Task processing

Or in <code>config.php</code>:

<syntaxhighlight lang="php">
$CFG->task_scheduled_concurrency_limit = 20; // Defaults to 3
$CFG->task_adhoc_concurrency_limit = 50; // Defaults to 3
</syntaxhighlight>

Whatever you set these to make sure the server(s) hosting them can comfortably handle this many processes. Often the bottleneck will be a shared service, usually the database.

You may find that certain types of very long running tasks will consume all the available task processes which means no other tasks will run. e.g. if you have 5 cli processes, but in the task queue there are 20 ad hoc tasks for an automated backup, each of which will take ten minutes to complete, then very quickly all 5 processes will be consumed by backups and nothing else. Other small very fast and light tasks like a document conversion or forum emails will not get sent until the backups are complete and a process frees up. To manage this you can limit the concurrency of specific types of ad hoc tasks. A good rule of thumb is that if all of the 'heavy' tasks consume all of their own limits then you should still have another few processes standing by on idle waiting for anything else which may be added to the queue.

Automated backups are the worst known offender, so hypothetically if you are running 50 ad hoc task processes concurrently a reasonable restriction might be to cap the backups to consume no more than half of those processes, ie 25 at most:

In <code>config.php</code>:

<syntaxhighlight lang="php">
$CFG->task_concurrency_limit = [
'core\task\course_backup_task' => 25,
'core_course\task\course_delete_modules' => 5,
];
</syntaxhighlight>

==See also==
* [[Scheduled tasks]]
* [http://en.wikipedia.org/wiki/Cron Wikipedia article on cron function]
* MDL-50694 - Cron message "The operation timed out while waiting for a lock" isn't really an error
Forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=139263#p609060 How to log the output of a Scheduled Task on Windows] - this discussion explains a nice trick that can be very useful when you are experiencing problems with your Windows Scheduled Task and you need to log the output of the Scheduled Task to a log file.
[[es:Cron]]
[[fr:Cron]]
[[ja:Cron]]
[[de:Cron-Job]]

Report builder

2021-08-23T10:41:54Z

Leonstr: Changed <code> to <syntaxhighlight>

{{Workplace}}
= Overview =
Moodle Workplace provides a graphical custom reporting tool. Moodle Workplace custom reports are built using the report builder interface, which provides advanced customization options to administrators. System reports are used in every listing in Workplace: Dashboard, [[Programs]], [[Certifications]], [[Dynamic rules]], and even in the Report builder itself.

{{MediaPlayer | url = https://youtu.be/gvQ6WqFYGns | desc = Moodle Workplace | Training | Report Builder}}

= Accessing the report builder =
The report builder can be made available to all users, and is accessed from the Workplace launcher. For instructions on granting access to a report, see the [[#Configuring_audience|configuring audience]] section below.

= Creating a custom report =
To create a new custom report, the administrator clicks the plus icon on the reports tab. Reports can use any data from their data sources, including data from the Workplace Datastore that contains historical information and snapshots of past events.

[[File:wp-rb-new-report.png]]

After selecting a data source for the new report, we can click on a column or drag it into the table to add it to the report. To use aggregation on any column, we just need to click on the "Select an aggregation for the column" icon and then we can select the kind of aggregation depending on the column data type.

== Limiting number of custom reports ==
A site administrator can restrict the number of custom reports that can be created per site/tenant by adding the following line(s) to the [[Configuration_file|site configuration]]:

<syntaxhighlight lang="php">
$CFG->tool_reportbuilder_limitsenabled = true;
$CFG->tool_reportbuilder_sitelimit = <VALUE>;
$CFG->tool_reportbuilder_tenantlimit = <VALUE>;
</syntaxhighlight>

Omitting this configuration, or setting <tt>$CFG->tool_reportbuilder_limitsenabled = false;</tt> indicates that no limit should be applied to the number of custom reports that can be created. Enabling limits and setting the values to 0 will disable the creation of custom reports. Note that a tenant limit cannot exceed a site limit.

== Disabling live editing in reports ==
For performance reasons a site administrator may consider disabling live editing of reports, that being the constant updating of report data while editing report content (columns, filters, conditions) by adding the following to the [[Configuration_file|site configuration]]:

<syntaxhighlight lang="php">
$CFG->tool_reportbuilder_liveediting = false;
</syntaxhighlight>

Omitting this configuration, or setting <tt>$CFG->tool_reportbuilder_liveediting = true;</tt> indicates that live editing is enabled.

= Conditions and Filters =
Clicking in the "Show/hide filters sidebar" icon on the right will expand the right panel that we can use to define conditions and filters and set the default sorting order. Using conditions, we can pre-filter the report for the users. Conditions cannot be changed in the viewing mode. In the filters tab, we can define filters and we can define the default sorting order using the last tab just by selecting and rearranging the available options.

[[File:wp-rb-conditions.png]]

= Preview report =
Finally the report can be previewed by clicking the "Switch to preview view" icon, and it displays as it would for the person viewing the report, including any conditions defined. Filters can be reset using the icon on each filter or all at once.

[[File:wp-rb-preview.png]]

= Configuring audience =
Any person with the capability to manage or view reports can view all custom reports defined in their tenant. It is possible to specify additional audiences of the report that will grant access to the reports to users within them. To specify which user audiences should be able to access a given report, navigate to the "Audience" tab when editing it. You can add as many audiences to the report as necessary. Currently supported types are as follows:

* [[Organisation_structure#Assigning_jobs|Organisation job assignments]]
* Users [[Assign_roles#System_context|assigned system roles]]
* [[Cohorts|Cohort]] members
* Manually selected users

To confirm which users now have access to the report, switch to the "Access" tab.

In addition to granting user access to reports, it is also possible to specify which users should be listed in any given report. To achieve this the "[[Report_builder_(Audience)|Relation to the report viewer]]" condition should be added to the report.

[[File:Report Builder Audiences.png]]

= Sending report results =
Custom reports can be created and scheduled to be sent out to specific audiences. From the manage custom reports page, navigate to the schedules tab of a report. Here, the administrator clicks the "New schedule" button and selects which report they would like to be sent. Various report formats are available to use for attached report data (CSV, Excel Spreadsheet, HTML, JSON, ODS, PDF), as well as recurrence options (send every weekday, month, etc). The administrator can also select which user should be used when sending the scheduled report. This allows the report to be sent to the audience as if it were being viewed by that user.

The recipients options allow the administrator to select which users should receive the report. All defined audiences for the current report are listed here for selection.

Finally, the message subject and content can be configured.

[[File:Report Builder Schedules.png]]

= Upgrading audience and schedules prior to 3.11 =
<p>[https://docs.moodle.org/dev/Moodle_Workplace_3.11_release_notes#3.11 Moodle Workplace 3.11] introduced some changes in the audience and schedules for Report Builder to support more types of audiences and link schedules to existing audiences.</p>

<p>Due to these improvements, audiences and schedules from versions prior to 3.11 need to be upgraded following this process:</p>
<ul>
<li><strong>Audiences</strong>: report audiences based on job department/position will be converted to the new "job" audience type.</li>
<li><strong>Schedules</strong>: New audiences will be automatically created for previously defined report schedule recipients for job department, position and manually added users. Each of these audiences will automatically be added to the new schedule as recipients.</li>
</ul>
<p>Note <strong>recipient emails are no longer supported in schedules</strong>. Where previous schedules used these, the person who created the schedule will receive an email notifying them of any changes made. The email will include a list of previous email recipients, with a link to this page. As an alternative to external email addresses, consider creating users with the [[No_login|No login]] authentication method.</p>

<p>The same process will be followed when [[Migrations#Report_Builder_audience_and_schedules_prior_to_3.11|importing Report Builder audience and schedules prior to 3.11 using the Migration tool]].</p>

= Shared reports =
After enabling [[Multi-tenancy#Shared_Space|Shared space]], users can create shared reports inside of it. These shared reports will be listed in the custom reports page in all tenants and will be marked with a "Shared space" label next to it.

This feature enables users to use the same report definition site-wide without duplicating the same reports in all tenants. It also allows to create cross-tenant reports. When a shared report is viewed from inside the tenant it only displays the users and entities from this tenant. When a shared report is viewed from Shared space it shows information from all tenants.

[[File:Shared reports - 02.png]]

Reports in the shared space can be shared with all tenants or be only accessible to users with access to the shared space.

== Creating a new shared report ==
Access the Shared space from the tenant switch dropdown, in the navigation bar. When inside the Shared space go to Report Builder in the Workplace launcher and create a new report as usual.

There's a setting to effectively share the report to make it available in other tenants. If this is not set, the report will be available only in the shared space (see the screenshot below).

[[File:Shared reports - 01.png]]