...

• Bugs, vulnerabilities and availability of patches are communicated with the SOS Change Management System.
• The article provides information about how to apply patches to the Controller.
  

  Display feature availability
  StartingFromRelease 2.3.0

• The article explains how to manually apply patches. For automated patching see JS7 - Automated Installation and Update.

...

• Patches are offered from .jar Java archive files or from .tar.gz tarball archive files.
• The same patch files are applied to Unix and Windows.
• Patch file names follow the scheme:
  • Unix, Windows: js7_controller.<release>-PATCH.<issue-key>.[jar|tar.gz]
  • The following placeholders are used:
    • release: The JS7 release number, see Releases.
    • issue-key: The issue key in the SOS Change Management System, for example: JS-1984.
  • Example:
    
    • Unix, Windows: js7_controller.2.2.3-PATCH.JS-1984.jar, js7_controller.2.2.3-PATCH.JS-1984.tar.gz
• Patch .tar.gz archive files
  • include one or more .jar files that hold patches.
  • include a directory hierarchy for .jar files:
    • controller/lib/patches

...

...

The Controller expects Java .jar libraries holding patches in the following locations:

• Unix
  • /opt/sos-berlin.com/js7/controller/lib/patches
• Windows
  • C:\Program Files\sos-berlin.com\js7\controller\lib\patches

The first part of the path can point to a different location. The lib/patches part is the same for any installation of a Controller.

...

Download Patches

Find the following examples for a patch:

...

Before applying patches users might want to verify the integrity and authenticity of downloaded patch files, see JS7 - Verifying releases.

Anchor
on_premises on_premises

Patches for Controller On Premises

The Controller expects Java .jar files holding patches in the following locations:

• Unix
  • /opt/sos-berlin.com/js7/controller/lib/patches
• Windows
  • C:\Program Files\sos-berlin.com\js7\controller\lib\patches

The paths noted above are specified during installation and can point to a different location.

...

The lib/patches part is the same for any installation of a Controller.

Applying Patches

Apply the following steps for to a Controller instance. If a Controller cluster is operated then these the steps have to be performed for all Controller instances.

The patch examples will not impact a Controller installation and are used for instructional purposes only. For details see JS-1984.

...

Note: The Controller has to be stopped before applying patches.

Applying Patch on Unix

Manual Patching

# invoke shell and switch to the user account that owns the Controller's home directory

# navigate to the targethome directory for patches
cd /opt/sos-berlin.com/js7/controller/lib/patches

# download the .jar patch file
curl https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.jar -O

# invoke shell and switch to the user account that owns the Controller's home directory

# navigate to the targethome directory for patches
cd /opt/sos-berlin.com/js7/controller/lib/patches

# download the .tar.gz patch archive
curl https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.tar.gz -O

# extract the .tar.gz patch archive that includes .jar files
tar -xvzfxvpozf js7_controller.2.2.3-PATCH.JS-1984.tar.gz

# remove the .tar.gz patch archive
rm js7_controller.2.2.3-PATCH.JS-1984.tar.gz

Automated Patching

# invoke shell and switch to the user account that owns the Controller's home directory

# download the .jar patch file
curl https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.jar -O

# apply the patch
./js7_install_controller.sh \
    --patch-jar=js7_controller.2.2.3-PATCH.JS-1984.jar \
    --patch=JS-1984 \
    --home=/opt/sos-berlin.com/js7/controller \
    --controller-id=controller

# invoke shell and switch to the user account that owns the Controller's home directory

# download the .tar.gz patch archive
curl https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.tar.gz -O

# apply the patch
./js7_install_controller.sh \
    --tarball=js7_controller.2.2.3-PATCH.JS-1984.tar.gz

...

 \
    --patch=JS-1984 \
    --home=/home/sos/controller \
    --controller-id=controller

Applying Patch on Windows

Manual Patching

@rem invoke Windows shell and switch to the user account that owns the Controller's home directory

@rem navigate to the targethome directory for patches
cd %ProgramFiles%\sos-berlin.com\js7\controller\<controller-id>\lib\patches

