Enable or disable maintenance mode
The following guide refers to a standard maintenance mode page. If you need to use a custom maintenance page, see Create the custom maintenance page topic.
Adobe Commerce and Magento Open Source use maintenance mode to disable bootstrapping. Disabling bootstrapping is helpful while you are maintaining, upgrading, or reconfiguring your site.
The application detects maintenance mode as follows:
-
If
var/.maintenance.flag
does not exist, maintenance mode is off and the application operates normally. -
Otherwise, maintenance mode is on unless
var/.maintenance.ip
exists.var/.maintenance.ip
can contain a list of IP addresses. If an entry point is accessed using HTTP and the client IP address corresponds to one of the entries in that list, then maintenance mode is off.
Install the application
Before you use this command to enable or disable maintenance mode, you must install the application.
Enable or disable maintenance mode
Use the magento maintenance
CLI command to enable or disable maintenance mode.
Command usage:
bin/magento maintenance:enable [--ip=<ip address> ... --ip=<ip address>] | [ip=none]
bin/magento maintenance:disable [--ip=<ip address> ... --ip=<ip address>] | [ip=none]
bin/magento maintenance:status
The --ip=<ip address>
option is an IP address to exempt from maintenance mode (for example, developers doing the maintenance). To exempt more than one IP address in the same command, use the option multiple times.
--ip=<ip address>
with magento maintenance:disable
saves the list of IPs for later use. To clear the list of exempt IPs, use magento maintenance:enable --ip=none
or see Maintain the list of exempt IP addresses.The bin/magento maintenance:status
command displays the status of maintenance mode.
For example, to enable maintenance mode with no IP address exemptions:
bin/magento maintenance:enable
To enable maintenance mode for all clients except 192.0.2.10 and 192.0.2.11:
bin/magento maintenance:enable --ip=192.0.2.10 --ip=192.0.2.11
After you place the application in maintenance mode, you must stop all message queue consumer processes.
One way to find these processes is to run the ps -ef | grep queue:consumers:start
command, and then run the kill <process_id>
command for each consumer. In a multiple node environment, repeat this task on each node.
Maintain the list of exempt IP addresses
To maintain the list of exempt IP addresses, you can either use the [--ip=<ip list>]
option in the preceding commands or you can use the following:
bin/magento maintenance:allow-ips <ip address> .. <ip address> [--none]
The <ip address> .. <ip address>
syntax is an optional space-delimited list of IP addresses to exempt.
The --none
option clears the list.
Multi-store setups
If you want to set up multiple stores, each with a different layout and localized content, pass the $_GET['skin']
parameter to the intended processor.
In the following example, we are using a 503
type error template file, which requires localized content.
The constructor of the Error_Processor
class accepts a skin
GET parameter to change the layout:
if (isset($_GET['skin'])) {
$this->_setSkin($_GET['skin']);
}
This can also be added to a rewrite rule in the .htaccess
file that appends a skin
parameter to the URL.
$_GET[‘skin’] parameter
To use the skin
parameter:
-
Check if the
.maintenance.flag
exists. -
Note the host address, that refers to the
HTTP_HOST
, or any other variable such as ENV variables. -
Check if the
skin
parameter exists. -
Set the parameter by using the rewrite rules below.
Here are some examples of rewrite rules:
- RewriteCond
%{DOCUMENT_ROOT}/var/.maintenance.flag -f
- RewriteCond
%{HTTP_HOST} ^sub.example.com$
- RewriteCond
%{QUERY_STRING} !(^|&)skin=sub(&|$)
[NC] - RewriteRule
^ %{REQUEST_URI}?skin=sub
[L]
- RewriteCond
-
Copy the following files:
pub/errors/default/503.phtml
topub/errors/sub/503.phtml
pub/errors/default/css/styles.css
topub/errors/sub/styles.css
-
Edit these files to provide localized content in the
503.phtml
file and custom styling in thestyles.css
file.Ensure your paths point to your
errors
directory. The directory name must match the URL parameter indicated in theRewriteRule
. In the previous example, thesub
directory is used, which is specified as a parameter in theRewriteRule
(skin=sub
)