<% set_title("Upgrading", product_name_long) %>


<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

To upgrade an existing installation to a new version of <%=vars.product_name_long%>,
follow these general steps:

1. Back up your current system.
1. Install the new version of the software.
1. Stop your cluster using the current software.
1. Restart the system using the new software.

In many cases, components running under the current version can be stopped selectively, then restarted under the new version
so that the cluster as a whole remains functional during the upgrade process; this is known as a "rolling upgrade."

In other cases, the entire system must be stopped in order to accomplish the upgrade,
which will require some downtime for your system.

See [Planning an Upgrade](upgrade_planning.html) to choose the upgrade scenario that best suits your implementation and to understand the resources
you will need to accomplish the upgrade. Then select the appropriate upgrade procedure for more detailed instructions that fit your specific needs.

## <a id="upgrade_details" class="no-quick-link"></a>Upgrade Details

-   **[Planning an Upgrade](upgrade_planning.html)**

    This section discusses the upgrade paths for various <%=vars.product_name_long%>
    versions, and it lists information you need to know before you begin
    the upgrade process.

-   **[Rolling Upgrade](upgrade_rolling.html)**

    A rolling upgrade allows you to keep your existing cluster running while you upgrade your members gradually.

-   **[Offline Upgrade](upgrade_offline.html)**

    An offline upgrade can handle the widest variety of software versions and cluster configurations, but requires shutting down the entire
    system for at least a short time.

-   **[Upgrading Clients](upgrade_clients.html)**

    When you upgrade your <%=vars.product_name%> server software, you may need to update your client
    applications in order to maintain compatibility with the upgraded servers.

## <a id="upgrade_to_115" class="no-quick-link"></a>Upgrading to v1.15

For some users, issues regarding SSL protocols and their default values require a preparatory SSL protocol migration step when upgrading to <%=vars.product_name%> v1.15.
Please read the following section carefully to determine whether your system requires this additional SSL protocol migration step.

### <a id="is_ssl_protocol_migration_required" class="no-quick-link"></a>Does my System Require SSL Protocol Migration Before Upgrading to <%=vars.product_name%> v1.15?

To determine whether your system requires the SSL protocol migration preparatory step, see if your system meets both of the following conditions:

- If `ssl-endpoint-identification-enabled` is set to `true` AND<br/>
- If `ssl-protocols` is set to a value other than "any", that is, it specifies a list of specific protocols, but does not include "SSLv2Hello",

THEN your system requires the SSL protocol migration step.

**How do I determine my system's settings for the `ssl-endpoint-identification-enabled` and `ssl-protocols` properties?**

SSL properties may be set in properties files or on the gfsh command line. To determine the settings for these parameters,

- Check `gemfire.properties` and `gfsecurity.properties` for
`ssl-endpoint-identification-enabled=true`. Also look for `ssl-use-default-context=true`, which sets
`ssl-endpoint-identification-enabled=true`.

- Search system logs for these properties (using `grep`, for example).

## <a id="preparatory-migration" class="no-quick-link"></a>Preparatory SSL Protocol Migration

The preparatory SSL protocol migration process consists of replacing one property, `ssl-protocols`,
with two new properties, `ssl-client-protocols` and `ssl-server-protocols`, then removing the old
`ssl-protocols` definition. Perform this substitution in whatever way the original `ssl-protocols`
were defined: in `.properties` files or on a command line.

1. If your system is running JDK 8, upgrade to the latest version of JDK 8 before proceeding. This is necessary, even if you plan to
perform the optional JDK upgrade step to JDK 11 or JDK 17.
1. Shutdown a member (server or locator).
2. Install <%=vars.product_name%> 1.15.
3. Optionally install a new Java JDK.
4. Add security property `ssl-client-protocols` with the same definition as the old `ssl-protocols` property.
5. Add security property `ssl-server-protocols` with the same definition as the old `ssl-protocols` property PLUS "SSLv2Hello".
For example, if the original value of `ssl-protocols` is "TLSv1.2", then define
    - `ssl-client-protocols="TLSv1.2"`
    - `ssl-server-protocols="TLSv1.2,SSLv2Hello"`
6. Start the member.
7. Verify successful cluster join.
8. Repeat from step 1 for the next member.

Optionally, after your upgrade is complete, you may restore your original `ssl-protocols` property
and restart all your members to eliminate the `SSLv2Hello` protocol support.