Error pages: Difference between revisions
(→Nginx) |
No edit summary |
||
| Line 26: | Line 26: | ||
For more security you can serve a 404 instead of a 403, and if you prefer you can reuse the themed 404 page below. | For more security you can serve a 404 instead of a 403, and if you prefer you can reuse the themed 404 page below. | ||
=== Apache === | === 403 in Apache === | ||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> | ||
DirectoryIndex disabled | DirectoryIndex disabled | ||
| Line 33: | Line 33: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
https://httpd.apache.org/docs/2.4/mod/mod_dir.html#directoryindex | https://httpd.apache.org/docs/2.4/mod/mod_dir.html#directoryindex | ||
=== Nginx === | === 403 in Nginx === | ||
<syntaxhighlight lang="nginx"> | <syntaxhighlight lang="nginx"> | ||
error_page 403 = /error/index.php | error_page 403 = /error/index.php | ||
| Line 39: | Line 39: | ||
error_page 403 = /error/index.php?code=404 | error_page 403 = /error/index.php?code=404 | ||
</syntaxhighlight>Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases. | </syntaxhighlight>Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases. | ||
== 404 File not found - Web server errors == | == 404 File not found - Web server errors == | ||
These are for errors which are technically outside of moodle such a 404 file not found at the server level rather than a 404 served by moodle. If you want to theme these then the approach is the same as you normally would for anything non Moodle, configure your web server to show a custom error page. But instead of writing your own, there is a built in Moodle error handler php script so they get the normal Moodle theme applied. You can see an example of what this error page looks like here: | These are for errors which are technically outside of moodle such a 404 file not found at the server level rather than a 404 served by moodle. If you want to theme these then the approach is the same as you normally would for anything non Moodle, configure your web server to show a custom error page. But instead of writing your own, there is a built in Moodle error handler php script so they get the normal Moodle theme applied. You can see an example of what this error page looks like here: | ||
https://moodle.org/errors/ | https://moodle.org/errors/ | ||
=== Apache === | === 404 in Apache === | ||
You can configure this using: | You can configure this using: | ||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> | ||
ErrorDocument 404 /error/index.php | ErrorDocument 404 /error/index.php | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== nginx === | === 404 in nginx === | ||
<syntaxhighlight lang="php"> | <syntaxhighlight lang="php"> | ||
error_page 404 = /error/index.php | error_page 404 = /error/index.php | ||
</syntaxhighlight>Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases. | </syntaxhighlight>Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases. | ||
== 502 Bad Gateway - Proxy / CDN issues == | == 502 Bad Gateway - Proxy / CDN issues == | ||
This means some upstream of your moodle server could not connect, ie nginx, varnish, a load balancer, proxy or CDN. | This means some upstream of your moodle server could not connect, ie nginx, varnish, a load balancer, proxy or CDN. | ||
Revision as of 03:38, 10 May 2023
This page is for any Moodle admins or developers who want to setup or customize error pages on their Moodle site. There is a variety of ways different errors can happen at different layers in a Moodle stack and because they each happen under different circumstance there cannot be a single way of handling them.
404 Normal Moodle errors and exceptions
These types of errors are things like you tried to access a course which no longer exists, or access a course which you don't have access to. Because these are "Moodle" pages they are themed correctly and normally there isn't much you want to do to improve them.
If you want to change the wording of the errors see:
https://docs.moodle.org/en/Language_customisation
If you want to change the theme, that is one and the same as normal theme customization:
https://docs.moodle.org/dev/Themes_overview
If a Moodle page throws an exception which isn't captured and results in an error page, and it will also helpfully, but blindly, link into this Moodle wiki where you might find more information on the error. This is great for sites in development or for admin type errors but typically less useful. You may want to divert users to your own support instead of off into a wiki page with generic Moodle information.
This links behavior can be changed and removed in your admin settings here:
/admin/settings.php?section=documentation
https://docs.moodle.org/dev/Exceptions
You can also simply hide the links using a capability too:
https://docs.moodle.org/38/en/Linking_Moodle_and_Docs#Removing_Moodle_Docs_links_for_teachers
403 Forbidden - Web server errors
For additional security you should not allow access to directory listings and you can also block access to certain files.
For more security you can serve a 404 instead of a 403, and if you prefer you can reuse the themed 404 page below.
403 in Apache
DirectoryIndex disabled
Options -Indexes
ErrorDocument 403 /error/index.php
https://httpd.apache.org/docs/2.4/mod/mod_dir.html#directoryindex
403 in Nginx
error_page 403 = /error/index.php
If you want to transform all 403 errors into 404's then:
error_page 403 = /error/index.php?code=404
Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases.
404 File not found - Web server errors
These are for errors which are technically outside of moodle such a 404 file not found at the server level rather than a 404 served by moodle. If you want to theme these then the approach is the same as you normally would for anything non Moodle, configure your web server to show a custom error page. But instead of writing your own, there is a built in Moodle error handler php script so they get the normal Moodle theme applied. You can see an example of what this error page looks like here:
404 in Apache
You can configure this using:
ErrorDocument 404 /error/index.php
404 in nginx
error_page 404 = /error/index.php
Note the '=' char above is important as it allows Moodle to reset the http headers to correctly serve the page in all cases.
502 Bad Gateway - Proxy / CDN issues
This means some upstream of your moodle server could not connect, ie nginx, varnish, a load balancer, proxy or CDN.
These error pages cannot be themed by at the application level and how to customize them depends on what is proxying moodle.
NOTE: It is very important if you do customize these to make sure you are not overriding the 40x and 50x error pages that Moodle may serve.
New in 4.0
These types of errors are more fundamental, and something has gone wrong so Moodle itself can't load, which means the error page can't access the database, MUC, or the language and strings API.
Previously these were difficult to style, and there are many edge cases to capture. This was fixed in this tracker:
https://tracker.moodle.org/browse/MDL-56041
These low level error pages resulted in the 'yellow box' and in 4.0 are now improved to more closely match the boost / bootstrap theme. You can customize this error page by editing this file:
error/plainpage.php
Note: this file cannot contain any Moodle API's and cannot link to files which are served by moodle such as theme files or plugin files. Ideally serve all dependencies such as css and even image inline.
503 Moodle under maintenance - Maintenance mode
During maintenance mode Moodle will serve a "503 Service Unavailable". This page can be customized:
https://docs.moodle.org/38/en/Maintenance_mode#CLI_maintenance_mode
