Update Tool Desktop Notifier Management

This page describes the management of the notifier's life cycle.

Goals:

• If the user has opt'ed in for update notifications (default is true) then the notifier should be registered as a login start up task.

• The notifier should remain registered as long as a valid image remains known to the GUI.

• The registered notifier should be resilient to changes to the image. If the image goes away or is moved a registered notifier should attempt to recover.

Non-goal:

• Allowing the user to selectively choose which installed images are monitored by the notifier.

Likely Install Scenarios:

• Preconfigured zip based image where the user can unzip and run the product.
• A minimized image that may or may not be platform neutral. The UC bootstrapper and/or a traditional installer may be utilized to install the pkgs.
• A traditional installer that installs the pkgs - does not utilize the UC bootstrapper.

The likely scenarios imply the following in regards to notifier management:

• In some cases we can depend on the bootstrapper to register the notifier.
• In some cases we can depend on the product's installer to register the notifier.
• In some cases we must rely on the GUI to register the notifier as the installer and bootstrapper are never run.

Other considerations:

• The bootstrapper is not run when the product is uninstalled so we can not rely on it to unregister the notifier.
• An image may be "uninstalled" by the the user deleting it from the host. An uninstaller may not be run as part of this process and the packages may not be formally uninstalled using the pkg command. This may leave a dangling (and invalid) notifier registration.
• The image may be "owned" by more than one user. For example two admins may manage the maintenance of an image. One may choose to opt in for update notifications, another may not.
• Similar to above when two users manage a shared image and one decides to remove it. Even if a formal installer is used to remove the image the second user's notifier registration would likely not be unregistered.
• An image may be moved to a new location.
• An image may be copied to a new location.

How do we accomplish the goals?

UC Bootstrapper:

Use the existing optin.update.notification property known to the bootstrapper to indicate whether the notifier should be registered as part of the boot strapping process. The default for this property is true.

When the bootstrapper is run, if the optin.update.notification property is true, it will attempt to register the notifier using the updatetoolconfig script. This may silently fail if the notifier is already registered by a different image. The bootstrapper will also launch the notifier. This may also silently fail if the notifier is already running.

If the optin.update.notification is true then the initial update check frequency of the notifier (notifier.check_frequency) will be set to daily if it is currently not set or set to "never". If it is currently set to weekly or monthly we assume the user established that frequency and we will not change it.

If the optin.update.notification is false then this indicates the user has opt'ed out of update checks. Since updates checks are per user not per image this indicates that no further update checks should occur for any image on the system known to that user (e.g. the GUI's main.image_list). The notifier.check_frequency will be set to "never".

Installers who utilize the bootstrapper and collect initial notification opt-in preferences from the user must represent the notification opt-in preference as a global preference which applies to all images on the system for that user.

Installers:

Installers are encouraged to use the UC bootstrapper to register the notifier. Installers should capture the user's opt-in update notification preference. The bootstrapper will use this information to not only register the notifier but properly establish the update check frequency and start the notifier if it is not already running.

Updatetool GUI:

The GUI will be used to check the status of the notifier registration. It will register the notifier if it needs to. Sixty seconds after the GUI is launched a timer will trigger the notifier registration check.

When the timer triggers, the GUI will check the notifier.check_frequency property. If this property is not "never" the GUI will register the notifier as a startup item. It will attempt register the notifier associated with the GUI's image. This may silently fail if the notifier is already registered. The GUI will not attempt to start the notifier.

This behavior supports the registration of the notifier for the pre-configured zip based image scenario - where there is no installer available to register the notifier.

Updatetool Package:

Do nothing.

When an IPS package is installed via the GUI a postinstall script can be executed. Support for executing a postinstall script is currently not supported when a package is installed via the pkg CLI. Given this inconsistency and limitation (the postinstall script can only be executed from the GUI) there is no value in performing an updatetool package level registration. (The GUI is already running which means the GUI has already performed the registration if necessary)

The updatetoolconfig Script:

We can also advertise in our external documentation the availablity of the updatetoolconfig script which may be used to register the notifier as a login start-up item.

The updatetoolconfig script will not attempt to start the notifier. It is only used to manage the registration of the notifier as a log in task.

Unregistration

When an image is uninstalled the uninstaller should attempt to unregister the notifier using the updatetoolconfig script. The unregistration will only succeed if the current image is the last known valid image known to the notifier/GUI.

If unregistration succeeds or is prevented due to other existing images a 0 exit code will be returned. If unreg fails because nothing is registered an exit code of 1 will be returned. Exit code of 2 indicates a CLI syntax issue and an exit code greater than 2 will indicate some other operational failure.

