This is the functional specification for Chromium Updater. It describes the externally observable behavior of the updater, including APIs and UI.
The metainstaller (UpdaterSetup) is a small executable that contains a compressed copy of the updater as a resource, extracts it, and triggers installation of the updater / an app. The metainstaller is downloaded by the user and can be run from any directory.
The metainstaller may have a tag attached to it. The tag is a piece of unsigned data from which the metainstaller extracts the ID of the application to be installed, along with the application's brand code, usage-stats opt-in status, and any additional parameters to be associated with the application.
After the metainstaller installs the updater, the updater installs an application by connecting to update servers and downloading and executing an application installer.
On Windows, the tag is embedded in one of the certificates in the metainstaller PE. The tag is supported for both EXE and MSI formats.
TODO(crbug.com/1328903) - document the rest of the tag format.
The brand code is a string of up to 4 characters long. The brand code is persisted during the install, over-installs, and updates.
The metainstaller parses its tag and re-launches itself at high integrity if installing an application with needsadmin=true or needsadmin=prefers.
Metainstaller localization presents the metainstaller UI with the user's preferred language on the current system. Every string shown in the UI is translated.
The bundle installer allows installation of more than one application. The bundle installer is typically used in software distribution scenarios.
TODO(crbug.com/1035895): Document bundled installers.
TODO(crbug.com/1035895): Document the standalone installer, including building a standalone installer for a given application.
Standalone installers embed all data required to install the application, including the payload and various configuration data needed by the application setup. Such an install completes even if a network connection is not available.
Standalone installers are used:
TODO(crbug.com/1139014): Document OEM.
Applications on macOS frequently install via “drag-install”, and then install the updater using a standalone installer on the application's first-run. The updater app can be embedded in a macOS application bundle as a helper and then invoked with appropriate command line arguments to install itself.
TODO(crbug.com/1327497) - document.
The updater is installed in one of the following modes (or scopes):
Per-machine and per-user instances of the updater can run side by side.
Depending on the scope, the updater is installed at:
%LOCAL_APP_DATA%\{COMPANY}\{UPDATERNAME}\{VERSION}\updater.exe%PROGRAM_FILES%\{COMPANY}\{UPDATERNAME}\{VERSION}\updater.exe~/Library/{COMPANY}/{UPDATERNAME}/{VERSION}/{UPDATERNAME}.app/Library/{COMPANY}/{UPDATERNAME}/{VERSION}/{UPDATERNAME}.appThe updater's functionality is split between several processes. The mode of a process is determined by command-line arguments:
OfflineManifest.gup or <app-id>.gup. The file contains the update check response in XML format.--handoff above.update, the server answers RPC messages on the UpdateService interface only.update-internal, the server answers RPC messages on the UpdateServiceInternal interface only.SERVICE_AUTO_START) or when CoCreate is called on one of several CLSIDs that the server supports.ServiceMain by the SCM when CoCreate is called on one of several CLSIDs that the server supports. This is used for:If none of the above arguments are set, the updater exits with an error.
Additionally, the mode may be modified by combining it with:
To maintain backwards compatibility with Omaha and Keystone, the updater installs small versions of those programs that implement a subset of their APIs.
The updater installs a Keystone-like application that contains these shims:
Both the Keystone and Keystone Agent executables simply exit immediately when run.
The ksinstall executable expects to be called with --uninstall and possibly --system. If so, it deletes the Keystone shim (but not the overall updater) from the file system. Otherwise, it exits with a non-zero exit code.
The ksadmin shim is frequently called by applications and handles a variety of command lines:
Some of these actions accept parameters:
On Windows, the updater replaces Omaha's files with a copy of the updater, and keeps the Omaha registry entry (CLIENTS/{430FD4D0-B729-4F61-AA34-91526481799D}) up-to-date with the latest pv value. Additionally, the updater replaces the Omaha uninstall command line with its own.
TODO(crbug.com/1035895): Document UI/UX.
The user interface is localized in the following languages: TBD.
TODO(crbug.com/1014591): Implement install cancellation, including cancellation ping.
The install flow can be stopped before the payload finishes downloading. In this case, the event ping associated with the install attempt will be sent with an eventresult of 4 (cancelled).
TODO(crbug.com/1286580): Implement silent mode.
Has a silent mode where the UI is not displayed at all.
If the installation fails, the updater shows an error message with a “Help” button. Clicking the help button opens a web page in the user's default browser. The page is opened with a query string: ?product={AppId}&errorcode={ErrorCode}.
TODO(crbug.com/1327491) - Implement the following algorithm.
The installsource identifies the originator of an install. It is provided on the command line of the metainstaller.
TODO(crbug.com/1327491) - is this needed? If yes, document the algorithm.
There is no limit for the number of retries to update an application if the update fails repeatedly.
The updater communicates with update servers using the Omaha Protocol.
The updater uses platform-native network stacks (WinHTTP on Windows and NSURLSession on macOS).
It is not possible to MITM the updater even if the network (including TLS) is compromised. The integrity of the client-server communication is guaranteed by the Client Update Protocol (CUP).
The legacy COM classes in updater_legacy_idl.template allow non-admin callers because the interfaces only expose functionality that non-admin callers need.
The new COM classes in updater_internal_idl.template and updater_idl.template require the callers to be admin. This is because the corresponding interfaces allow for unrestricted functionality, such as installing any app that the updater supports. For non-admins, COM creation will fail with E_ACCESSDENIED.
The updater does not retry an update check that transacted with the backend, even if the response was erroneous (misformatted or unparsable), until the next normally scheduled update check.
The updater sends DoS mitigation headers in requests to the server.
When the server responds with an X-Retry-After header, the client does not issue another update check until the specified period has passed (maximum 24 hours).
X-Retry-After was received in the background case, a foreground update is still permitted (but not if it was received in response to a foreground update).TODO(crbug.com/1329328) - document the client responsibilities.
The client records the cohort, cohortname, and cohorthint values from the server in each update response (even if there is no-update) and reports them on subsequent update checks.
As part of installing or updating an application, the updater executes the application's installer. The API for the application installer is platform- specific.
The macOS API is defined here.
TODO(crbug.com/1035895): Document Windows installer APIs
TODO(crbug.com/1339454): Run installers at BELOW_NORMAL_PRIORITY_CLASS if the update flow is a background flow.
TODO(crbug.com/1339451): Document enterprise enrollment and the token.
Enterprise policies can prevent the installation of applications:
Refer to chrome/updater/protos/omaha_settings.proto for more details.
needsadminneedsadmin is one of the install parameters that can be specified for first installs via the metainstaller tag. needsadmin is used to indicate whether the application needs admin rights to install.
For example, here is a command line for the Updater on Windows that includes:
UpdaterSetup.exe --install --tag="appguid=YourAppID&needsadmin=False"
In this case, the updater client understands that the application installer needs to install the application on a per-user basis for the current user.
needsadmin has the following supported values:
true: the application supports being installed systemwide and once installed, is available to all users on the system.false: the application supports only user installs.prefers: the application installation is first attempted systemwide. If the user refuses the UAC prompt however, the application is then only installed for the current user. The application installer needs to be able to support the installation as system, or per-user, or both modes.installdataindexinstalldataindex is one of the install parameters that can be specified for first installs on the command line or via the metainstaller tag.
For example, here is a typical command line for the Updater on Windows:
UpdaterSetup.exe /install "appguid=YourAppID&appname=YourAppName&needsadmin=False&lang=en&installdataindex =verboselog"
In this case, the updater client sends the installdataindex of verboselog to the update server.
This is how a JSON request from the updater client may look like:
{
"request":{
"@os":"win",
"@updater":"updater",
"acceptformat":"crx3",
"app":[
{
"appid":"YourAppID",
"data":[
{
"index":"verboselog",
"name":"install"
}
],
"enabled":true,
"installsource":"ondemand",
"ping":{
"r":-2
},
"updatecheck":{
"sameversionupdate":true
},
"version":"0.1"
}
],
"arch":"x86",
"dedup":"cr",
"domainjoined":true,
"hw":{
"avx":true,
"physmemory":32,
"sse":true,
"sse2":true,
"sse3":true,
"sse41":true,
"sse42":true,
"ssse3":true
},
"ismachine":false,
"lang":"en-US",
"nacl_arch":"x86-64",
"os":{
"arch":"x86_64",
"platform":"Windows",
"version":"10.0.19042.1586"
},
"prodversion":"101.0.4949.0",
"protocol":"3.1",
"requestid":"{6b417770-1f68-4d52-8843-356760c84d33}",
"sessionid":"{37775211-4487-48d5-845d-35a1d71b03bc}",
"updaterversion":"101.0.4949.0",
"wow64":true
}
}
The server retrieves the data corresponding to installdataindex=verboselog and returns it back to the updater client.
This is how a JSON response from the update server may look like:
"response":{
"protocol":"3.1",
"app":[
{"appid":"12345",
"data":[{
"status":"ok",
"name":"install",
"index":"verboselog",
"#text":"{\"logging\":{\"verbose\":true}}"
}],
"updatecheck":{
"status":"ok",
"urls":{"url":[{"codebase":"http://example.com/"},
{"codebasediff":"http://diff.example.com/"}]},
"manifest":{
"version":"1.2.3.4",
"prodversionmin":"2.0.143.0",
"run":"UpdaterSetup.exe",
"arguments":"--arg1 --arg2",
"packages":{"package":[{"name":"extension_1_2_3_4.crx"}]}}
}
}
]
}
The updater client writes this data to a temporary file in the same directory as the application installer. This is for security reasons, since writing the data to the temp directory could potentially allow a man-in-the-middle attack.
The updater client provides the temporary file as a parameter to the application installer.
Let's say, as shown above, that the update server responds with these example file contents:
{"logging":{"verbose":true}}
The updater client creates a temporary file, say c:\my path\temporaryfile.dat (assuming the application installer is running from c:\my path\YesExe.exe), with the following file contents:
\xEF\xBB\xBF{"logging":{"verbose":true}}
and then provide the file as a parameter to the application installer:
"c:\my path\YesExe.exe" --installerdata="c:\my path\temporaryfile.dat"
EF BB BF.INSTALLERDATA="pathtofile".--installerdata="pathtofile".INSTALLERDATA="pathtofile".The updater accepts updates packaged as CRX₃ files. All files are signed with a publisher key. The corresponding public key is hardcoded into the updater.
TODO(crbug.com/1035895): Document differential updates.
TODO(crbug.com/1331030): Implement differential update support.
The updater runs periodic tasks every hour, checking its own status, detecting application uninstalls, and potentially checking for updates.
The updater has a base update check period of 4.5 hours (though this can be overridden by policy). Each time the updater runs routine tasks, the update check is only run if the period has elapsed since the last check.
Since the updater's periodic tasks are run every hour, in practice the update check period is always rounded up to the nearest hour.
To prevent multiple updaters from synchronizing their update checks (for example, if a large cohort of machines is powered on at the the same time), the updater will randomly use a longer update check period (120% of the normal period) with 10% probability.
The updater will always check for updates if the time since the last check is negative (e.g. due to clock wander).
Once the updater commits to checking for updates, it will delay the actual check by a random number of milliseconds up to one minute. This avoids sychronizing traffic to the first second of each minute (or the first millisecond of each second).
Background updates can be disabled entirely through policy.
The update tasks are scheduled using the OS task scheduler.
The time resolution for tasks is 1 minute. Tasks are set to run 5 minutes after they've been created.
TODO(crbug.com/1328935): implement built in task scheduler as a failover mechanism
TODO(crbug.com/1035895): Does the updater run at user login on Windows?
The updater exposes an RPC interface for any user to trigger an update check. The update can be triggered by any user on the system, even in the system scope.
The caller provides the ID of the item to update, the install data index to request, the priority, whether a same-version update (repair) is permitted, and callbacks to monitor the progress and completion of the operation.
The interface provides the version of the update, if an update is available.
Regardless of the normal update check timing, the update check is attempted immediately.
The updater exposes an RPC interface for users to register an application with the updater. Unlike on-demand updates, cross-user application registration is not permitted.
If the application is already installed, it is registered with the version present on disk. If it has not yet been installed, a version of 0 is used.
Applications can report whether they are actively used or not through the updater. Update servers can then aggregate this information to produce user counts.
Software can be installed or updated only if the user has agreed to the Terms of Service. The updater only runs if the user has accepted the ToS for at least one application.
TODO(crbug.com/1035895): Document EULA signals.
The updater may upload its crash reports and send usage stats if and only if any piece of software it manages is permitted to send usage stats.
HKCU\SOFTWARE\{Company}\Update\ClientState\{APPID} → usagestats (DWORD): 1 or HKLM\SOFTWARE\{Company}\Update\ClientStateMedium\{APPID} → usagestats (DWORD): 1IsUploadEnabled to true for a crashpad database maintained in a “Crashpad” subdirectory of their application data directory.TODO(crbug.com/1035895): Document relevant enterprise policies.
TODO(crbug.com/1035895): Implement this section. (ADMX file export.)
ADMX templates are provided.
When the updater installs an application (an installer is run) it sends an event with "eventtype": 2 indicating the outcome of installation. The updater does not send such a ping for its own installation.
When the updater updates an application (including itself) it sends an event with "eventtype": 3 indicating the outcome of update operation.
When the updater detects the uninstallation of an application, it sends an event with "eventtype": 4 to notify the server of the uninstallation.
When the updater attempts to download a file, it sends an event with "eventtype": 14 describing the parameters and outcome of the download.
Multiple events associated with an update session are bundled together into a single request.
There could be multiple URLs for a given application payload. The URLs are tried in the order they are returned in the update response.
The integrity of the payload is verified.
There is no download cache. Payloads are re-downloaded for applications which fail to install.
All updater logs are written to {UPDATER_DATA_DIR}\updater.log.
On macOS for system-scope updaters, {UPDATER_DATA_DIR} is /Library/Application Support/{COMPANY_SHORTNAME}/{PRODUCT_FULLNAME}.
On macOS for user-scope updaters, {UPDATER_DATA_DIR} is ~/Library/Application Support/{COMPANY_SHORTNAME}/{PRODUCT_FULLNAME}.
On Windows for system-scope updaters, {UPDATER_DATA_DIR} is %PROGRAMFILES%\{COMPANY_SHORTNAME}\{PRODUCT_FULLNAME}. (A 32-bit updater uses use %PROGRAMFILESX86% if appropriate instead.)
On Windows for user-scope updaters, {UPDATER_DATA_DIR} is %LOCALAPPDATA%\{COMPANY_SHORTNAME}\{PRODUCT_FULLNAME}.
TODO(crbug.com/1035895): Document updater crash reporting.
The feature allows installed products to pre-register and later run elevated command lines in the format c:\program files\foo\exe.exe params. Multiple command lines can be registered per app_id.
This feature is only for system applications.
The program path is always an absolute path. Additionally, the program path is also a child of %ProgramFiles% or %ProgramFiles(x86)%. For instance:
c:\path-to-exe\exe.exe is an invalid path."c:\Program Files\subdir\exe.exe" is a valid path."c:\Program Files (x86)\subdir\exe.exe" is also a valid path.Commands are registered in the registry with the following format:
Update\Clients\{`app_id`}
REG_SZ `command_id` == "c:\Program Files\subdir\exe.exe p1 p2"
Once registered, commands may be invoked using the LaunchCmdElevated method in the IProcessLauncher interface.
The feature allows installed products to pre-register and later run command lines in the format c:\path-to-exe\exe.exe {params} (elevated for system applications). {params} is optional and can also include replaceable parameters substituted at runtime. Multiple app commands can be registered per app_id.
The program path is always an absolute path. Additionally, for system applications, the program path is also a child of %ProgramFiles% or %ProgramFiles(x86)%. For instance:
c:\path-to-exe\exe.exe is an invalid path."c:\Program Files\subdir\exe.exe" is a valid path."c:\Program Files (x86)\subdir\exe.exe" is also a valid path.App commands are registered in the registry with the following formats:
Update\Clients\{`app_id`}\Commands\`command_id`
REG_SZ "CommandLine" == {command format}
{optional} REG_DWORD "AutoRunOnOSUpgrade" == {1}
Update\Clients\{`app_id`}
REG_SZ `command_id` == {command format}
Example {command format}: c:\path-to\echo.exe %1 %2 %3 StaticParam4
As shown above, {command format} needs to be the complete path to an executable followed by optional parameters.
If “AutoRunOnOSUpgrade” is non-zero, the command is invoked when the updater detects an OS upgrade. In this case, command format can optionally contain a single substitutible parameter, which is filled in with the OS versions in the format {Previous OS Version}-{Current OS Version}. It is ok to have a static command line as well if the OS versions information is not required.
Once registered, commands may be invoked using the execute method in the IAppCommandWeb interface.
interface IAppCommandWeb : IDispatch {
// Use values from the AppCommandStatus enum.
[propget] HRESULT status([out, retval] UINT*);
[propget] HRESULT exitCode([out, retval] DWORD*);
[propget] HRESULT output([out, retval] BSTR*);
HRESULT execute([in, optional] VARIANT substitution1,
[in, optional] VARIANT substitution2,
[in, optional] VARIANT substitution3,
[in, optional] VARIANT substitution4,
[in, optional] VARIANT substitution5,
[in, optional] VARIANT substitution6,
[in, optional] VARIANT substitution7,
[in, optional] VARIANT substitution8,
[in, optional] VARIANT substitution9);
};
Here is a code snippet a client may use, with error checking omitted:
var bundle = update3WebServer.createAppBundleWeb(); bundle.initialize(); bundle.createInstalledApp(appGuid); var app = bundle.appWeb(0); cmd = app.command(command); cmd.execute();
Parameters placeholders (%1-%9) are filled by the numbered substitutions in IAppCommandWeb::execute. Placeholders without corresponding substitutions cause the execution to fail.
Clients may poll for the execution status of commands that they have invoked by using the status method of IAppCommandWeb. When the status is COMMAND_STATUS_COMPLETE, the exitCode method can be used to get the process exit code.
%ProgramFiles% for security, since it runs elevated.% followed by a digit. Literal % characters are escaped by doubling them.For example, if substitutions to IAppCommandWeb::execute are AA and BB respectively, a command format of: echo.exe %1 %%2 %%%2 becomes the command line echo.exe AA %2 %BB
The feature allows Chrome and other applications to query the policies that are currently in effect.
Chrome Browser Enterprise (CBE) admins sometimes want to understand if the update policies they have set have propagated to the clients.
Without this API, the only way they can do this is to open up regedit to see if the GPO has propagated correctly.
In addition there is a delay between when the GPO is set on the server and when the value is propagated on the client so being able to verify that the updater picks up the policy can help debug propagation issues as well.
The IPolicyStatus/IPolicyStatus2/IPolicyStatus3 interfaces therefore expose this functionality that can be queried and shown in chrome://policy.
IPolicyStatus/IPolicyStatus2/IPolicyStatus3 interface definition
On Mac and Linux, if the application was registered with an existence path checker and no file at that path exists (or if the file at that path is owned by another user), the updater considers the application uninstalled, sends the ping, and stops trying to keep it up to date.
On Windows, if the ClientState entry for for the application is deleted, the app is considered uninstalled.
On Windows, the updater registers a “UninstallCmdLine” under the Software\ {Company}\Updater key. This command line can be invoked by application uninstallers to cause the updater to update its registrations. The updater also checks for uninstallations in every periodic task execution.
When the last registered application is uninstalled, the updater uninstalls itself immediately. The updater also uninstalls itself if it has started 24 times but never had a product (besides itself) registered for updates.
The updater uninstaller removes all updater files, registry keys, RPC hooks, scheduled tasks, and so forth from the file system, except that it leaves a small log file in its data directory.
Building the updater produces both a production-ready updater executable and a version of the executable used for the purposes of testing. The test executable is identical to the production one except that it allows cetain constants to be overridden by the execution environment:
url: Update check & ping-back URL.use_cup: Whether CUP is used at all.cup_public_key: An unarmored PEM-encoded ASN.1 SubjectPublicKeyInfo with the ecPublicKey algorithm and containing a named elliptic curve.group_policies: Allows setting group policies, such as install and update policies.Overrides are specified in an overrides.json file placed in the updater data directory.
TODO(crbug.com/1035895): Document tagging tools.