ISPN-11785 server patching docs

cli/cli-client/src/main/resources/help/patch.adoc

@@ -2,11 +2,17 @@ PATCH(1)
 ========
 :doctype: manpage
 
-
 NAME
 ----
-patch - manages ${infinispan.brand.name} server patches.
+patch - manages server patches.
 
+DESCRIPTION
+-----------
+List, describe, install, rollback, and create server patches.
+
+Patches are zip archive files that contain artifacts to upgrade servers and
+resolve issues or add new features. Patches can apply target versions to
+multiple server installations with different versions.
 
 SYNOPSIS
 --------
@@ -21,42 +27,25 @@ SYNOPSIS
 *patch create* 'patch-file' 'target-server' 'source-server-1' ['source-server-2'...]
 
 
-DESCRIPTION
------------
-Manage (list, describe, install, rollback, create) ${infinispan.brand.name} server patches.
-Server patches contain a number of artifacts that upgrade a server in order to resolve issues or add new features and is
-distributed as a zip archive.
-A single server patch can be used to upgrade multiple server source versions to a specific target version.
-
-
-COMMAND SYNOPSIS
-----------------
-
-List patches installed on a server
-
-*patch ls*::
-Lists the patches currently installed on a server in order of installation.
-
-Install a patch on a server
-
-*patch install* 'patch-file'::
-Installs 'patch-file' on a server in the current directory.
-It is possible to specify a path to the server where the patch should be installed.
+PATCH LIST OPTIONS
+------------------
 
-Describe the contents of a patch archive file
+*--server*='path/to/server'::
+Sets the path to a target server outside the current server home directory.
 
-*patch describe* 'patch-file'::
-Describes the contents of the specified 'patch-file', i.e. the target version and the list of source versions that are supported.
+*-v, --verbose*::
+Shows the content of each installed patch, including information about
+individual files.
 
-Create a patch file
 
-*patch create* 'patch-file' 'target-server' 'source-server-1' ['source-server-2'...]::
-Creates a patch file
+PATCH INSTALL OPTIONS
+---------------------
 
-Rollback patches
+*--dry-run*::
+Shows the operations that the patch peforms without applying any changes.
 
