Maintenance Mode
Maintenance mode is a feature that temporarily restricts access to your Moodle site, allowing only administrators to log in. This is essential during upgrades, database maintenance, server migrations, and other operations that could cause data inconsistency if users are actively using the site.
When to Use Maintenance Mode
- Moodle upgrades: Always enable maintenance mode before upgrading core or plugins
- Database maintenance: Schema changes, table repairs, large data migrations
- Server maintenance: OS updates, hardware changes, server migrations
- Backup operations: When creating consistent database snapshots
- Emergency situations: Security breaches, performance crises, data corruption
Enabling Maintenance Mode via the Web Interface
- Navigate to Site administration > Server > Maintenance mode
- Set Maintenance mode to Enable
- Optionally enter a Maintenance message in the text editor. This message is displayed to all non-admin users who try to access the site. You can include HTML formatting, estimated completion time, and contact information.
- Click Save changes
When maintenance mode is active:
- Non-admin users see the maintenance message (or a default message if none is set)
- Administrators can still log in and use the site normally
- Cron continues to run unless manually stopped
- Web service calls are rejected
Enabling Maintenance Mode via CLI
The CLI method is preferred, especially when the web interface may be unavailable or during scripted deployments:
# Enable maintenance mode
sudo -u www-data php admin/cli/maintenance.php --enable
# Enable with a custom message
sudo -u www-data php admin/cli/maintenance.php --enablelater=10
--message="Scheduled maintenance. The site will be back at 3:00 AM UTC."
# Enable maintenance mode to start in 10 minutes
sudo -u www-data php admin/cli/maintenance.php --enablelater=10
# Disable maintenance mode
sudo -u www-data php admin/cli/maintenance.php --disable
# Check current maintenance mode status
sudo -u www-data php admin/cli/maintenance.php
Maintenance Mode File Method
In situations where even the CLI is not working (e.g., database is down), you can create a file-based maintenance mode by creating a file called climaintenance.html in the moodledata directory:
echo "<h1>Site Under Maintenance</h1><p>We will be back soon.</p>" > /var/moodledata/climaintenance.html
Moodle checks for this file before loading any code, making it an effective emergency shutdown method. Remove the file to restore access:
rm /var/moodledata/climaintenance.html
This method is the most reliable way to take a Moodle site offline because it works even when the database is unreachable or the Moodle code is broken.
Custom Maintenance Page
You can create a professionally designed maintenance page by making the climaintenance.html file a full HTML document with CSS styling:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Maintenance - Your Institution</title>
<style>
body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
h1 { color: #333; }
p { color: #666; font-size: 18px; }
</style>
</head>
<body>
<h1>Scheduled Maintenance</h1>
<p>Our learning platform is currently undergoing scheduled maintenance.</p>
<p>Expected completion: 3:00 AM UTC</p>
<p>Contact: support@example.com</p>
</body>
</html>
Maintenance Mode in Automated Deployments
For automated deployment scripts, a typical maintenance workflow looks like:
#!/bin/bash
# Deployment script
cd /var/www/moodle
# 1. Enable maintenance mode
sudo -u www-data php admin/cli/maintenance.php --enable
# 2. Pull new code
git pull origin MOODLE_405_STABLE
# 3. Run upgrade
sudo -u www-data php admin/cli/upgrade.php --non-interactive
# 4. Purge caches
sudo -u www-data php admin/cli/purge_caches.php
# 5. Disable maintenance mode
sudo -u www-data php admin/cli/maintenance.php --disable
Important Considerations
- Active sessions: Users currently logged in are not immediately disconnected. They will see the maintenance page on their next request.
- Cron during maintenance: Cron continues to run during maintenance mode. If you need to stop cron (e.g., during database schema changes), temporarily disable the cron job.
- Mobile app: The Moodle mobile app will show an error when maintenance mode is active.
- Web services: API calls return an error response during maintenance mode.
- Duration: Keep maintenance windows as short as possible. Communicate expected duration to users in advance.