Patching InsightIQ

This section explains how the patching mechanism works and how to create new patches for InsightIQ. This section is indented for source code contributors.

If you’re looking for documentation about install/uninstall patches, please checkout the Scripts section.

How patching works

Where patches are stored

The patching mechanism creates a directory under the installation path of the InsightIQ source code. For example, if you deploy a new OVA of InsightIQ 4.1.1, the installation path is /usr/share/isilon/lib/python2.7/site-packages/insightiq. The directory created is named patches, for obvious reasons. The patches directory contains subdirectories; one for each patch currently installed.

The reason for putting the patches directory under the InsightIQ source code is it simplifies upgrades. When you ask the patching mechanism “what patches are currently installed” after an upgrade, it’ll always report that no patches are installed. In otherwords, upgrading InsightIQ removes all patches. There’s no way to avoid this; Python will overwrite the installation directory when upgrading the InsightIQ package.

Example file structure before InsightIQ upgrade:

insightiq
  \patches
    \patch-1234
    \patch-598
  \config
  \core
  features.py

Example file structure after InsightIQ upgrade:

insightiq
  \config
  \core
  features.py

This simplifies upgrades because we A) don’t have to try an “re-apply” a patch after an upgrade, or B) update our list of installed patches after an upgrade.

Specific patch directory contents

Lets say we have patch-1234 installed. The directory created (which is used to reference the patch) contains the following:

\patch-1234
  meta.ini
  README.txt
  \originals

The meta.ini and README.txt are defined in the next section, and come from the tar patch file. The directory originals contains backup copies of the original source files. When you install a patch, the patching tool creates these backups to enable us to uninstall the patch. Within that directory, you’ll see some rather long file names:

\originals
  insightiq___controllers___security.py

The triple-underbars ___ are used to replace the forward slash normally associated with a file system path. A triple-underbar is used instead of a single-underbar because it’s common for a Python source file to contain a single-underbar.

What’s in a patch

A patch for InsightIQ is a tar file consisting of the following files:

README.txt

A description of the patch. This must always include the bug number for the issue that requires patching.

meta.ini

A config file that defines what source files are getting patched, and what versions of InsightIQ the patch works with.

PATCHED_FILE

The patched source file, where PATCHED_FILE is actually the name of the source file. There can be as many as these files as needed for the patch.

Within the tar file, these files must be stored in a directory that names the patch following the convention of patch-PATCH_NUMBER, where PATCH_NUMBER is the actual number used to identify the patch for Isilon. In other words, if you unfurl the patch tar file, a directory with the patch files is written to your file system.

Example of patch file contents:

README.txt
meta.ini
insightiq/controllers/security.py

The meta.ini

The format is your standard INI file, with the headings info, version and files.

The info heading has two keys, name which is the name of the patch, and bug which is the number for the associated bug that is being patched.

The versions heading has two keys, minimum and maximum, and as you’ve likely guessed, define the oldest and newest versions of InsightIQ that the patch applies to.

The files heading defines what files are being patched, and can have as many keys as necessary. The key names should be the location of the original source file (relative to the installation directory), and the key values are the md5 hash of that original source file. Why are we including md5 hashes? To avoid installing patches that clobber (i.e. patch B overwrites the same file as patch A).

Example meta.ini:

[info]
name = patch-1234
bug = 156986
[version]
minimum = 4.1.0
maximum = 4.1.1
[files]
insightiq/controllers/security.py = 56266031a30cab220f56ee43b4159ded

Note

Version values are inclusive. If your patch only applies to one specific release, both minimum and maximum should have the same value.

Making a patch

There are the steps to create a patch for a single source file. In this example, we are patching insightiq/controllers/security.py

1. Create a directory for the patch:

   $ mkdir patch-1234
   

2. Copy your README.txt and meta.ini files into the directory made in step 1:

   $ cp README.txt meta.ini patch-1234
   

3. Create all subdirectories for the source file paths:

   $ mkdir -p patch-1234/insightiq/controllers
   

# Copy the patched files unto their respective locations::

$ cp security.py patch-1234/insightiq/controllers/

1. Create the tgz file:

   $ cd patch-1234 && tar -zcvf insightiq-patch-1234.tgz *