Required files

To run the VMBC, first create a sub-directory containing the following files, named as follows.

Name Description

rhino.license

A license to use Rhino.

This file will have been provided to you as part of your general contract to use this software.

This file is required to run VMBC and can also be included in the final VM image. If the file is not included in the image, it needs to be added when configuring the VM(s) through the use of the rvtconfig tool. If the file was included it can be replaced at deployment time though use of the same tool.

<jdk>

A Java Development Kit (JDK), in tar archive format. The file can have any name.

For licensing reasons, VMBC does not include a JDK by default; you must provide one. You can download a JDK from OpenJDK.

Valid JDKs are determined using the following criteria, which all JDKs from Oracle and OpenJDK should meet:

  • it is a valid tar archive (possibly gzip-compressed), with a name ending in .tar or .tar.gz

  • there is exactly one directory at the top level of the archive

  • under that top directory, the archive contains files bin/java and bin/javac.

The JDK you provide will be copied onto the produced VM. You must ensure that:

  • the version of Java in the JDK is compatible with the Rhino version in use

  • the licensing terms of the JDK allow it to be incorporated into virtual appliances you are producing, according to how you intend to use or distribute those virtual appliances.

node-parameters.yaml

A file listing certain properties of the VM to be built. This file is described on the Node parameters file page.

sentinel-package.zip, rhino-export.zip, or du directory

A Sentinel package, Rhino export, or directory of deployable units (DUs) of your application. You must include exactly one of these.

If you provide a directory of deployable units:

  • the directory must be named du

  • it must only contain Rhino deployable units, with names ending in du.jar.

csar-signing-key

An RSA private key used to sign the Cloud Service Archives (CSARs) from which the SIMPL VM will deploy your application. By signing the CSARs, your customers or users who deploy the CSARs can verify that they are the authentic published CSARs for your application, and are of the correct version.

You can generate a suitable key using ssh-keygen -t RSA -b 4096 -f csar-signing-key -N "" -m pem, where 4096 is the key strength in bits; it is recommended to use at least this value. The key must not have a passphrase and must be in PEM format (represented by the options -N "" and -m pem).

Providing a signing key is mandatory. The key is only used at build time to sign the CSARs, and is not included in the final VM images or CSARs.

If you generate a key using a command similar to the one above, make sure to delete or move the public key file (ending with .pub), as only the private key file should be provided in the VMBC input directory. It is always possible to rederive the public key from the private key at a later point, by using ssh-keygen -y.

Optional files

For VMBC, the sub-directory may also contain the following optional files.

Name Description

rhino-install.tar

A production Rhino package. (The file can have any name, but rhino-install.tar is most common.)

If this file is provided, VMBC will install the given Rhino into the VMs in place of the Rhino version that comes prepackaged with VMBC.

See Providing a Rhino package below for information on using a different Rhino version.

custom-build.zip

An archive containing custom scripts to run during the build process. This file is described in Build hooks.

custom-configuration.zip

An archive containing custom configuration scripts to run during configuration. This file is described in initconf hooks.

sas-bundle-mappings.yaml

A YAML file containing SAS bundle mappings. Each mapping is from a fully-qualified bundle name (such as com.opencloud.rhino) to the prefix that Rhino should apply to any event IDs in that bundle. The prefixes are 16 bits, that is from 1 (0x0001) to 65535 (0xFFFF), and must be unique.

Specify all bundle mappings at the top level of the YAML file. You can specify the prefixes in any integer format accepted by YAML - for this purpose, hexadecimal is most common. Here is an example file:

---
com.opencloud.rhino: 0x0001
com.opencloud.rhino.somecomponent: 0x0002

When provided, the bundle mappings are set in Rhino during the VM build. If required, your build hooks or initconf hooks can always make further changes to SAS bundle mappings.

Refer to SAS Bundle Mappings in the Rhino documentation for more information on SAS bundle mappings.

Providing a Rhino package

As noted in the table above, you can provide a production Rhino package in the input files, and VMBC will then install that version of Rhino into the VMs. A provided Rhino package must:

  • be a production Rhino package, not the Rhino SDK

  • be a valid tar archive (possibly gzip-compressed), with a name ending in .tar or .tar.gz

  • contain a version of Rhino that is at least that of the prepackaged Rhino, namely 3.2.

Updating the Rhino version this way is useful, for instance, when you wish to take a new Rhino version for a security fix or software update, without having to wait for the next release of VMBC.

Warning

To avoid unexpected behaviour, we strongly recommend that you use only Rhino versions with the same major version number as the pre-packaged Rhino, i.e. versions where the first two digits of the version number are identical.

For security reasons, VMBC rejects attempts to use an earlier version of Rhino than the prepackaged version.

Providing a later version of Rhino may not function as expected due to compatibility issues (the code in VMBC and on the VMs may not always be compatible with the given Rhino version). VMBC will emit a warning to this effect.

Running the vmbc command

The command you then run is ./vmbc, which takes parameters describing the target platforms for your VM, chosen from the following:

vsphere

VMware’s vSphere platform
vcloud

VMware’s vCloud platform
openstack

OpenStack platform
imageless

Platform-independent

For every platform specified, corresponding CSAR files (the packaging used by Metaswitch’s SIMPL VM) will automatically be built.

The imageless parameter builds CSARs containing the regularly included files (product schema, resources, validation tests), but no VM image. These are mainly used for verifying configuration against the CSAR schema, or other similar testing purposes where VMs are not being deployed. They can also be used where VM images have already been uploaded to virtualisation platforms. These CSARs are much smaller in size, making file transfer much quicker.

Run this command from the directory containing the sub-directory of input files described above. The tool will automatically find which sub-directory contains the necessary files, so you do not need to pass that as a parameter. Avoid having multiple different sub-directories containing relevant files because this will confuse this auto detection.

The maximal invocation of the command is thus:

./vmbc vsphere vcloud openstack imageless

There is a lot of work involved in building a VM - this command will typically take 10-20 minutes or more to run.

You can obtain full help for the ./vmbc script by running ./vmbc -h.

Host networking vs. bridge networking

By default, VMBC is run using Docker’s bridge networking mode. However, on some host operating systems you may find that this mode does not allow the container to get internet access, which may be required for some of your custom build hooks (for example, a hook that installs yum packages). Alternatively, you may find that, although the scripts have Internet access, they do not have working DNS resolution.

Note VMBC does not require internet access by default.

If this is the case, you can try running the ./vmbc command with the -n option, which will change to host networking mode instead. This should resolve the lack of internet access or DNS, but be aware that, on some host operating systems, this can cause Rhino to fail to start. See the troubleshooting section for more information.

Output files

Images are written to a directory named target/images located in the directory from which you invoked the ./vmbc command.

The command will also output build.log and Rhino log files in the target directory, along with a number of other log files (notably Rhino logs) generated by the build process and the .out files from any custom build hooks. These can help to debug issues encountered during the build.

$ ls -1 target
before-rhino-install.out
build.log
rhino.log
console.log
<other files>
images

$ ls -1 target/images
custom-vm-0.1.0rc2-openstack-csar.zip
custom-vm-0.1.0rc2-vmware-csar.zip
custom-vm-0.1.0rc2-vsphere-csar.zip
custom-vm-0.1.0rc2-vcloud.ovf
custom-vm-0.1.0rc2-vsphere.ova
custom-vm-0.1.0rc2-openstack.qcow2
custom-vm-0.1.0rc2-imageless-csar.zip
custom-vm-0.1.0rc2.yaml
Previous page Next page