7.7 KiB
title, intro, redirect_from, versions, type, topics, shortTitle
| title | intro | redirect_from | versions | type | topics | shortTitle | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Enabling and scheduling maintenance mode | Some standard maintenance procedures, such as upgrading {% data variables.location.product_location %} or restoring backups, require the instance to be taken offline for normal use. |
|
|
how_to |
|
Configure maintenance mode |
About maintenance mode
Some types of operations require that you take {% data variables.location.product_location %} offline and put it into maintenance mode:
- Upgrading to a new version of {% data variables.product.prodname_ghe_server %}
- Increasing CPU, memory, or storage resources allocated to the virtual machine
- Migrating data from one virtual machine to another
- Restoring data from a {% data variables.product.prodname_enterprise_backup_utilities %} snapshot
- Troubleshooting certain types of critical application issues
We recommend that you schedule a maintenance window for at least 30 minutes in the future to give users time to prepare. When a maintenance window is scheduled, all users will see a banner when accessing the site.
When the instance is in maintenance mode, all normal HTTP and Git access is refused. This includes web and API requests, for which the appliance responds with status code 503 (Service Unavailable). Git fetch, clone, and push operations are also rejected with an error message indicating that the site is temporarily unavailable. In high availability configurations, Git replication will be paused. GitHub Actions jobs will not be executed. Visiting the site in a browser results in a maintenance page.
{% ifversion ip-exception-list %}
You can perform initial validation of your maintenance operation by configuring an IP exception list to allow access to {% data variables.location.product_location %} from only the IP addresses and ranges provided. Attempts to access {% data variables.location.product_location %} from IP addresses not specified on the IP exception list will receive a response consistent with those sent when the instance is in maintenance mode.
{% endif %}
Enabling maintenance mode immediately or scheduling a maintenance window for a later time
{% data reusables.enterprise_site_admin_settings.access-settings %} {% data reusables.enterprise_site_admin_settings.management-console %}
-
In the top navigation bar, click Maintenance.
-
Under "Enable and schedule", {% ifversion custom-maintenance-mode-message %}select Enable maintenance mode, then {% endif %}decide whether to enable maintenance mode immediately or to schedule a maintenance window for a future time.
- To enable maintenance mode immediately, select the dropdown menu and click now.
- To schedule a maintenance window for a future time, select the dropdown menu and click a start time. {% data reusables.enterprise_management_console.custom-maintenance-message %} {% ifversion custom-maintenance-mode-message %}1. When you're satisfied with the timing of the window and the optional message, click Save. If you selected "now", your instance will be put into maintenance mode immediately. {% else %}1. When you're satisfied with the timing of the window, select the checkbox next to "Enable maintenance mode". If you selected "now", your instance will be put into maintenance mode immediately.{% endif %}
{% ifversion ip-exception-list %}
Validating changes in maintenance mode using the IP exception list
The IP exception list provides controlled and restricted access to {% data variables.location.product_location %}, which is ideal for initial validation of server health following a maintenance operation. Once enabled, {% data variables.location.product_location %} will be taken out of maintenance mode and available only to the configured IP addresses. The maintenance mode checkbox will be updated to reflect the change in state.
If you re-enable maintenance mode, the IP exception list will be disabled and {% data variables.location.product_location %} will return to maintenance mode. If you just disable the IP exception list, {% data variables.location.product_location %} will return to normal operation.
You can also use a command-line utility to configure the IP exception list. For more information, see "AUTOTITLE" and "AUTOTITLE."
{% data reusables.enterprise_site_admin_settings.access-settings %} {% data reusables.enterprise_site_admin_settings.management-console %}
-
In the top navigation bar, click Maintenance, then confirm maintenance mode is already enabled.
-
Under "Enable and configure IP exception list", select Enable IP exception list.
-
To the right of the checkbox for enabling the list, type a valid list of space-separated IP addresses or CIDR blocks that should be allowed to access {% data variables.location.product_location %}. {% data reusables.enterprise_management_console.custom-maintenance-message %}
-
Click Save.
{% endif %}
Scheduling maintenance mode with the {% data variables.product.prodname_enterprise_api %}
You can schedule maintenance for different times or dates with the {% data variables.product.prodname_enterprise_api %}. For more information, see "AUTOTITLE."
Enabling or disabling maintenance mode for {% data variables.product.prodname_ghe_server %} via the CLI
With the ghe-maintenance utility, you can set or unset maintenance mode for a single instance of {% data variables.product.prodname_ghe_server %}.
$ ghe-maintenance -h
# Shows options
$ ghe-maintenance -q
# Queries the current mode
$ ghe-maintenance -s
# Sets maintenance mode
{%- ifversion custom-maintenance-mode-message %}
$ ghe-maintenance -s "MESSAGE"
# Sets maintenance mode with a custom message
$ ghe-maintenance -m "MESSAGE"
# Updates the custom message
{%- endif %}
$ ghe-maintenance -u
# Unsets maintenance mode
Enabling or disabling maintenance mode for all nodes in a cluster via the CLI
With the ghe-cluster-maintenance utility, you can set or unset maintenance mode for every node in a cluster.
$ ghe-cluster-maintenance -h
# Shows options
$ ghe-cluster-maintenance -q
# Queries the current mode
$ ghe-cluster-maintenance -s
# Sets maintenance mode
{%- ifversion custom-maintenance-mode-message %}
$ ghe-cluster-maintenance -s "MESSAGE"
# Sets maintenance mode with a custom message
$ ghe-cluster-maintenance -m "MESSAGE"
# Updates the custom message
{%- endif %}
$ ghe-cluster-maintenance -u
# Unsets maintenance mode