@rem download from URL https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.jar
@rem copy from download location (could be different from this example)
copy %USERPROFILE%\Downloads\js7_controller.2.2.3-PATCH.JS-1984.jar .

@rem invoke Windows shell and switch to the user account that owns the Controller's home directory

@rem navigate to the targethome directory for patches
cd %ProgramFiles%\sos-berlin.com\js7\controller\lib\patches

@rem download from URL https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.tar.gz
@rem copy from download location (could be different from this example)
copy %USERPROFILE%\Downloads\js7_controller.2.2.3-PATCH.JS-1984.tar.gz .

@rem extract the .tar.gz patch archive that includes .jar files
tar.exe -xfxzf js7_controller.2.2.3-PATCH.JS-1984.tar.gz
 
@rem remove the .tar.gz patch archive
del js7_controller.2.2.3-PATCH.JS-1984.tar.gz

Automated Patching

# invoke PowerShell and switch to the user account that owns the Controller's home directory

# download from URL
Invoke-WebRequest `
    -Uri 'https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.jar' `
    -Outfile js7_controller.2.2.3-PATCH.JS-1984.jar

# apply patch
./Install-JS7Controller.ps1 `
    -PatchJar js7_controller.2.2.3-PATCH.JS-1984.jar `
    -Patch JS-1984 `
    -HomeDir $env:ProgramFiles\sos-berlin.com\js7\controller `
    -ControllerId controller `
    -HttpPort 4444

# invoke PowerShell and switch to the user account that owns the Controller's home directory

# download from URL
Invoke-WebRequest `
    -Uri 'https://download.sos-berlin.com/patches/2.2.3-patch/js7_controller.2.2.3-PATCH.JS-1984.tar.gz' `
    -Outfile js7_controller.2.2.3-PATCH.JS-1984.tar.gz
 
# apply patch
./Install-JS7Controller.ps1 `
    -Tarball js7_controller.2.2.3-PATCH.JS-1984.tar.gz `
    -Patch JS-1984 `
    -HomeDir $env:ProgramFiles\sos-berlin.com\js7\controller `
    -ControllerId controller `
    -HttpPort 4444

Notes

Note: The Controller instance has to be restarted to apply patches.

Note: Users are discouraged from using tools such as 7-Zip to extract the patch archive in case of manual patching. Instead, use the tools available from the OS as indicated by the examples. Do not create a sub-folder from the archive name but extract directly to the directory hierarchy as indicated above.

Hint: For automated rollout of patches see JS7 - Automated Installation and Update.

...

Removing Patches

Patches are automatically removed when a Controller release instance is updated or upgraded using the JS7 - Controller - Installation Using the Windows Graphical Installer or the installation scripts as indicated with JS7 - Automated Installation and Update.

...

Note: The Controller instance has to be stopped before patches are removed.

Anchor
docker_containers docker_containers

...

Patches for Controller Container

The Controller container expects Java .jar libraries files for patches in the following location:

• /var/sos-berlin.com/js7/controller/config/patches
• The /var/sos-berlin.com/js7/controller directory is typically mounted to a var volume when running the container: for details see the JS7 - Controller Installation for Containers article.
• If the sub-directory config/patches does not exist then it should be created before storing the patch file.
• If a patch is provided from a .tar.gz archive file then users should extract the archive and store the .jar files included to the config/patches sub-directory.

...

Applying Patches

On start-up the Controller container checks the directory noted above for the existence of .jar files and applies the patches - for details see the Patch Patches for Controller On Premises section above.

Patches are not applied persistently to a container. Therefore patch Patch files remain in place in the the /var/sos-berlin.com/js7/controller/config/patches sub-directory (typically mounted to a volume) as long as the patch is to be appliedfor the lifetime of the Controller release in use. Patches have to be removed if a newer release of the Controller is used.

Note: The Controller container has to be restarted to apply patches.

...

Removing Patches

Patches are removed by dropping the files in the config/patches sub-directory.

Patch files are not automatically removed when updating or upgrading the Controller image. If a newer Controller release is used then this includes any fixes provided by previous patches. Users have to remove patch files when applying new releases.

Note: The Controller container has to be restarted to apply make removal of patches effective.