Configuring the Router

This page is intended to help systems administrators to correctly configure the Routing Engine created as a part of Moodle 4.5.

From Moodle 4.5 onwards, Moodle includes a Routing Engine which allows requests to be dynamically served without files in specific locations.

The use of these routes can help to provide nicer URLs, which are easier to remember and more user-friendly. This is also reported to assist with SEO ranking.

Configuration of the Moodle Router will be compulsory from Moodle 5.1 onwards.

The type of Router that Moodle uses is known as a Front Controller.

What the web server needs to do

In many cases a user will request a file which is available as requested on disk, for example if the user requests https://example.com/course/view.php?id=42 then this will relate to a file at /course/view.php.

However, in other cases, a user may be accessing a URL which does not directly relate to a file on disk, for example if the user requests https://example.com/course/42/manage then this must instead be handled by the Moodle Router.

The Moodle Router is accessed from the file, r.php, which is located in the main Moodle directory.

How to configure the web server

Moodle supports a wide range of web servers. The guidance here is general in nature and the configuration examples may not apply exactly to your circumstances.

Configuring Apache2

Without Root Access

The easiest way to configure Apache2 does not require root access. In the main moodle directory, open (or create) the .htaccess file. Add the following line to the start of the file (it may also work at other places in that file).

FallbackResource /r.php

The FallbackResource directive sets a handler for any URL that doesn't map to anything in your filesystem. The handler, r.php, is already present in the main moodle directory.

With Root Access

Changing the Apache2 configuration file requires root access. This may be worth the extra work because Apache indicates that using .htaccess instead of a configuration file will result in a performance hit. The location of the configuration fill may be found with the command httpd -V; if that doesn't work, common locations are given by Apache, and commands to find the location are given on stackoverflow. Part of the output of httpd -V is shown below.

 -D AP_HAVE_RELIABLE_PIPED_LOGS
 -D DYNAMIC_MODULE_LIMIT=256
 -D HTTPD_ROOT="/etc/apache2"
 -D SUEXEC_BIN="/usr/sbin/suexec"
 -D DEFAULT_PIDLOG="/var/run/apache2/httpd.pid"
 -D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
 -D DEFAULT_ERRORLOG="logs/error_log"
 -D AP_TYPES_CONFIG_FILE="conf/mime.types"
 -D SERVER_CONFIG_FILE="conf/httpd.conf"

The data in the two lines, HTTPD_ROOT, and SERVER_CONFIG_FILE, can be combined to give the location of httpd.conf, which in this case is /etc/apache2/conf/httpd.conf.

Apache2 can be configured to support the Moodle Router by specifying a FallbackResource in the Directory directive. If not already defined, also add the DirectoryIndex index.php directive directly above the FallbackResource directive to prevent HTTP 404 errors from occurring with the Moodle Router.

DocumentRoot /var/www/moodle/public
<Directory /var/www/moodle/public>
    AllowOverride None
    Require all granted
    DirectoryIndex index.php
    FallbackResource /r.php
</Directory>

The FallbackResource is relative to the DocumentRoot so if Moodle is in a sub-directory, the path will be relative to that root. The Require all granted directive allows unconditional access to authenticated users.

DocumentRoot /var/www/moodle/public
<Directory /var/www/moodle/public/moodle>
    AllowOverride None
    Require all granted
    DirectoryIndex index.php
    FallbackResource /moodle/r.php
</Directory>

Configuring Nginx

The nginx server supports the use of a try_files directive, which checks for existence of files in the specified order, using the first found file for processing.

location / {
    try_files $uri /r.php;
}

If your Moodle site is in a sub-directory, you will need to use a more specific location.

location /moodle/ {
  try_files $uri $uri/ /moodle/r.php;
}

If you host multiple Moodles then you may wish to use a case-sensitive regular expression match for the location:

location ~ ^/(?<sitepath>[^/]*)/ {
  try_files $uri $uri/ /$sitepath/r.php;
}

IIS

Note: The following instructions are untested. If you have knoweldge of IIS and can provide more accurate or up-to-date instructions, please do so.

Using the URL Rewriter module for IIS, you can create a Rewrite rule in your web.config file.

<rewrite>
    <rules>
        <rule name="Moodle" stopProcessing="true">
            <match url="^(.*)$" ignoreCase="false" />
            <conditions logicalGrouping="MatchAll">
                <add input="{REQUEST_FILENAME}" matchType="IsFile" ignoreCase="false" negate="true" />
            </conditions>
            <action type="Rewrite" url="r.php" appendQueryString="true" />
        </rule>
    </rules>
</rewrite>

Configuring Moodle

After successfully configuring the Router, you should inform Moodle that it is correctly configured by setting the following in your config.php

$CFG->routerconfigured = true;

To test the system, login to Moodle, open a course, and note the id number in the address bar, which is 42 in this example: https://moodle.example.com/course/view.php?id=42. Try entering the following in the address bar: https://moodle.example.com/my/course/42/manage. The "my" shouldn't have been in there, so this will generate a distinctive error page, like the following.

Remove the "my/" from the address and it should take you to the appropriate page.

Documentation