Update Manager Service Example

Update Manager Service



·            Overview

·            Prerequisites

·            Update Manager Service Example

·            makeEsfStar.sh script

·            fileIncludeList

·            Post- and Pre-install scripts

·            Add Files to Target

·            Creating an Update File


·            Setup for Testing the Update

·            Testing via Configuration Manager HTTP

·            Testing Direct .star File Update

·            Cleaning Up After the Update



This example shows how to use the Update Manager Service, as well as create an update file to update a device.  The ESF Update Manager Service uses the ESF Configuration Manager (CM) to get software updates into ESF.  The CM is already highly adaptable in terms of getting Objects from remote locations into specific bundles.  So, the Update Manager Service uses this as the mechanism to get the updates into the system as described in more detail here.  The CM is described in more detail here and a code example is here.


In this example, you will learn how to

Create an update that can deployed on a working system

Deploy the created update to a target system



·            Installing the Eclipse IDE

·            Integrating ESF Tooling and Projects into Eclipse


·            Installing ESF Tooling into Wind River Workbench


·            Using Working Sets

·            Hello World Using the ESF Logger

·            Configuration Manager Service


Update Manager Service Example

This how-to goes through the process of creating an update to deploy to a target system.  The process involves creating a zip file with a ‘project_releases.txt’ and one or more ‘star’ files in it.  The update service is capable of deploying a series of updates.  This keeps updates small, as well as allows updates to be incremental as old units may come online.  Regardless, this structure does not prevent cumulative updates.  One could create separate updates where each update included all of the previous updates as well.  When deploying the updates, the zip file contains a project_releases.txt that only refers to a single star file that is the combination of all previous updates.


