| <% 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. |