Manual unregistration is possible by invoking the updatetoolconfig script with the --unregister option. Using the --force option will trigger unregistration even if other images are still known to the notifier/GUI.

Implementation Details

The updatetoolconfig utility is used to register the notifier as a login start-up task. When the notifier is registered a helper tool is placed in the updatetool "preferences" directory:

$HOME/.updatetool/notifier

(On Windows the helper tool is installed into Documents and Settings\user\Start Menu\Programs\Startup. It is called Update Tool Notifier.exe.

The tool is copied from $IMAGE_ROOT/updatetool/lib (or bin on Windows).

The preferences directory may not exist so the tool may have to create it.

It is this tool that is registered as a login start-up task with the system login facility.

The updatetoolconfig utility also creates the following file in the preferences directory:

$HOME/.updatetool/notifier.cfg

It contains the path to the image which last registered the notifier.

When the user logs into the system the system login facilities invokes the notifier helper tool. It loads the image path stored in the notifier.cfg. Validates the path and then uses that path to launch the actual notifier from that image.

An invalid path in the notifier.cfg could mean the image may have been moved or deleted. When this occurs the notifier helper tool will read (if it exists) $HOME/.updatetool/imagelist.cfg. This file contains a simple list of images known to the GUI. It's in this form:

/path/to/image1
/path/to/image2
/path/to/image3

The first image in the list that is found to be valid (where valid means IMAGE_ROOT/updatetool/bin/updatetool exists) will be used to launch the notifier. This path would also be placed in the notifier.cfg file (replacing the invalid path).

The $HOME/.updatetool/imagelist.cfg file will be maintained by the GUI. Whenever the GUI updates the list of known images this list is also updated.

If the path in notifier.cfg is invalid and all the paths in imagelist.cfg are invalid (or if these files do not exist) the notifier tool will silently exit.

When the notifier is unregistered as a start-up task the updatetoolconfig script will first inspect the contents of the imagelist.cfg file. If more than one path is contained in that file then the notifier will not be unregistered (The assumption being that there are still other images on the host that need monitoring). If there is only one image path in imagelist.cfg and the path matches the path of the image being unregistered then the unregistration will occur.

If the --force option is used during unregistration the above checks will not occur. The notifier will be unregistered as a login start-up task.

A note about Windows. The notifier helper tool can not be a bat script. When a bat script is launched a cmd.exe window is displayed. A cmd.exe window should not appear when a user logs into their system. On Windows we will copy the existing updatetool.exe wrapper utility to the user's startup folder. It will be renamed notifier.exe. This wrapper utility would be enhanced to perform the functions as described above.

How to keep the notifier helper tool up to date?

The notifier tool in the .updatetool directory may become out of date. A complete unregistration followed by a registration would cause it to be replaced but this cycle may not happen very often.

When the notifier script is invoked it will compare its version number (a simple monotonically increasing number) with the version number returned be executing the notifier tool from the current image (based on the contents of notifier.cfg). If the current image has a newer version of the notifier tool it will replace itself with the newer version.

Maintaining notifier registration

Images may be removed via:

• Updatetool GUI
• pkg CLI
• rm (of the image directory)

This may leave the notifier registration in one of these situations:

1 No images remain and the notifier is not registered

Perfect. Nothing to do.

2 No images remain and the notifier is registered

The notifier tool will silently fail when no images are available.

3 Images remain but the notifier is no longer registered

When the user launches the GUI a background thread should detect this and register the notifier if the optin.update.notification is true and the notifier.check_frequency is not never. TBD: Do we need to check both?

4 Images remain but the notifier is registered by a non-existent image

When the user logs in the notifier tool should detect this situation and locate a valid image via the contents of imagelist.cfg.

5 Images remain and the notifier is registered by an existing image

Perfect. Nothing to do.

Issues with the prior notifier registration implementation

The notifier was registered when an updatetool pkg is installed and removed when an updatetool pkg is uninstall. There are several issues with this approach:

• The user may not have wanted the notifier registered.
• We attempt to register the notifier regardless of whether a notifier is already registered (this isn't that big an issue)
• We attempt to unregister a notifier regardless of which instance of the updatetool pkg added it.
• If the user is managing multiple images it is easy for them to get in a state where they remove an image (and unregister the notifier) yet still have images on the system that need monitoring.
• The registration postinstall script is only executed from the GUI.

Short of moving all the updatetool code and dependencies outside of the image and managing it independently from the user images we needed a better way of handling the life cycle of the notifier.