Brian Stansberry [https://community.jboss.org/people/brian.stansberry] modified the document: "Experimenting with Single Installation Patching" To view the document, visit: https://community.jboss.org/docs/DOC-47969 -------------------------------------------------------------- Instructions for experimenting with the " https://community.jboss.org/docs/DOC-47500 Single Installation Patching" feature currently being developed. These instructions assume basic git knowledge and knowledge of how to work with the AS 7 code base. See " https://community.jboss.org/docs/DOC-15596 Hacking on JBoss AS7" for basic background. h2. Getting and Building the Source The patching feature is currently on a topic branch being maintained by Emanuel Muckenhuber. Until that branch is merged into master: 1) If you haven't already, clone the AS repo $ git clone git://github.com/jbossas/jboss-as.git 2) Add Emanuel's github repo as a remote $ cd jboss-as $ git remote add -f emanuel git://github.com/emuckenhuber/jboss-as.git 3) Checkout a new branch "patches-master" to track Emanuel's branch $ git checkout -t emanuel/patches-master 4) Build the AS $ ./build.sh add the -DskipTests option to skip running tests if you want the build to go a bit faster. h3. Generating Patches To generate a patch, you'll need 5 things: 1. An unzipped AS distribution representing the AS release being patched. This is the "applies-to-dist". This can be any AS7 release distribution, or the output of any successful build of the AS7 codebase since 7.1.0.Final was released. (Even earlier would probably work fine.) 2. An unzipped AS distribution representing the "patched" AS release. This is the "updated-dist". This is a distribution built from code that is newer than whatever went into the "applies-to" distribution. It can be a later release or build, or even the same distribution as the "applies-to-dist" that you've manually modified in some fashion. 3. An AS distribution you built following the instructions in the "Getting and Building the Source" section above. The patch generation tool is included in this distribution. If the distribution you are using for the "updated-dist" was built in that manner, then you can use it; you don't need a separate distribution. At some point we'll distribute the patch generation tool as a separate distribution, but for now it's simplest just to use an AS distribution. In the rest of this section, we'll refer to this as the "patch generation tool distribution." 4. A patch-config.xml file providing instructions about how to create the patch. See details below. 5. The filesystem location where you want the patch file to be written (including the name of the file.) To run the patch generation tool: $ cd /root/of/the/patch/generation/tool/distribution $ java -jar jboss-modules.jar -mp modules org.jboss.as.patching.generator --help INFO  [org.jboss.modules] JBoss Modules version 1.1.3.GA Usage: patch-gen.sh [args...] where args include:     --applies-to-dist=<file>  Filesystem path of a pristine unzip of                               the distribution of the version of the                               software to which the generated patch                               applies     -h, --help                Display this message and exit     --output-file=<file>      Filesystem location to which the                               generated patch file should be written     --patch-config=<file>     Filesystem path of the patch generation                               configuration file to use     --updated-dist=<file>     Filesystem path of a pristine unzip of                               a distribution of software which                               contains the changes that should be                               incorporated in the patch     -v, --version             Print version and exit To actually run the patch generation tool and not just get help output, you will need to append the --applies-to-dist, --updated-dist, --patch-config and --output-file arguments described above to the process launch command (instead of --help), with the appropriate value for each included. The patch-gen tool will attempt to use default values for --applies-to-dist, --updated-dist and --output-file, so only --patch-config absolutely needs to be specified. * Default for --updated-dist is the current working dir, or its parent if the current working dir is named bin/. The assumption here is the patch generation tool is itself being run from the --updated-dist (which is the newest dist and thus will have the newest version of the tool). The tool does a couple basic sanity checks to verify that the working dir is actually an AS distribution. If those sanity checks don't pass, the patch generation will fail with a message indicating --updated-dist needs to be specified. * Default for --applies-to-dist can be a sibling of the root of --applies-to-dist, named the same as the applies-to-version in the patch-config.xml. * Default for --output-file can be <name-of-patch-as-specified-in-patch-config>.par in the current working dir. The java command above is pretty lengthy, so we've written a shell script that does the same thing. In the source code it can be found at patching/src/main/resources/patch-gen.sh. Copy that to the bin/ dir of the patch generation tool distribution and then you can get the output above by simply doing: $ bin/patch-gen.sh --help h4. Methods of Patch Generation There are two basic methods of patch generation. Which the tool should use is declared in the patch-config.xml file: * generate-by-diff: The patch generation tool itself compares the contents of the --applies-to-dist and the --updated-dist and creates a patch. This is most useful for CP patches. +TODO for one-off patches allow an option where the diffing algorithm ignore will timestamps as described by Jeff Mesnil (http://https://community.jboss.org/wiki/SingleInstallationPatching#commen... * specified-content: The patch-config.xml file declares in detail what modules, bundles and misc files are to be added, updated or removed via the patch. This is most useful for one-off patches where the patch author knows what has changed. h4. The patch-config.xml File The patch-config.xml file provides basic metadata about the patch, along with instructions on how to generate it. The person preparing the patch creates the patch-config.xml file. +Note: the file doesn't have to be named patch-config.xml; it can be named anything.+ The simplest way to describe the file is to show a couple of examples. The full xsd for the file can be found in the AS source dist at patching/src/main/resources/patch-config.xsd. An example patch-config file for a generate-by-diff patch: <?xml version='1.0' encoding='UTF-8'?> <patch-config xmlns="urn:jboss:patch-config:1.0">     <name>6.1.0-to-6.1.1</name>     <description>Cumulative patch to move from EAP 6.1.0.GA to EAP 6.1.1.GA</description>     <cumulative applies-to-version="EAP 6.1.0.GA" resulting-version="EAP 6.1.1.GA"/>     <generate-by-diff/> </patch-config> An example patch-config file for a specified-content patch: <?xml version='1.0' encoding='UTF-8'?> <patch-config xmlns="urn:jboss:patch-config:1.0">     <name>JBPAPP6-123</name>     <description>One off patch to fix JBPAPP6-123</description>     <one-off>         <applies-to-version>EAP 6.1.0.GA</applies-to-version>     </one-off>     <specified-content>         <modules>             <added-module name="org.jboss.as.foo" />             <updated-module name="org.jboss.as.bar" slot="eap"/>             <removed-module name="org.jboss.as.fubar" />         </modules>         <misc-files>             <updated-misc-content path="bin/standalone.sh" />             <updated-misc-content path="bin/standalone.bat" />         </misc-files>     </specified-content> </patch-config> h3. Applying Patches Only an AS release that includes the patching feature can be patched using the patching tool. So, that means you can only experiment with applying patches to an AS distribution you built following the instructions in the "Getting and Building the Source" section above. That limits things a bit as far as what patches you can try to apply; for example you couldn't generate a patch that represents the difference between 7.1.2.Final and 7.1.3.Final and then apply it to 7.1.2.Final. To apply a patch, you need: 1. A patch file, prepared as described in the "Generating Patches" section. 2. An unzipped AS distribution that represents the "applies-to" distribution. This can be the exact same "applies-to" distribution you used when creating the patch, or, if you want to experiment with how the patch tool deals with the (typical) situation where the user has in some way modified a standard AS version, you can make some sort of modification. We use the standard AS CLI tool to provide the user interface for the patch application tool. To see how to apply the patch, cd into the root of the installation being patched, launch the CLI and get the help for the "patch" command: $ bin/jboss-cli.sh -c [standalone@localhost:9999 /] patch --help SYNOPSIS     patch       <action> <action_arguments>*       [--override-all]       [--override-modules]       [--override=path(,path)*]       [--preserve=path(,path)*]       [--host=<host>]           where <action> can be   apply           - apply a patch   info            - information about the installed patches   rollback        - rollback a patch that has been applied           and <action_arguments> depends on the <action> ACTION: apply    Apply a patch    .... h3. This document won't include any more details on actually executing the patch command. Part of the goal of experimenting with it is to see if the --help output is adequate for users to understand what to do. The patch command only stages the patch (i.e. modifies the filesystem in a way that should not impact the running target process.) To actually have the patch take effect in the runtime, the target process needs to be restarted: [standalone@localhost:9999 /] :shutdown(restart=true) {"outcome" => "success"} Note that simply reloading the target process (using the :reload operation) is insufficient. +TODO add options to the patch command to automatically restart the process if staging is successful.+ h3. The patch info The patch info shows all currently active patches. In case there is no cumulative patch active it will return "base". [standalone@localhost:9999 /] patch info {     "outcome" : "success",     "result" : {         "cumulative" : "6.1.0-to-6.1.1",         "patches" : [ "JBPAPP6-123" ]     } } h3. Conflict resolution Conflict dection is run for both applying and rolling back patches. In case conflicts are detected and the patch operation will fail and return all found conflicts as part of the failure-description. Since modules are not directly touched there is only a single swtich to ignore those (--override-modules). h3. Following Progress The patching feature is still under active development, so if you want update your build and see what's new: 1) cd into the git repo you cloned in step 1) of "Getting and Building the Source" above. 2) Pull down the latest $ git fetch emanuel 3) Make sure you have a clean repo $ git status 4) Rebase your branch onto the latest $ git checkout patches-master $ git rebase emanuel/patches-master 5) Build again -------------------------------------------------------------- Comment by going to Community [https://community.jboss.org/docs/DOC-47969] Create a new document in JBoss AS 7 Development at Community [https://community.jboss.org/choose-container!input.jspa?contentType=102&a...]