Intended audience

This page is aimed at developers who wish to publish a major upgrade package for a new release of a Sentinel product.

Creating the bundle

Creating a major upgrade bundle requires:

  • the product SDK

  • the orca-bundler tool

  • the data transformation rules, present in the product upgrade module

and the optional packages

  • the new Rhino

  • the new Java JDK

  • the post-install package

  • the post-configure package

  • the required Rhino configuration and the required SDK install properties, both present in the product upgrade module

The orca-bundler will:

  • put the product SDK in offline mode with an offline repository

  • zip the product SDK

  • combine the orca tools with the product SDK and the optional packages to create the major upgrade bundle

To create the major upgrade bundle without the optional packages:

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

  • decompress it

  • run generate-orca-bundle major-upgrade to bundle the SDK with orca

$ unzip orca-bundler.zip
$ ./generate-orca-bundle major-upgrade --release-sdk <the sdk>.zip --out <the upgrade bundle>.zip --transformation-rules <transformation rules jar>

Optionally you can generate your SDK offline if you need a customized SDK.

  • run generate-orca-bundle prepare-sdk to convert the release SDK to offline mode

  • run generate-orca-bundle major-upgrade to bundle the offline SDK with orca

$ unzip orca-bundler.zip
$ ./generate-orca-bundle prepare-sdk --release-sdk <product sdk>.zip --out <the offline SDK>.zip
$ ./generate-orca-bundle major-upgrade --offline-sdk <the offline sdk>.zip --out <the upgrade bundle>.zip --transformation-rules <transformation rules jar>

The upgrade package will contain:

Item Description

README

Contains information about the major upgrade: how to use it, what components it changes, and what problems it fixes

orca

The orca tool

helpers directory

Contains the set of scripts used by orca

core directory

Contains the set of scripts used by orca

workflows directory

Contains the set of scripts used by orca

resources directory

Contains the properties used by orca

licenses directory

License information for third party libraries used by the patch runner

packages directory

Contains the package files and the packages.cfg

transformation-rules

Contains the transformation rules jar

required-installer-properties

Contains the required SDK properties

The package files directory contains:

  • the packages.cfg file

  • the SDK in offline mode

  • the post install package or custom package (optional)

  • the post configure package (optional)

  • the rhino installer (optional)

  • the rhino-config.json with the required Rhino properties when a new Rhino is required

  • the Java JDK (optional)

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

Adding custom packages to the upgrade bundle

In case the major upgrade requires a custom package, the best solution is to include it with the upgrade bundle.

To create the major upgrade bundle with the optional packages:

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

  • get the new Rhino version to be installed

  • get the new Java JDK to be installed

  • get the post-install package

  • get the post-configure package

  • decompress the orca bundler

  • run generate-orca-bundle major-upgrade to bundle the SDK and the optional packages with orca

Use the options:

  • --post-install-package and/or --post-configure-package to add a custom module

  • --post-configure-package to add a post-configuration module

  • --rhino-package to add a new Rhino to install

  • --license to specify a new Rhino license

  • --java-package to add the new Java JDK

  • --required-properties to specify the minimum required product SDK install.properties

  • --required-rhino-overrides to specify the minimum required Rhino installer overrides with optional mandatory values

  • --rhino-config-json to specify extra Rhino configuration

  • --feature-scripts to specify the original Feature scripts to be used in the 3 way merge feature scripts

Note A new license option is only available when installing a new Rhino version. Use the flag --skip-rhino-version-check in the bundler while creating test upgrade bundles against non released versions of Rhino. 
$ unzip orca-bundler.zip
$ ./generate-orca-bundle major-upgrade --release-sdk <product sdk>.zip\
                                       --out <the offline SDK>.zip\
                                       --post-install-package <custom package>\
                                       --post-configure-package <configure package>\
                                       --rhino-package <new Rhino package>\
                                       --rhino-config-json <Rhino config properties to apply>\
                                       --required-properties <product required properties>\
                                       --required-rhino-overrides <Rhino required overrides>\
                                       --feature-scripts <the feature scripts xml file from rhino export>\
                                       --transformation-rules <the transformations rules jar>\
                                       --java-package <new Java JDK>