-*patch rollback*::
-Rolls back the patch installed last (use the *patch ls* command to show the patches in the order they've been applied)
+*--server*='path/to/server'::
+Sets the path to a target server outside the current server home directory.
 
 
 PATCH DESCRIBE OPTIONS
@@ -66,38 +55,41 @@ PATCH DESCRIBE OPTIONS
 Shows the content of the patch, including information about individual files
 
 
-PATCH LIST OPTIONS
-------------------
+PATCH ROLLBACK OPTIONS
+----------------------
 
-*--server*='path-to-server'::
-The path to the server if it is in a different location than the current 'ISPN_HOME'
+*--dry-run*::
+Shows the operations that the patch peforms without applying any changes.
 
-*-v, --verbose*::
-Shows the content of each installed patch, including information about individual files
+*--server*='path/to/server'::
+Sets the path to a target server outside the current server home directory.
 
 
 PATCH CREATE OPTIONS
 --------------------
 
 *-q, --qualifier*='name'::
-Specifies a description qualifier string for the patch, e.g. 'one-off for issue nnnn'
+Specifies a descriptive qualifier string for the patch; for example, 'one-off for issue nnnn'.
 
 
-PATCH INSTALL OPTIONS
----------------------
+EXAMPLES
+--------
 
-*--dry-run*::
-Shows the operations that will be performed but doesn't actually apply them
+`patch ls` +
+Lists the patches currently installed on a server in order of installation.
 
-*--server*='path-to-server'::
-The path to the server if it is in a different location than the current 'ISPN_HOME'
+`patch install mypatch.zip` +
+Installs "mypatch.zip" on a server in the current directory.
 
+`patch install mypatch.zip --server=/path/to/server/home` +
+Installs "mypatch.zip" on a server in a different directory.
 
-PATCH ROLLBACK OPTIONS
-----------------------
+`patch describe mypatch.zip` +
+Displays the target version and list of source versions for "mypatch.zip".
 
-*--dry-run*::
-Shows the operations that will be performed but doesn't actually apply them
+`patch create mypatch.zip 'target-server' 'source-server-1' ['source-server-2'...]` +
+Creates a patch file named "mypatch.zip" that uses the version of the target server and applies to the source server versions.
 
-*--server*='path-to-server'::
-The path to the server if it is in a different location than the current 'ISPN_HOME'
+`patch rollback` +
+Rolls back the last patch that was applied to a server and restores the
+previous version.

documentation/src/main/asciidoc/stories/assembly_cli_command_reference.adoc

@@ -30,6 +30,7 @@ include::{cli_help}/encoding.adoc[leveloffset=+1]
 include::{cli_help}/get.adoc[leveloffset=+1]
 include::{cli_help}/help.adoc[leveloffset=+1]
 include::{cli_help}/ls.adoc[leveloffset=+1]
+include::{cli_help}/patch.adoc[leveloffset=+1]
 include::{cli_help}/put.adoc[leveloffset=+1]
 include::{cli_help}/query.adoc[leveloffset=+1]
 include::{cli_help}/quit.adoc[leveloffset=+1]

documentation/src/main/asciidoc/stories/assembly_server_patching.adoc

@@ -0,0 +1,24 @@
+[id='patching']
+:context: server
+= Patching {brandname} Server Installations
+Install and manage patches for {brandname} server installations.
+
+You can apply patches to multiple {brandname} servers with different versions
+to upgrade to a desired target version. However, patches do not take effect if
+{brandname} servers are running. For this reason you install patches while
+servers are offline. If you want to upgrade {brandname} clusters without
+downtime, create a new cluster with the target version and perform a rolling
+upgrade to that version instead of patching.
+
+include::{topics}/ref_server_patches.adoc[leveloffset=+1]
+//Product only
+ifdef::productized[]
+include::{topics}/proc_server_downloading_patches.adoc[leveloffset=+1]
+endif::productized[]
+include::{topics}/proc_server_creating_patches.adoc[leveloffset=+1]
+include::{topics}/proc_server_installing_patches.adoc[leveloffset=+1]
+include::{topics}/proc_server_rolling_back_patches.adoc[leveloffset=+1]
+
+// Restore the parent context.
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

documentation/src/main/asciidoc/stories/assembly_server_quickstart.adoc

@@ -1,5 +1,5 @@
 [id='server_quickstart']
-:context: server_quickstart
+:context: server
 = Running {brandname} Servers
 Spin up {brandname} server instances that automatically form clusters. Learn
 how to create cache definitions to store your data.

documentation/src/main/asciidoc/stories/assembly_server_rolling_upgrades.adoc

@@ -1,6 +1,6 @@
 [id='rolling_server_upgrades']
 :context: upgrade
-= Upgrading {brandname} Servers
+= Performing Rolling Upgrades for {brandname} Servers
 Perform rolling upgrades of your {brandname} clusters to change between
 versions without downtime or data loss. Rolling upgrades migrate both your
 {brandname} servers and your data to the target version over Hot Rod.

documentation/src/main/asciidoc/titles/server/stories.adoc

@@ -8,3 +8,4 @@ include::{stories}/assembly_server_monitoring.adoc[leveloffset=+1]
 include::{stories}/assembly_server_security.adoc[leveloffset=+1]
 include::{stories}/assembly_server_remote_execution.adoc[leveloffset=+1]
 include::{stories}/assembly_server_rolling_upgrades.adoc[leveloffset=+1]
+include::{stories}/assembly_server_patching.adoc[leveloffset=+1]

documentation/src/main/asciidoc/titles/upgrading/stories.adoc

@@ -3,4 +3,5 @@
 
 include::{stories}/assembly_upgrading.adoc[leveloffset=+1]
 include::{stories}/assembly_server_rolling_upgrades.adoc[leveloffset=+1]
+include::{stories}/assembly_server_patching.adoc[leveloffset=+1]
 include::{stories}/assembly_migrating_data.adoc[leveloffset=+1]

documentation/src/main/asciidoc/topics/con_cache_authorization.adoc

@@ -1,10 +1,10 @@
-[id='cache_authorization-{context}']
+[id='cache_authorization']
 = Cache Authorization
 {brandname} can restrict access to data by authorizing requests to perform
 cache operations.
 
 {brandname} maps identities, or Principals of type `java.security.Principal`,
-to security roles in your configuration. For example, a Principal named 
+to security roles in your configuration. For example, a Principal named
 `reader` maps to a security role named `reader`.
 
 {brandname} lets you assign permissions to the various roles to authorize cache

documentation/src/main/asciidoc/topics/proc_server_creating_patches.adoc

@@ -0,0 +1,89 @@
+[id='patching_create-{context}']
+= Creating Server Patches
+You can create patches for {brandname} servers from an existing server
+installation.
+
+ifndef::productized[]
+You can create patches for {brandname} servers starting from 10.1.7. You can
+patch any 10.1 or later server installation. However you cannot patch 9.4.x or
+earlier servers with 10.1.7 or later.
+
+You can also create patches that either upgrade or downgrade the {brandname}
+server version. For example, you can create a patch from version 10.1.7 and use
+it to upgrade version 10.1.5 or downgrade version 11.0.0.
+endif::productized[]
+ifdef::productized[]
+You can create patches for {brandname} servers starting from 8.0.1. You can
+patch 8.0 GA servers with 8.0.1. However you cannot patch 7.3.x or earlier
+servers with 8.0.1 or later.
+
+You can also create patches that either upgrade or downgrade the {brandname}
+server version. For example, you can create a patch from version 8.0.1 and use
+it to upgrade version 8.0 GA or downgrade a later version.
+
+[IMPORTANT]
+====
+{RedHat} supports patched server deployments only with patches that you
+download from the {portal}. {RedHat} does not support server patches that you
+create yourself.
+====
+endif::productized[]
+
+.Procedure
+
+. Navigate to `{server_home}` for a {brandname} server installation that has
+the target version for the patch you want to create.
+. Start the CLI.
++
+[source,options="nowrap",subs=attributes+]
+----
+$ bin/cli.sh
+[disconnected]>
+----
++
+. Use the `patch create` command to generate a patch archive and include the `-q` option with a meaningful qualifier to describe the patch.
++
+[source,options="nowrap",subs=attributes+]
+----
+[disconnected]> patch create -q "this is my test patch" path/to/mypatch.zip \
+path/to/target/server/home path/to/source/server/home
+----
++
+The preceding command generates a `.zip` archive in the specified directory.
+Paths are relative to `{server_home}` for the target server.
++
+[TIP]
+====
+Create single patches for multiple different {brandname} versions, for example:
+
+[source,options="nowrap",subs=attributes+]
+----
+[disconnected]> patch create -q "this is my test patch" path/to/mypatch.zip \
+path/to/target/server/home \
+path/to/source/server1/home path/to/source/server2/home
+----
+
+Where `server1` and `server2` are different {brandname} versions where you can
+install "mypatch.zip".
+====
++
+. Describe the generated patch archive.
++
+[source,options="nowrap",subs=attributes+]
+----
+[disconnected]> patch describe path/to/mypatch.zip
+
+{fullbrandname} patch target=$target_version(my test patch)  source=$source_version created=$timestamp
+----
++
+* `$target_version` is the {brandname} server version from which the patch was created.
+* `$source_version` is one or more {brandname} server versions to which you can apply the patch.
++
+You can apply patches to {brandname} servers that match the `$source_version`
+only. Attempting to apply patches to other versions results in the following
+exception:
++
+[source,options="nowrap",subs=attributes+]
+----
+java.lang.IllegalStateException: The supplied patch cannot be applied to `$source_version`
+----

documentation/src/main/asciidoc/topics/proc_server_downloading_patches.adoc

@@ -0,0 +1,40 @@
+[id='patching_download-{context}']
+= Downloading Server Patches
+Download patches that you can apply to {brandname} servers.
+
+.Procedure
+
+. Access the {portal}.
+. Download the appropriate {brandname} server patch from the link:{download_url}[software downloads section].
+. Open a terminal window and navigate to `{server_home}`.
+. Start the CLI.
++
+[source,options="nowrap",subs=attributes+]
+----
+$ bin/cli.sh
+[disconnected]>
+----
++
+. Describe the patch file you downloaded.
++
+[source,options="nowrap",subs=attributes+]
+----
+[disconnected]> patch describe /path/to/redhat-datagrid-$version-server-patch.zip
+{fullbrandname} patch target=$target_version source=$source_version created=$timestamp
+----
++
+* `$target_version` is the {brandname} version that applies when you install the patch on a server.
+* `$source_version` is one or more {brandname} server versions where you can install the patch.
+
+.Verification
+Use the checksum to verify the integrity of your download.
+
+. Run the `md5sum` or `sha256sum` command with the downloaded patch as the
+argument, for example:
++
+[source,options="nowrap",subs=attributes+]
+----
+$ sha256sum redhat-datagrid-$version-server-patch.zip
+----
++
+. Compare with the `MD5` or `SHA-256` checksum value on the {ProductName} *Software Details* page.