Omaha Client working with protocol

Here are some notes about how Omaha client is working with protocol.
See the protocol description here.

Predefines

Let's use the {Update} symbol as the shortcut of the HKLM/Software/{OmahaCompanyName}/Update or HKCU/Software/{OmahaCompanyName}/Update registry path (depends on how omaha client is installed - per-machine or per-user). This will simplify the text a bit.

GUIDs format

Regardless of what case is using in GUIDs in registry or metainstaller's tag, the client always sends all GUID to the server in upper case. Therefore, all GUIDs defined on server must be also in upper case.

Including user id into request

Omaha client can send userid attribute as part of the <request> tag.
In order to enable this, at least one application should be installed with usagestats option set to 1 (e.g. when usagestats=1 is a part of the metainstaller's tag).
In this case, the client will automatically create the uid parameter under {Update} registry path and will use its value in requests.

Working with different update channels

Omaha client can work with different update channels for different applications, i.e. it can use stable channel for one application and dev channel for another. The channel can be provided via metainstaller's tag. When constructing request, the clients uses tag attribute of the <app> tag to transmit channel value. So, if using dev channel, the <app> tag will be looking like:

<app appid="{GUID}" ... tag="dev" ... />

When there is no channel provided, the default tag value is used.

Event actions

There are 4 events defined:

preinstall event

preinstall event is currently not supported by the client

install and update events

Defines what to do on application install/update after downloading it from the server. The behavior of actions corresponding to these 2 events are the same. Effective attributes are:

• run (optional): The name of an installer binary to run. If this is not set, the client will run the file it just downloaded.
• arguments (optional): Arguments to be passed to that installer binary.

postinstall event

Defines optional step which will be performed after successfull installation. Effective attributes are:

• run (optional): The name of a binary to run. This is not necessary the application-owned binary, but might be, for instance, cmd.exe or any program recognizable by the system.
• arguments (optional): Arguments to be passed to that binary.
• successurl (optional): A URL to be opened using the system's default web browser on a successful install.
• terminateallbrowsers (optional): If "true", close all browser windows before starting the binary.
• successsaction (optional): Contains a fixed string denoting some action to take in response to a successful install. One of:
  • default
  • exitsilently
  • exitsilentlyonlaunchcmd

In addition, the application installer might set the InstallerSuccessLaunchCmdLine value under {Update}/ClientState/{GUID} registry path. This value is also used as command to run after successful installation. However, if run attribute is presented in <action event="postinstall"... /> tag it will have priority over registry value so the registry value will be ignored in that case.

Installer data elements

There is data element defined in protocol which allows to pass additional data to application installer.
At this moment the client only supports elements with install name, there's no support of untrusted elements.
The index of the install data element can be provided via metainstaller's tag.

When the client receives installer data corresponding to requested index, it stores it into temporary file. After that the client invokes the application installer binary with necessary arguments and passes the temporary filename with /installerdata argument, like this:

application_installer.exe /installerdata=path_to_temp_file.tmp