Post-install and post-configure packages

During the upgrade procedure the custom packages will be installed if they are present in the packages.cfg.

Note
"Post-install" and "post-configuration" customizations

Note that orca will install the post-install package after installing the main product SDK but before applying any configuration. The post-configure package will be installed after the configuration is applied. If different customizations are required at these points then you must create two separate custom packages.

The custom packages must conform to the following specification:

  • be a .zip file

  • contain an executable file named install (no extension) in the root directory of the zip.

orca extracts the packages to ~/install/<package name> on the Rhino node and runs the install script from this directory. It calls the install script with one command-line parameter, which is the full path to the uplevel Rhino installation.

It is recommended that the package developer edits the README in the upgrade bundle to include the extra details on the custom package(s).

You can also manually add the post-install and post-configure packages to the upgrade bundle, but it is not recommended. To do so, add the optional packages major upgrade to the bundle zip file after running the above commands. The optional packages have to be in the packages directory and the packages.cfg needs to have the packages names.

Example of the contents of a packages.cfg:

[files]
sdk=volte-2.8.0.3-offline-sdk.zip
post_install_package=post-install-package.zip
post_configure_package=post-configure-package.zip
rhino_package=rhino-install.tar
rhino_config_json=sentinel-volte-upgrade-rhino-config.json

[versions]
sdk=2.8.0.3
rhino_package=2.6.1.2

[additional_data]

The packages, properties and feature scripts format

The Feature Scripts

The major upgrade process includes a three-way merge process that requires the original Feature Scripts from the currently installed product. The objective is to minimize the manual work to adjust the Feature Scripts and to preserve the custom changes per customer.

The merge feature script tool receives 3 inputs:

  1. the feature scripts from the product without customizations

  2. the current feature scripts present in the installed system

  3. the feature scripts from the new product after installation

The item 1 should be provided while creating the upgrade package. It is important to know what is the version that is current installed in customer and what is the chosen deployment module.

The item 2 and 3 are acquired during the upgrade process.

The feature script format is an xml file format generated by the rhino-export process.

Important The tool supports just one platform operator name per installation. It ignores the operator name while extracting the Feature Scripts file from the production system.

The post-install and post-configure packages

The post-install and post-configure package should be of the following format:

  • a self-contained zip file (included inside the upgrade bundle in the top-level directory)

  • an executable file named install (with no extension; it can be of any format, e.g. bash script or binary) in the top-level directory of said zip file

orca will pass the directory of the current live Rhino installation as an argument to the executable install.

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>

The Java package

The Java package has the format jdk-<version>-<platform>.tar.gz, e.g jdk-8u172-linux-x64.tar.gz.

If a Java package is specified a new section in the packages.cfg will include the jdk details.

[files]
sdk=volte-2.8.0.2-offline-sdk.zip
rhino_package=rhino-install.tar
java_package=jdk-8u172-linux-x64.tar.gz
rhino_config_json=sentinel-volte-upgrade-rhino-config.json
feature_scripts=downlevel_feature_scripts.xml

[versions]
sdk=2.8.0.2
rhino_package=2.6.1.0
java_package=1.8.0_172

[additional_data]
java_package=jdk1.8.0_172

The transformation rule jar

The transformation rule jar is a compiled file including the classes to make the data transformation according to the data transformation API. The rules live in the product repository.

For more details see SLEE Data Transformation and Data Transformation API.

The required properties file

The required properties file is a simple file with the properties to be checked. Each property is a line in the file.

Example from sentinel-volte-upgrade-required-installer-properties.txt:

volte.mode
home.domain
home.network.prefix
home.mcc
home.mnc.list
Previous page Next page