Brian Stansberry [
https://community.jboss.org/people/brian.stansberry] modified the
document:
"Single Installation Patching"
To view the document, visit:
https://community.jboss.org/docs/DOC-47500
--------------------------------------------------------------
This article outlines design notes for the single instance patching feature being
developed for AS 7.2.
The 7.2 version of the feature will be apply to apply a patch to a single installation of
the AS (i.e. a single unzip of the AS distribution.) That single installation may be being
used for a standalone server or for a managed domain Host Controller and servers. However,
the 7.2 version will not support coordinated patching by the patching tool of multiple
installation in a managed domain. The user can of course independently patch multiple
installation in a domain, coordinating the application of those patches themselves.
The basic patching process will consist of:
1. The user obtains a patch file.
2. The user uses the CLI tool to connect to a standalone server or Host Controller that is
running on the installation that is to be patched.1. The server or Host Controller may be
running in admin-only mode or running normally. However, some patches may not be able to
be applied if the target process isn't running in admin-only mode
3. The user invokes a command on the CLI providing the location of the patch file. The CLi
invokes an operation(s) on the target process telling it to stage the patch.
4. The target process stages the patch by applying the patch contents to the filesystem.1.
The changes made to the filesystem during staging should not affect the running operation
of the server. If this is not possible, the server should reject the patch with an error
message indicating that it needs to be placed in admin-only mode before applying the
patch.
5. The user uses the CLI tool to restart the target process. Upon restart the staged patch
is visible in the runtime.
Patches can also be rolled back:
1. The user can use the CLI tool to instruct the target process to revert a patch.
2. Patch reversion results in changes to the filesystem that are staged in the same manner
as what is done with a patch installation.1. The changes made to the filesystem during
patch rollback staging should not affect the running operation of the server. If this is
not possible, the server should reject the patch rollback with an error message indicating
that it needs to be placed in admin-only mode before rolling back the patch.
3. The user uses the CLI tool to restart the target process. Upon restart the rolled back
patch is no longer visible in the runtime.
h1. Patch File
A patch file is a zip archive that contains a patch.xml file that is used to describe the
patch along with the updated modules, OSGi bundles and miscellaneous files that comprise
the patch. It's structure is as follows:
+ META-INF
++ patch.xml
+ modules
++ patch modules in the same structure as they appear the modules dir in the normal AS
dist
+ bundles
++ patch bundles in the same structure as they appear the bundles dir in the normal AS
dist
+ misc
++ misc files that need to be updated, organized in a directory structure that matches the
directory structure of the AS dist
h3. The patch.xml File
The patch.xml file describes the patch. It includes basic information about the patch
along with metadata about the modules, bundles and misc files in the patch.
h5. Basic patch metadata
* The name of the patch
* The type of the patch (one-off vs cumulative, etc -- TODO list all)
* The version to which the patch applies
* A text description of the patch
* TODO others
h5. Module metadata
* The name of the module
* The slot of the module
* The hash of the module.xml file of the previous version of the module. Not present if
the relevant module did not exist in the version being patched.
h5. Removed module metadata
Identifies modules that were available in the version being patched but which should no
longer be accessible once the patch is applied
* The name of the removed module
* The slot of the removed module
h5. Bundle metadata
* TODO anything?
h5. Removed bundle metadata
Identifies bundles that were available in the version being patched but which should no
longer be accessible once the patch is applied
* The name of the removed bundle
h5. Misc file metadata
* The path of the misc file, relative to the root of the AS distribution
* The hash of the version of the file that was in the version being patched. Not present
if the relevant file did not exist in the version being patched.
* A boolean indicator as to whether the file is in active use by a non-admin-mode Host
Controller or server
h5. Removed misc file metadata
Identifies misc files that were available in the version being patched but which should no
longer be accessible once the patch is applied
* The path of the misc file, relative to the root of the AS distribution
* A boolean indicator as to whether the file is in active use by a non-admin-mode Host
Controller or server
h2. Patch Staging
The target process when it applies a patch will create a patches directory directly
underneath the root of the AS distribution. As with other directories, the location of
this directory can be controlled via a system property passed to the JVM at process
launch.
Before patch staging begins, a check is made as to whether the target process is in
admin-only mode. If it is not, and
h4. Modules
Patch modules will be staged by copying them to a patch-specific subdirectory of the
patches directory. Information about the location of this directory will be stored in a
location visible to the module loader used by JBoss Modules at boot. This patch-specific
subdirectory is not visible to the module loader currently in use by the target process.
TODO describe check for user-modified modules.
Information about removed modules will also be stored in a location visible to the boot
module loader at next boot.
h4. Bundles
Patch bundes will be staged by copying them to a patch-specific subdirectory of the
patches directory. This patch-specific subdirectory is not visible to the OSGi subsystem
currently in use by the target process.
Information about removed bundles will also be stored in a location visible to the OSGi
subsystem at next boot.
h4. Misc files
Misc files are staged by copying them directly to their normal location on the filesystem.
A copy of the existing file at that location will be stored in the patch-specific
subdirectory of the patches directory.
TODO describe check for user-modified misc files.
h2. Patch Application
TODO
h2. Rollback Staging
TODO
h2. Rollback Application
TODO
h2. Patch Generation Tool
* Accepts basic metadata along with the location of a distribution of the new version
along with a distribution of the old version* Also includes details on any misc files that
are expected to be in active use
* Generates a patch.xml file
* Can generate a full patch file
* Optional: Can be run from inside the bin/ dir of the full distribution of the new
version and if provided with the patch.xml file can generate a patch file from the
contents of the full dist* Idea here is the patch.xml file could be distributed as part of
the new version and the user could use it to generate patch
--------------------------------------------------------------
Comment by going to Community
[
https://community.jboss.org/docs/DOC-47500]
Create a new document in JBoss AS 7 Development at Community
[
https://community.jboss.org/choose-container!input.jspa?contentType=102&a...]