Maintenance Mode Plugin

Overview

The Maintenance Mode plugin enables system administrators to restrict access to the PteroCA Panel during system updates, database migrations, or emergency maintenance periods.

Features

• Comprehensive Access Control: Blocks all non-administrator access when enabled
• Administrator Access: Administrators (ROLE_ADMIN) retain full panel access
• Professional Maintenance Page: Clean, responsive design with configurable messaging
• Whitelisted Paths: Automatic access to login page and static assets
• HTTP 503 Response: Proper service unavailable status with retry header
• Configurable Settings: Customize title, message, and estimated completion time
• Audit Logging: All blocked access attempts are logged

Installation

GUI Installation (Recommended)

1. Go to Admin Panel → Plugins → Upload Plugin
2. Upload the downloaded ZIP file
3. The plugin will be automatically registered and ready to enable

Console Installation (Alternative)

If you prefer command-line installation:

# Register the plugin (if not already registered)
php bin/console plugin:reset maintenance-mode

# Enable the plugin
php bin/console plugin:enable maintenance-mode

# Clear cache
php bin/console cache:clear

Verify Installation

# Check plugin status
php bin/console plugin:list

# Should show maintenance-mode with status: enabled

Configuration

Access Configuration Panel

1. Log in as an administrator
2. Navigate to Admin → Plugins → Maintenance Mode → Configure
3. Adjust settings as needed

Available Settings

| Setting | Type | Default | Description | |---------|------|---------|-------------| | Enable Maintenance Mode | Boolean | false | Master toggle for maintenance mode | | Maintenance Page Title | String | "System Maintenance" | Title displayed on maintenance page | | Maintenance Message | String | "We are currently..." | Message shown to users | | Estimated Completion Time | String | "" | Optional completion time (e.g., "3:00 PM UTC") |

Enable Maintenance Mode

1. Set "Enable Maintenance Mode" to ON
2. Optionally customize the message and estimated completion time
3. Click Save

Result: All non-admin users will see the maintenance page. Administrators can still access the full panel.

Disable Maintenance Mode

1. Log in as administrator
2. Navigate to plugin configuration
3. Set "Enable Maintenance Mode" to OFF
4. Click Save

Result: Normal access restored for all users.

How It Works

Request Interception

When maintenance mode is enabled, the plugin intercepts all incoming requests and checks:

1. Is maintenance mode disabled? → Allow access
2. Is the requested path whitelisted? → Allow access
3. Is the user an administrator? → Allow access
4. Otherwise → Show maintenance page with HTTP 503 status

Whitelisted Paths

These paths remain accessible during maintenance:

• /login - Login page (administrators need access)
• /bundles/ - Static assets (CSS, JS from bundles)
• /build/ - Compiled frontend assets
• /uploads/ - Uploaded files
• /_wdt, /_profiler - Debug toolbar (dev environment)
• /favicon.ico, /robots.txt - Common files

Security

• Admin Detection: Uses Symfony's Security::isGranted('ROLE_ADMIN')
• Session Security: Existing authentication remains intact
• No Information Disclosure: Generic maintenance message
• Audit Trail: All blocked access logged with user/path information

Performance Impact

• When Disabled: ~0.1ms overhead (single boolean check)
• When Enabled: ~1-2ms overhead (setting fetch + path/admin checks)
• Caching: Settings cached by PluginSettingService (24h TTL)

Troubleshooting

Plugin Not Loading

# Check plugin status
php bin/console plugin:list

# If not registered, reset it
php bin/console plugin:reset maintenance-mode

# Enable it
php bin/console plugin:enable maintenance-mode

# Clear cache
php bin/console cache:clear

Maintenance Page Not Showing

1. Check if maintenance is enabled:

   • Go to Admin → Plugins → Maintenance Mode
   • Verify "Enable Maintenance Mode" is ON

2. Check logs:

   tail -100 /app/var/log/dev.log | grep -i maintenance
   

3. Clear cache:

   php bin/console cache:clear
   

Admin Can't Access Panel

• Maintenance mode should never block ROLE_ADMIN users
• If blocked, check user roles in database
• Verify /login path is accessible
• Check logs for authorization errors

Static Assets Not Loading

• Verify whitelisted paths include /bundles/, /build/, /uploads/
• Check browser console for 503 errors on assets
• Ensure maintenance page uses CDN for Bootstrap/Font Awesome

Uninstallation

# Disable the plugin
php bin/console plugin:disable maintenance-mode

# Remove plugin directory
rm -rf plugins/maintenance-mode

Note: Settings are preserved in the database even after disabling. To completely remove, use:

php bin/console plugin:uninstall maintenance-mode

Development

Modifying the Plugin

1. Make changes to plugin files
2. Set correct ownership (if needed):

   chown -R www-data:www-data /app/plugins/maintenance-mode
   

3. Clear cache:

   php bin/console cache:clear
   

Debugging

Enable debug mode in .env:

APP_ENV=dev
APP_DEBUG=true

View logs:

tail -f /app/var/log/dev.log

License

MIT License - Same as PteroCA Panel

Support

For issues or questions:

• Check logs: /app/var/log/dev.log
• Review this README
• Contact PteroCA support team

Version History

1.0.0 (2026-02-09)

• Initial release
• Maintenance mode with admin access
• Configurable maintenance page
• HTTP 503 response
• Audit logging
• Responsive design