This is the user manual for Chromium Updater.
Chromium Updater is an out-of-process service that finds and applies updates to software. Integrating with Chromium Updater requires:
Additionally, applications should take care to:
Chromium Updater identifies each application by means of an “App ID”. An app ID can be any ASCII string. For example, the App ID of Google Chrome (Windows) is {8A69D345-D564-463C-AFF1-A69D9E530F96}, and the App ID of Google Chrome (macOS) is COM.GOOGLE.CHROME.
Acquiring a unique App ID is the first step to integrating with the updater. Consult your organization's update server team to obtain an ID.
App IDs are case-insensitive.
Chromium Updater can be installed in one of two scopes: system wide, or for the current OS user only. System installations are appropriate if the software's installation requires administrative privileges or should be shared between multiple OS users. System installations require the user to have admin privileges at the time of the installation, but thereafter silently keep the software up to date.
On Windows, applications are most commonly distributed by means of UpdaterSetup.exe, a “tagged metainstaller” that first installs the updater, then registers the application with the updater and asks the updater to “update” (install) it. This has the advantage that even if UpdaterSetup.exe is old, the newest version of the application is always installed on the system. UpdaterSetup.exe also provides UI and manages integration with the updater.
UpdaterSetup.exe can also be used to install the updater alone, by running UpdaterSetup.exe --install --system. (For user installs, elide --system.)
For security reasons, applications that install at system scope must install into C:\Program Files or a similar path that non-admins don't have write access to. System-scope installers are run with system privileges, and writing or deleting paths under user control as system creates a privilege escalation vulnerability on the system.
When an application installer successfully runs, it should write (HKCU or HKLM)\SOFTWARE\{Company}\Update\Clients\{AppID} → pv to the version that was installed.
On macOS, applications are most commonly distributed either by means of a PKG installer or a “drag-install” experience in a mountable DMG.
Applications installing via a PKG installer should bundle and install {Company}Updater.pkg as part of their installation. Such an installation is always system-wide. The application should run a postinstall script registering itself with the updater by calling /Library/Application Support/{Company}/{Company}Updater/Current/{Company}Updater.app/Contents/Helpers/{Company}SoftwareUpdater.bundle/Contents/Helpers/ksadmin -r -P product_id -v version -x path_to_application_bundle -S.
Applications installing via a DMG experience must set up the updater during first run. These applications should embed the updater in their app bundle as a “Helper”, and install by running {App Bundle}/Contents/Helpers/{Company}Updater.app/Contents/MacOS/{Company}Updater --install. The application should then register itself with the updater by calling ~/Library/Application Support/{Company}/{Company}Updater/Current/{Company}Updater.app/Contents/Helpers/{Company}SoftwareUpdater.bundle/Contents/Helpers/ksadmin -r -P product_id -v version -x path_to_application_bundle -U.
If the app is running as root, it must add --system to the install command above, use -S instead of -U in the ksadmin command, and use the ksadmin in /Library instead of ~/Library.
Additional registration arguments are available to register additional data and provide alternative ways to track the version of a product.
Repeating the updater installation and app registration is not harmful. To make the system more resilient, apps may periodically repeat the installation and registration process.
An Objective-C library to perform these operations is in development. When available, applications will be able to initialize CRURegistration with their product IDs, then use installUpdaterWithReply: and registerVersion:existenceCheckerPath:serverURLString:reply: to install the updater (if needed) and register. These methods operate asynchronously using dispatch/dispatch.h mechanisms. CRURegistration maintains an internal task queue, so clients can call register... immediately after install... without waiting for a result.
CRURegistration uses the helpers and command line binaries documented above. To install the updater using CRURegistration, the updater must be embedded as a Helper as documented above.
CRURegistration is designed to depend only on APIs published in macOS SDKs and compile as pure Objective-C (without requiring C++ support) so it can be dropped into projects without incurring Chromium dependencies.
The updater will uninstall itself automatically when it has no applications to manage, but it may need some help to do so in a timely manner.
On Windows, when an application is uninstalled, it should delete the (HKCU or HKLM)\SOFTWARE\{Company}\Update\Clients\{AppID} key and then run the command line in (HKCU or HKLM)\SOFTWARE\{Company}\Updater → UninstallCmdLine. This will notify the updater of the uninstallation.
On macOS, it is assumed that users uninstall software by deleting the app bundle. The updater will notice this on its own in a few hours. However, it can be notified earlier by running any {Company}Updater.app/Contents/MacOS/{Company}Updater --wake-all (with --system for system-scope installs).
Command line arguments for the updater client are documented in the functional spec.
The updater setup process can exit with the following error codes:
Windows tagged metainstallers support a number of dynamic install parameters:
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="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.
The server retrieves the data corresponding to installdataindex=verboselog and returns it back to the updater client.
The updater client writes this data to a temporary file in the same directory as the application installer.
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 will now create 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 Application Command feature allows installed Updater-managed products to pre-register and then later run command lines (elevated for system applications). The command lines can also include replaceable parameters substituted at runtime.
For more information, please see the functional spec.
The updater writes logs to its product directory, whether or not it is installed. Note that there are two possible product directories (one for system scope and one for user scope), and so there are often two log files.
See the functional spec for more details.