In this example, we make a very simple update.  We add a single bundle and update the /etc/esf/*release*.xml file to reflect the new version.  By default, every ESF system should have a /etc/esf/*release*.xml file.  The format for this name is BOARD-PRODUCTNAME_release-MAJOR.MINOR.SUBMINOR.xml.  We are using a Helios board, and the product is called Tomahawk.  The current release of tomahawk is 1.0.0.  So the new release file will be /etc/esf/helios-tomahawk_release-1.1.0.xml.  In this update, we add a new business logic bundle (the hello world bundle from Hello World Using the ESF Logger), a modified services.xml file to automatically start the bundle, and a new release.xml file to reflect the changes.


In order to do this, we need the star builder components.  There are four files of importance.  These files are contained in the zip file 3.05-UpdateManager.zip.  Download this file to the /tmp/ directory on an ESF system.  Then execute the following commands to extract the necessary components.


cd /tmp

unzip 3.05-UpdateManager.zip


Before creating the update, issue the following command to back up your existing files, so that you can restore the system back to present condition.


tar cvf /root/version_backup.tar /etc/esf/*.xml /opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml /opt/jvm/esf/configuration/.esf/com.esf.core.system.manager/esf.props



makeEsfStar.sh script

The first file is the ‘makeEsfStar.sh’, which is the script that is run to generate the actual star file.  It has three parameters that must be set on a project by project basis.  These parameters are


COMPANY=[the company that owns the product]

PROJECT=[board-product, where the “board” is the hardware, and “product” is the software being released]

UPDATE_SERVER_LOCATION=[URL of the update server if one exists (can be blank)]


The example parameters are






If the UPDATE_SERVER_LOCATION is set, then the makeEsfStar.sh script will fetch the current version of UPDATE_SERVER_FILE from the server and append the new line to it.  If it is not specified, it simply creates a new project_releases.txt that only contains one line representing the new star file being created.



The second piece of interest in the making of star files is the file called fileIncludeList.  It is simply a list of files with their full paths that should be included in the star file.


The fileIncludeList for our example is


# Include below a list of all the filesystem files to be included





Post- and Pre-install scripts

There are two additional files that are of interest in the star file creation: preinst_script and the postinst_script.  As the names suggest, these files are scripts that are put into the star file and run either before or after the main tar file containing the files in fileIncludeList is extracted.  They can be used to do work like deleting old files, logging information, or installing RPMs.  The preinst_script is run before any other files are extracted.  The postinst_script is run after the files are extracted into the filesystem.


In the preinst_script, remove any old copies of the .jar files that are being installed.  Use a “rm -f bundlename_*.jar” to remove any existing copies, but be careful not to remove the bundlename.service*.jar if you aren’t installing a new service bundle.


The following are the examples for this how-to.


root@localhost:/tmp> cat preinst_script


date >> /tmp/update.log

echo preinstall script in update 1.1.0 was run >> /tmp/update.log

#remove old files

echo removing helios-tomahawk_release-1.0.0.xml >> /tmp/update.log

rm /etc/esf/helios-tomahawk_release-1.0.0.xml

echo removing old .jar files >> /tmp/update.log

rm -f /opt/jvm/esf/bundlefiles/com.esf.example.helloworld_*.jar


root@localhost:/tmp> cat postinst_script


date >> /tmp/update.log

echo postinstall script in update 1.1.0 was run >> /tmp/update.log


Add Files to Target

Before running makeEsfStar.sh, make sure the target device has been updated with all the changes going into the update.  In this example, you are using the 3.05-UpdateManager.zip example file, so you will need to make the following modifications to your system to be compatible with the example.


1. Add all new files to be installed on the target.  This may include .jar files and all other file system components.  Make sure the permissions on the files are correct.  If including RPMs or Debians, include them under the /tmp/ directory.  In this example, include the  com.esf.example.helloworld_1.0.0.201007301252.jar  in the  /opt/jvm/esf/bundlefiles/  directory (actual filename will be different when you create your HelloWorld plug-in).


2. Make sure the file /opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml has been updated to automatically start any new Java projects.  In this example, modify the services.xml file to include the helloworld example.


nano /opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml


Add the following lines.







3. Update the release.xml file according to the current product and release number.  In this example, create a file named  /etc/esf/helios-tomahawk_release-1.1.0.xml  with the following contents.


<?xml version="1.0" encoding="UTF-8"?>


  <comment>Helios Denali</comment>
















      <location>ESF_ROOT trunk</location>







Creating an Update File

With all these files in place, we can run the makeEsfStar.sh to build the update.  All four of the make files (makeEsfStar.sh, fileIncludeList, preinst_script, and postinst_script) should be placed in /tmp/ on the target. 


The makeEsfStar.sh script pulls the files from this unit as listed in the fileIncludeList into a zipped copy.  The following is output for our example.



root@localhost:/tmp> ./makeEsfStar.sh

making /tmp/new_star

validating versions

the current version is: 1.1.0

fetching the latest releases.txt file

not making /tmp/ dir

Tarring the following files into the star file...


















Adding .star pre-script tmp/preinst_script.

Adding .star post-script tmp/postinst_script.

  adding: eurotech_helios-tomahawk_update-1.1.0.star (deflated 32%)

  adding: helios-tomahawk_releases.txt (deflated 8%)



eurotech_helios-tomahawk_update-1.1.0.star created successfully:


star file is /tmp/eurotech_helios-tomahawk_update-1.1.0.star

version file is /tmp/helios-tomahawk_releases.txt

update file is /tmp/tcd_file_tgz_1.tgz



Check the previous output to make sure that all the needed files were included in the update file list. 


There are three new files in /tmp/: tcd_file_tgz_1.tgz, eurotech_helios-tomahawk_update-1.1.0.star, and helios-tomahawk_releases.txt.  These files can now be placed on an update server or deployed directly to other targets.  The tcd_file_tgz_1.tgz file can be used to apply the update via the CM HTTP service.  The .star file can also be deployed directly via command prompt.  These two methods are described in the next sections.


If you are using Denali, you can also use the Update configuration tab.  See the Denali User Manual for instructions.




Setup for Testing the Update

Before testing the update, we need to make sure your ESF system is back to a “normal” state.  Ideally, this step would include re-installing your present version of software to its pristine state, applying the update cleanly to the current system, and validating to make sure it all works correctly before deploying this update to a field application.  However, for this example it’s only necessary to remove any changes that we introduced to the system.  If you used the same device to create the update as you will use to test the install, perform the following steps to make the system look like it would prior to the update being installed.


1. Remove the new files from the target.  In this example, remove com.esf.example.helloworld_1.0.0.201007301252.jar  from the  /opt/jvm/esf/bundlefiles/  directory.


rm /opt/jvm/esf/bundlefiles/com.esf.example.helloworld_1.0.0.201007301252.jar


2. Modify the services.xml


nano /opt/jvm/esf/configuration/.esf/com.esf.core.system.bootstrap/services.xml


and remove the following lines.







3. Move the file /etc/esf/helios-tomahawk_release-1.1.0.xml  to  /etc/esf/helios-tomahawk_release-1.0.0.xml  (the contents don’t really matter for our present purpose).  This step will simulate a system running the “tomahawk” product name, which is starting at version 1.0.0.  After the update, the version file will be replaced with the 1.1.0 version.


mv /etc/esf/helios-tomahawk_release-1.1.0.xml  /etc/esf/helios-tomahawk_release-1.0.0.xml



rm /etc/esf/*.xml

touch /etc/esf/helios-tomahawk_release-1.0.0.xml



Testing via Configuration Manager HTTP

One way to load software updates into ESF is via the Configuration Manager.  This step will use the tcd_file_tgz_1.tgz file created previously.  First, use the steps in the section Setup for Testing the Update to set up for testing.


From the Linux command line, tail the Equinox log file.


tail -f /tmp/equinox.log


To test the update using CM, open a browser to the address  http://[ip_address]:8080/com/esf/core/configuration/cpi/HttpServer  (substituting your actual address for “[ip_address]”).  A simple dialog will open as shown in figure 1.



Figure 1 Uploading the Update


Browse to the tcd_file_tgz_1.tgz file you have copied over to your PC.  Then, click the Upload button.  On the ESF console, you should see the following output.


[WARNING] 2012-05-07 20:14:08.495 - com.esf.core.updater.EsfUpdater: ********************************  WARNING - ABOUT TO UPDATE  ********************************

[WARNING] 2012-05-07 20:14:08.495 - com.esf.core.updater.EsfUpdater: about to update from 1.0.0 to helios-tomahawk_update-1.1.0

[WARNING] 2012-05-07 20:14:08.496 - com.esf.core.updater.EsfUpdater: ESF will shut down for the udpate and the unit may reboot depending on what the update includes

[WARNING] 2012-05-07 20:14:08.496 - com.esf.core.updater.EsfUpdater: Do not remove power to the unit until this process is complete

[WARNING] 2012-05-07 20:14:08.496 - com.esf.core.updater.EsfUpdater: ********************************  WARNING - ABOUT TO UPDATE  ********************************

[WARNING] 2012-05-07 20:14:11.152 - com.esf.core.updater.EsfUpdater: ********************************  END WARNING - UPDATE COMPLETE!  ********************************


The update creates a file /tmp/update.log, which can be observed to see more results of the update process.


root@localhost:/tmp> more /tmp/update.log

Self-extracting archive... please wait

Extracting eurotech_helios-tomahawk_update-1.1.0.star}

Running .star pre-script /tmp/preinst_script

Mon May  7 21:47:40 GMT 2012

preinstall script in update 1.1.0 was run

removing helios-tomahawk_release-1.0.0.xml

removing old .jar files

Running .star post-script /tmp/postinst_script

Mon May  7 21:47:40 GMT 2012

postinstall script in update 1.1.0 was run

Extraction completed.


After testing the update, if needed, restore the original system files in the section Cleaning Up After the Update.



Testing Direct .star File Update

Another way to load software updates into ESF is directly from the command line.  This step will use the eurotech_helios-tomahawk_update-1.1.0.star file created previously.  First, use the steps in the section Setup for Testing the Update to set up for testing.


Download the eurotech_helios-tomahawk_update-1.1.0.star file into the /tmp/ directory on the target.  From a command line, issue the following commands.


cd /tmp

touch update.log

tail -f update.log &                    (Notice the ampersand ‘&’ at the end.)

sh eurotech_helios-tomahawk_update-1.1.0.star


The output of the /tmp/update.log file can be observed to see more results of the update process.


Running .star pre-script /tmp/preinst_script

Tue May  8 15:28:35 GMT 2012

preinstall script in update 1.1.0 was run

removing helios-tomahawk_release-1.0.0.xml

removing old .jar files

Running .star post-script /tmp/postinst_script

Tue May  8 15:28:35 GMT 2012

postinstall script in update 1.1.0 was run

Extraction completed.


After testing the update, if needed, restore the original system files in the section Cleaning Up After the Update.




Cleaning Up After the Update

After testing the update process, you can restore the system files to their original state with the following commands.


rm /etc/esf/*.xml

tar xvf /root/version_backup.tar -C /

rm /opt/jvm/esf/bundlefiles/com.esf.example.helloworld_1.0.0.201007301252.jar



The code to create this update can be found here.  This does not need to be imported into Eclipse as it all runs on the target system.