A customer can update the version of Rhino they are using by:

  • Creating a Rhino only upgrade bundle

  • Use orca to apply the Rhino only upgrade bundle

Creating a Rhino-only upgrade bundle

A Rhino-only upgrade bundle is is a self-contained package named:

  • rhino-<rhino-version>-upgrade-bundle.zip

For example, a bundle to upgrade to Rhino 2.6.0.1 would be called rhino-2.6.0.1-upgrade-bundle.zip

A Rhino-only upgrade bundle includes the orca bundle and also:

Bundle element Description

A Rhino install package

The new version of Rhino to be installed

(optionally) a new JDK package

A new JDK for the new Rhino may be required or recommended

(optionally) a new license

A new license may be required to use the new Rhino

(optionally) a Rhino configuration update JSON file

This file defines any configuration changes to apply to the default Rhino installation. For example, to change the size of the Java heap, or increase the size of the Rhino management database.

The Rhino package

The Rhino package is the tar file used to distribute Rhino. It contains the Rhino binaries, tools and the installation script.

rhino-install.tar

The Rhino config json file

This file contains configuration that will be applied to Rhino during its installation. The file is formatted as JSON and it includes the Rhino config file destination, the properties and values. Rhino has several configuration attributes in several files with different formats. Currently orca applies the changes to the config_variables and rhino-config.xml file.

The json file format is:

[
  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "properties",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  },

  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "xml",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  },
  ....
  {
     "filename": "file name with path relative to Rhino node installation",
     "filetype:" "sh",
     "settings:" [{settings 1},{settings 2},...,{settings n}]
  }
]
Note The filename path is relative to the Rhino node installation. e.g for rhino-config.xml it should be config/rhino-config.xml

The filetype attribute accepts the following values:

  • properties to deal with Rhino key=value config properties)

  • xml to deal with rhino xml config files, e.g rhino-config.xml

  • sh to deal with read-config-variables file

The parameters in the settings attribute should match the expected format defined by the filetype:

  • a property if filetype is properties or sh

  • an XPath if filetype is xml

Example from sentinel-volte-upgrade-rhino-config.json

[
  {
    "filename": "config/config_variables",
    "filetype": "properties",
    "settings": [
      {
        "name": "HEAP_SIZE",
        "type": "minimum",
        "units": "m",
        "value": 6144
      }
    ]
  },

  {
    "filename": "config/rhino-config.xml",
    "filetype": "xml",
    "settings": [
      {
        "xpath": ".//memdb[jndi-name='ManagementDatabase']/committed-size",
        "type": "minimum",
        "units": "M",
        "value": 400
      }
    ]
  }
]
Note Currently the only supported values for type are value and minimum.

For the example above, orca will change the value of the HEAP_SIZE property to 6144m if the current value is lower than that. It will also change the committed-size for element memdb with jndi-name equals to 'ManagementDatabase'.

Concretely it will change

 <memdb>
       <jndi-name>ManagementDatabase</jndi-name>
       <committed-size>128M</committed-size>
 </memdb>

to

 <memdb>
       <jndi-name>ManagementDatabase</jndi-name>
       <committed-size>400M</committed-size>
 </memdb>

Creating the bundle

To create a Rhino only upgrade bundle:

  • get the latest version of orca-bundler.zip from operational-tools

  • decompress it

  • run generate-orca-bundle rhino-upgrade to bundle a Rhino install with orca

$ unzip orca-bundler.zip
$ ./generate-orca-bundle rhino-upgrade --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>

A new license can be installed during a Rhino update by including it in the bundle.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle rhino-upgrade --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>\
                                       --license <new-license.license>

To also update the JDK (Java) used to run rhino, include a new JDK package in the bundle.

$ unzip orca-bundler.zip
$ ./generate-orca-bundle rhino-upgrade --out <the upgrade bundle>.zip\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>\
                                       --license <new-license.license>\
                                       --java-package <jdk-package>

The orca-bundler will create the zip file specified in <the upgrade bundle>.zip with the Rhino install package, the orca tool, the optional packages and a README file explaining how to install the Rhino only upgrade. It is important to review this file and add or change any information before handing the upgrade to the customer.

Note Use the flag --skip-rhino-version-check in the bundler while creating test upgrade bundles against non released versions of Rhino.

Applying a Rhino only upgrade bundle

Use the orca tool to apply a Rhino only upgrade (see: orca requirements).

Applying a Rhino only upgrade requires administrative access to hosts running Rhino. Be sure the credentials used in ssh trusted connections are valid.

Orca assumes the $HOME directory of the remote hosts is the base directory. Use the option --remote-home-dir or -r if the path is different. The upgrade requires at least 1.5GB of free disk space in the first node:

  • 0.5GB for the upgrade bundle

  • 0.5GB for the installer to run

  • 0.5GB for logs

Apply a Rhino only upgrade

The steps for applying a Rhino only upgrade are:

  • download the Rhino only upgrade bundle to the management host

  • ensure the management host has ssh access to the cluster hosts running Rhino

  • decompress the upgrade bundle and cd to the upgrade bundle

  • read the README for instructions and for details of the upgrade

  • verify Rhino is running

Upgrade Rhino on all nodes with the orca command:

./orca --hosts host1,host2,host3 rhino-only-upgrade --no-pause

Apply a Rhino only upgrade in multiple stages by using the --pause option.

./orca --hosts host1,host2,host3 rhino-only-upgrade --pause

All of the hosts (in this case host1, host2, and host3) are prepared for the upgrade. Only the first host (host1) will have the new Rhino version active. You need to arrange your testing appropriately to route traffic to this specific host.

Once you are satisfied that the upgrade is working as required, continue the upgrade by:

./orca --hosts host1,host2,host3 rhino-only-upgrade --continue
Note Use the same list of hosts as the continuation process needs to access the same first host, and same set of prepared hosts, as before.

This will then migrate the other nodes of the cluster, so they are all using the new version of Rhino.

Previous page Next page