Previous versions are described at:
* [Version 3.1](https://chromium.googlesource.com/chromium/src.git/+/master/docs/updater/protocol_3_1.md)
* [Version 3](https://github.com/google/omaha/blob/master/doc/ServerProtocolV3.md)
* [Version 2](https://github.com/google/omaha/blob/master/doc/ServerProtocolV2.md)
* Version 1 of the protocol was never publicly deployed.
[TOC]
NOTE: this is a draft version of Omaha Protocol 4.0.
## Introduction
The Omaha protocol defines the interactions between a software updater (an
"Omaha Client") and a cloud update infrastructure. The cloud infrastructure
contains both an update control server (an "Omaha Server") and a collection of
plain HTTP servers or CDNs (collectively, the "Download Servers"). The protocol
is an application-layer protocol on top of HTTP.
Omaha clients interact with the servers in a three-phase **session**. Each step
in the session involves at least one successful HTTP transaction.
1. **The Update Check**: The client transmits what applications it has
installed that may be eligible for update to the server. The server replies
with whether an update is available for each application. If no updates are
available, this is the end of the update session.
2. **The Download(s)**: The client downloads the updates from the download
servers. It then executes downloaded installers or its own code to apply
these updates.
3. **The Ping-Back(s)**: The client transmits data about its activities back
to the server, including whether the updates were successful, which
download URLs were used, and any error codes encountered.
The update check is an HTTP POST with a JSON data body. The response has a JSON
data body. The integrity of the update check is protected by [CUP](cup.md), even
in the presence of compromised TLS.
The downloads are HTTP GET requests. The client is free to use any HTTP
technology to fetch the downloads, for example using Range requests.
The ping-back is an HTTP POST with a JSON data body. The response may contain a
JSON data body acknowledging the received data, but should be ignored by the
client unless CUP is in use on this request.
## Concepts
### Session ID
All requests in a session are linked by a unique **session ID**. Session IDs are
random strings with at least 128 bits of entropy. There must be no relationship
between a previous session ID and the next session ID. In the update check and
ping-back requests the session id is transmitted in the POST body (details
below). In the download requests it is transmitted as an HTTP header (details
below).
### Request ID
Each update check has a unique **request ID**. Each ping-back has a different
unique request ID. Request IDs are random strings with at least 128 bits of
entropy. There must be no relationship between a previous request ID and the
next request ID. Request ID allows an Omaha server to deduplicate repeated
requests, which have been observed as part of client or proxy retry loops.
### Default Values
The request bodies of the update check and ping-back requests are JSON. Most
members have a default value defined by this protocol. Clients and servers may
omit serialization of any members the have default values. Therefore, if a
client or server does not send the member, the recipient must assume the default
value of that member.
The default value of any list-valued member is the empty list. The default value
of any object-valued member is an empty object (which is equivalent to an object
of the appropriate type populated with its default members).
Compatible clients and servers must be able to tolerate unexpected members.
### Version Numbers
Version numbers are strings of the form A.B.C.D, where A, B, C, and D are
base 10 integers between 0 and 2^32 - 1 (inclusive). Suffix elements may be
omitted if equal to 0; that is, "1.2" is equal to "1.2.0.0".
Version numbers are ordered. Version A is greater than version B if and only if
there some element of version A is greater than the corresponding element of
version B, and all the preceding elements are equal. Two versions are equal if
any only if all their elements are equal.
### Application IDs
An application ID is a string that identifies an application, for example
"com.google.chrome". Application IDs are case-insensitive in the ASCII
characters. Application IDs should only contain printable, human-readable
characters.
### User Counting
The Omaha protocol is anonymous, but allows servers to compute the number of
unique active or update-checking devices. This is accomplished through
client-regulated counting.
The idea of client-regulated counting is to inspect all update check requests
received over the last N days and discard all but the first request from each
client. The number of remaining requests is equal to the number of unique
clients.
Each response from the server contains a numeric date, representing the date (in
the server's choice of timezone) that the client's request was received. The
client stores this date, and sends it on the next request to the server. When
inspecting the next request, the server can determine whether the date is before
(current date - N + 1). If so, this is the first request from the client in the
N-day window. Otherwise, this request is a "duplicate" and can be discarded.
In certain environments (for example, frequently re-imaged VMs in internet
cafes), it is likely that the client may fail to update the date of the last
transaction. To avoid overcounting such clients, a technique called
ping-freshness is used. A ping-freshness value is a random string with at least
128 bits of entropy that is written into the client's data store alongside the
server's date. This value is sent along with the date in the next request. If
the server receives multiple requests with the same ping-freshness, this is a
signal that a machine's state has been cloned or reset and that the dates in the
request are not trustworthy. A new ping-freshness value is written any time a
new date is written.
In addition to counting the total population for each application, the Omaha
protocol counts the active user population for each application. When an
application is actively used, it signals this to the client, and the client will
transmit the "last reported active" date to the server on the next update check
(in addition to the "last checked" date). These dates are separately writeable
and therefore need separate ping-freshness values as well.
The "last reported active" and "last checked" date may vary per managed
application, and the client must maintain separate dates (and separate
ping-freshness values) per application.
### Differential Updates
A differential update achieves better compression by relying on information
(e.g. cached payloads) that the client already has.
A version number is usually insufficient to identify the binaries the client
already has, since they may vary by architecture, platform, or other variables
while retaining the same official version number. Therefore, the server sends a
more precise label with each package. Once an update payload is installed, the
"package fingerprint" that is associated with this payload is then sent back in
subsequent update checks.
The package fingerprint sent by the server must identify the payload that will
eventually be installed by the client as a result of processing the server's
response. This will usually be derived from a checksum of the package payload,
which will be different from the payload the client initially downloads if the
downloaded payload is compressed, differential, or otherwise transformed.
### Pipelines
A pipeline represents a series of operations to obtain and process a payload in
order to update to a new version of a given product. The protocol defines
various operations to support full, differential, and/or compressed update
payloads. The client must specify when sending a request what pipeline
operations it supports. Additional pipeline operations may be added in the
future.
The update response sent to the client contains a list of pipelines, each
producing the same end result. The pipelines are listed in order of preference,
and must be attempted by by the client in that order. If a pipeline fails, the
client will attempt the next pipeline available, proceeding until either a
pipeline is successful, or all pipelines have failed. This increases the
probability that a pipeline will be applied, even if all differential pipelines
fail.
### Extensions & Forward Compatibility
The protocol is extensible via the addition of new object members. Clients must
tolerate the existence of members they do not handle. Unofficial or
application-specific additional members should be prefixed with an underscore to
avoid colliding with later additions to the protocol.
Additions to the protocol that specify backward-compatible default values (often
with a semantic meaning of "unknown") do not need to increase the protocol
version. Removals of values with specified defaults from the protocol do not
need to increase the protocol version, since the default value can be assumed by
compatible endpoints. All other changes to the protocol may require a new
version number.
### Timing & Backoff
Clients and servers are free to negotiate the rate at which the client conducts
update sessions. However, the following best practices are recommended:
* If a client periodically checks according to a time-elapsed scheduled task,
(e.g. "check every 5 hours"), those checks should happen at an interval
that is coprime with a 24-hour day. This prevents a specific client from
being locked to a particular set of times at which it checks for an update.
* As much as possible while respecting a user or administrator's preferences,
clients should avoid check policies that rely on specific clock values
(e.g. "check at 5:00 AM"). Clocks throughout the world are roughly
synchronized and update schedules like this cause abrupt spikes in update
load on update infrastructure.
* If a client cannot conduct a check at the scheduled time (it is in an off
or standby power state or lacks network connectivity, the client should
check as soon as it recovers from that condition (subject to the below).
This allows clients who are only briefly connected to reliably update.
* A client doing periodic checks should implement a random chance to postpone
a periodic update by a fraction of that period. Client update schedules can
become synchronized by server-side or network outages, by image cloning, by
synchronized installations, or other effects. This behavior gradually
desynchronizes a cohort of clients that have become synchronized for any
reason. A 20% chance to delay by 0% to 20% of the period (chosen randomly)
is generally good enough.
* Clients should avoid checking at a predictable millisecond within the
second, a predictable second within the minute, or a predictable minute
within the hour. This both helps resist fingerprinting of the client and
smooths load on the server, which might otherwise have spikes of traffic at
precisely 1:00:00.000, 1:00:01.000, 1:01:00.000, etc.
In the case of update check failure, retries are generally permitted. The client
is free to attempt an immediate retry or a retry after a delay.
At scale, even a single retry may double load on the update server regardless of
any client delay (unless the client simply delays to its next normal periodic
update check. Clients must not retry if they successfully receive a
CUP-validated response from the server, regardless of the contents. Servers may
protect themselves in the case of overload by issuing an X-Retry-After HTTP
header, detailed [below](#headers-update-check-response).
For download requests, clients should prefer to fall back to subsequent download
URLs rather than attempting retries on a particular URL.
### Safe JSON Prefixes
JSON responses from the server are prefixed with `)]}'\n`, where \n indicates a
new line character. This prevents them from being naively executed as a script
in the context of the update server's origin.
## Update Checks
An update check is the first phase of an Omaha session. In an update check, the
client sends information about what applications it is managing and the server
responds with whether any updates are available for the applications.
### URL (Update Check Request)
Update check requests will bear a query parameter as defined by [CUP](cup.md).
### Headers (Update Check Request)
Clients should send the following headers with each request. Request headers are
not protected by CUP and therefore should be considered untrusted data. They are
advisory data replicated from the request body so that server-side DoS
prevention mechanisms can inexpensively reject traffic (i.e. without parsing the
request body).
* `X-Goog-Update-Interactivity`: Either "fg" or "bg". "fg" indicating a
user-initiated foreground update. "bg" indicates that the request is part
of a background update. If the server is under extremely high load, it may
use this to prioritize "fg" requests over "bg" requests.
* `X-Goog-Update-AppId`: A comma-separated list of application IDs included
in this request.
* `X-Goog-Update-Updater`: "name-version", where "name" is the name of the
updater as reported in `request.updater` and "version" is the version of
the updater as reported in `request.updaterversion`.
### Body (Update Check Request)
The request body of an update check contains a JSON object with the following
members:
* `request`: A `request` object.
#### `request` Object (Update Check Request)
A request object has the following members:
* `@os`: A string identifying the operating system.
Added for backwards compatibility with Chrome Web store.
Recommend: new servers should use `os` member instead.
Default: "". Known values include:
* "android": Android.
* "cros": ChromeOS.
* "fuchsia": Fuchsia.
* "linux": Linux.
* "mac": macOS.
* "openbsd": OpenBSD.
* "win": Windows.
* `@updater`: A string identifying the client software (e.g. "Omaha",
"Chrome", "Chrome Extension Updater"). Default: "".
* `acceptformat`: A string, formatted as a comma-separated list of strings,
describing the pipeline operations that this client can perform.
Default: "".
The valid operations are any of the types supported by the
[Operation Object](#operation-objects-update-check-response)
* `app`: A list of `app` objects.
* `dedup`: A string, must be "cr". This indicates to servers that the client
intends to use client-regulated counting algorithms rather than any sort of
unique identifier. Version 3.0 of the protocol also supported "uid".
* `dlpref`: Specifies the preferred download URL behavior. A comma-separated
list of values, in order of descending priority. Default: "". Legal values
include:
* "" (empty string): No preference.
* "cacheable": Proxy-cacheable download URLs are preferred.
* `domainjoined`: A boolean. True if the device is a managed enterprise
device that will respect enterprise group or cloud policies. False
otherwise.
* `hw`: A `hw` object (see below).
* `ismachine`: Whether this client is installed system-wide or only for a
single user. Default: -1. Legal values:
* -1: unknown
* 1: this client is installed in a cross-user context.
* 0: this client is installed only for the current user.
* `os`: An `os` object.
* `protocol`: The version of the Omaha protocol. Clients must transmit "4.0"
as the value when using this protocol.
* `requestid`: A randomly-generated string, unique to this request. Default:
"" (empty string).
* `sessionid`: A randomly-generated string, unique to this update session.
Default: "" (empty string).
* `testsource`: A string set in tests, developer requests, or automated
probers to distinguish this request from real user traffic. Any value
other than the empty string indicates that the request should not be
counted toward official metrics. Default: "" (empty string).
* `updater`: A list of `updater` objects.
* `updaterchannel`: If present, identifies the distribution channel of the
client (e.g. "stable", "beta", "dev", "canary", "extended"). Default: "".
* `updaterversion`: The version of the client that is sending this request.
Default: "0".
#### `hw` Objects (Update Check Request)
An `hw` object contains information about the capabilities of the client's
hardware. It has the following members:
* `sse`: "1" if the client's hardware supports the SSE instruction set. "0"
if the client's hardware does not. "-1" if unknown. Default: "-1".
* `sse2`: As `sse` but for the SSE2 instruction set extension.
* `sse3`: As `sse` but for the SSE3 instruction set extension.
* `sse41`: As `sse` but for the SSE4.1 instruction set extension.
* `sse42`: As `sse` but for the SSE4.2 instruction set extension.
* `ssse3`: As `sse` but for the SSSE3 instruction set extension.
* `avx`: As `sse` but for the AVX instruction set extension.
* `physmemory`: The physical memory the client has available to it, measured
in gibibytes, truncated down to the nearest gibibyte, or "-1" if unknown.
This value is intended to reflect the maximum theoretical storage capacity
of the client, not including any hard drive or paging to a hard drive or
peripheral. Default: "-1".
#### `os` Objects (Update Check Request)
An `os` object contains information about the operating system that the client
is running within. It has the following members:
* `platform`: The operating system family that the client is running within
(e.g. "win", "mac", "linux", "ios", "android"), or "" if unknown. The
operating system family name should be transmitted in a canonical form.
Formatting varies across implementations. Default: "". Known values:
* "android" or "Android": Android.
* "chromeos" or "ChromeOS" or "Chrome OS": Chrome OS.
* "chromiumos" or "ChromiumOS" or "Chromium OS": Chromium OS.
* "dragonfly": DragonFly BSD.
* "freebsd" or "FreeBSD": FreeBSD.
* "Fuchsia": Fuchsia.
* "ios" or "iOS": Apple iOS.
* "linux" or "Linux": Linux and its derivatives, except as mentioned
below.
* "mac" or "Mac OS X": Apple macOS and its derivatives.
* "openbsd" or "OpenBSD": OpenBSD.
* "Solaris": Solaris.
* "win" or "Windows": Microsoft Windows and its derivatives.
* "Unknown": Sent by some clients instead of "" when the platform is not
recognized.
* `version`: The version number of the operating system, or "" if unknown.
Default: "".
* `sp`: The service pack level of the operating system, or "" if unknown or
not applicable. Default: "".
* On Windows, the service pack should be formatted as a Title Case
string (e.g. "Service Pack 2").
* `arch`: The architecture of the operating system, or "" if unknown.
Default: "". Known Values:
* "arm": ARM
* "arm64": 64-bit ARM
* "x86": x86
* "x86_64": x86-64
* "x64": x64
#### `app` Objects (Update Check Request)
Each managed application is represented by exactly one `app` object. It has the
following members:
* `appid`: The [application id](#application-ids) that identifies the
application. Default: Undefined - Clients must transmit this attribute.
* `brand`: The brand code corresponding to the partner promotion that
triggered the installation of the application. Brand codes usually match
the [A-Z]{4} regex, but the protocol supports any string. Default: "".
* `cohort`: A machine-readable string identifying the release cohort
(channel) that the app belongs to. Limited to ASCII characters 32 to 126
(inclusive) and a maximum length of 1024 characters. Default: "".
* `cohorthint`: A value that expresses a client request to move to another
release cohort. The exact values may be application-specific and should be
set up ahead of time on the server. Default: "".
* `cohortname`: A human-readable string identifying the semantics behind the
current cohort. For example, this might be displayed to the user and
indicate the channel or experimental status. Default: "".
* `release_channel`: The target channel that the app switches to. For
example an app can have stable, beta, dev, and canary channels. Note
switching to an older channel may have no effect until the older channel
catches up with the install. Ex: a machine on today's beta (107.0.5304.62)
that is switched to stable will stay on that version until 107 ships to
stable. Downgrade can be forced by the use of the `rollback_allowed` in
the `updatecheck` node.
* `data`: A list of `data` objects.
* `disabled`: A list of `disabled` objects.
* `enabled`: Indicates whether the application is enabled on the client. As
an example, Chrome extensions can be put into a "disabled" state without
uninstallation. A value of "-1" indicates that the enabled status is
unknown, or that the concept of enabling/disabling does not exist. "0"
indicates that the application is disabled. "1" indicates that the app is
enabled. Default: "-1".
* `fp`: A `fingerprint` object representing the currently installed
[package fingerprint](#differential-updates) of the application.
* `cached_fingerprints`: A list of `fingerprint` objects, one for each
currently cached [package fingerprint](#differential-updates)
of the application. This list may be empty if the local cache is empty or
does not exist.
* `iid`: Installation ID is an opaque token that identifies an installation
flow. The installation ID is a unique identifier embedded into a
metainstaller for the application. It can be used to correlate the first
update-check of an application with web actions and the application
download. To avoid creating a persistent unique identifier for this
installation, clients must clear the `iid` value after transmitting it
once. Default: "".
* `installdate`: The approximate date that the application installation took
place on, or "-2" if unknown or not applicable. Default: "-2". During the
installation request itself (the first communication to the server), the
client should use a special value of "-1". The
`response.daystart.elapsed_days` value for that request's response should
be stored to use in all subsequent requests. To mitigate privacy risk,
clients should fuzz the value to the week granularity by storing X - X % 7,
where X is the server-provided date. For offline installs, the client
should send -2. Default: -2.
* `installedby`: A string describing the original cause of the installation.
The string should be drawn from a small set of constant values, to minimize
entropy and the ability for the client to be fingerprinted. Default: "".
* `installsource`: A string describing the immediate cause of this request.
Known values include: "" (a normal background update) and "ondemand" (a
foreground, user-initiated update). Default: "".
The string should be drawn from a small set of constant values, to minimize
entropy and the ability for the client to be fingerprinted.
* `ismachine`: "0" if the application is installed for the user specifically
(i.e. elevated privileges are not needed to update it). "1" if the
application is installed in a cross-user (system or privileged) context.
"-1" if unknown or not applicable. Default: "-1"
* `lang`: The language of the application installation, in BCP 47
representation, or "" if unknown or not applicable. Default: "".
* `ping`: A `ping` object.
* `tag`: A string, representing arbitrary application-specific data that the
client wishes to disclose to the server. Clients should prefer to extend
this protocol with additional attributes rather than use this field, but in
some cases transmission of opaque or unparsable data is necessary (for
example, transmitting the tag of a tagged metainstaller). Default: "".
* `version`: The [version number](#version-numbers) of the current
installation of the application. A successful installation of an update
should change this version in future requests, even if the old version of
the application may still be running.
Default: "0".
* `updatecheck`: An `updatecheck` object. This member may be omitted if the
client will not honor an update response.
#### `fingerprint` Objects (Update Check Request)
A `fingerprint` object contains a string representing the
[package fingerprint](#differential-updates) for this update.
* `fingerprint`: The package fingerprint for this package given as a string,
or "" if the fingerprint is unknown. Default: "".
#### `ping` Objects (Update Check Request)
* `ad`: The date that the previous active report took place on, or "-1" if
this is the first active report for the application. "-2" if the date of
the previous active report is unknown or the app has not been active since
the previous active report. Default: "-2". If not "-2", this request is an
active report. If "-2" but the application is known to have been active,
this request is an active report. In response to the previous active
report, the server responded with the date in the `response.clock.date`
member. See [User Counting](#user-counting).
* `rd`: The date that the previous roll call took place on, or "-1" if this
is the application's first roll call, or "-2" if the date of the previous
roll call is not known. Default: "-2". This request is a roll call,
regardless of the value of this member. In response to the previous roll
call, the server responded with the date in the `response.clock.date`
member. See [User Counting](#user-counting).
* `ping_freshness`: A random 128-bit number, written into the client's
storage alongside the next value of rd, and rotated whenever the client
stores a new value for rd. See [Ping Freshess](#ping-freshness). A value of
"" (empty string) indicates that no value was available. Default: "".
#### `data` Objects (Update Check Request)
A data object represents a request for arbitrary specific application-specific
data from the server. The server maintains a map of index values to data
contents, and can supply them if requested. This is used during installation to
transmit alternate branding or seeded configurations to the application. `data`
objects have the following members:
* `name`: The type of data lookup to perform. The only known supported value
is "install". Default: "".
* `index`: The key to look up on the server. Default: "".
#### `disabled` Objects (Update Check Request)
A disabled object contains information about why an app is disabled. Multiple
causes for a disabled state may exist.
* `reason`: an numeric reason that the app is disabled. The meaning of these
values are client-specific (possibly app-specific), except for "0", which
indicates no reason. Default: "0".
#### `updatecheck` Objects (Update Check Request)
An updatecheck object represents the actual intent to update. It has the
following members:
* `rollback_allowed`: true if the client will accept a version downgrade.
Typically used in conjunction with a targetversionprefix. Default: false.
* `sameversionupdate`: true if the client is requesting that it be updated
to the version it currently has (usually as part of a repair or
overinstallation) instead of receiving no update. Default: false.
* `targetversionprefix`: A component-wise prefix of a version number, or a
complete version number. The server SHOULD NOT return an update
instruction to a version number that does not match the prefix or complete
version number. The prefix is interpreted a dotted-tuple that specifies
the exactly-matching elements; it is not a lexical prefix. (For example,
"1.2.3" matches "1.2.3.4" but not "1.2.34".) Default: "".
* `updatedisabled`: An indication of whether the client will honor an update
response, if it receives one. Legal values are "true" (indicating that the
client will ignore any update instruction) and "false" (indicating that the
client will attempt an update if one is instructed). Default: "false".
#### `updater` Objects (Update Check Request)
An updater object represents the state of another sibling update program on
the system. Clients report about other updaters present on the system to enable
redundancy and recoverability of sibling updaters. For example, Chrome is
normally updated by GoogleUpdate, but in cases where GoogleUpdate has been
disabled or is broken (according to the data transmitted here), the server can
issue a pipeline for Chrome to attempt recovery of GoogleUpdate. An updater
object has the following members:
* `autoupdatecheckenabled`: 1 if the other updater is subject
to an enterprise policy that disables its update-checking functionality. 0
if not. -1 if unknown. Default: -1.
* `ismachine`: 1 if the updater has system or administrator
privileges, or if it is installed in a cross-user context. 0 if not. -1 if
unknown. Default: -1.
* `lastchecked`: An estimated number of hours since the other updater
successfully checked for an update. A value of -1 indicates the last check
time is unknown. Default: -1. Clients should limit the accuracy of this
value in order to prevent an observer from correlating this request to the
one last sent by the subject updater.
>Chrome only sends the following values:
>* -1: unknown
>* 0: [0, 336) hours ago (0 to < ~2 weeks)
>* 336: [336, 1344) hours ago (~2 weeks to ~2×28 days)
>* 1344: at least 1344 hours ago (~2×28 days or more)
* `laststarted`: An estimated number of hours since the other updater
successfully ran (started and exited without crashing). A value of -1
indicates the last check time is unknown. Default: -1. Clients should
limit the accuracy of this value in order to prevent an observer from
correlating this request to the one last sent by the subject updater.
>Chrome only sends the following values:
>* -1: unknown
>* 0: [0, 336) hours ago (0 to < ~2 weeks)
>* 336: [336, 1344) hours ago (~2 weeks to ~2×28 days)
>* 1344: at least 1344 hours ago (~2×28 days or more)
* `name`: The name of the other updater.
* `updatepolicy`: A numeric indicator of what kind of updater policy the
other updater has about updating this client. Default: -2. Known values:
* -2: unknown
* -1: no such policy exists
* 0: policy set to allow background and foreground updates.
* 1: policy set to allow background updates only.
* 2: policy set to allow foreground updates only.
* 3: policy set to disable updates.
* `version`: The current version number of the other updater. Default: "0".
---
### Headers (Update Check Response)
In addition to normal HTTP headers, this protocol defines the following update
check response headers:
* `X-Cup-Server-Proof`: Contains the CUP signature of the response.
* `X-Retry-After`: If present, a positive integer, representing a number of
seconds for which the client mut not contact the server again for
background updates, including but not limited to retries of this particular
request. Clients must respect this header even if paired with
non-successful HTTP response code. Servers should not send a value in
excess of 86400 (24 hours), and clients should treat values greater than
86400 as 86400. Clients may still send a ping-back for this update session.
### Body (Update Check Response)
The response body of an update check begins with `)]}'\n`, where \n indicates a
newline character, followed by a JSON object with the following members:
* `response`: A `response` object.
#### `response` Objects (Update Check Response)
A response object contains the server's response to a corresponding `request`
object in the update check request.
* `app`: A list of `app` objects. There is one object for each `app` in the
request body.
* `daystart`: A `daystart` object.
* `systemrequirements`: A `systemrequirements` object. The server will not
send this element, but it may be present in offline installer manifests.
* `protocol`: The version of the Omaha protocol. Servers responding with this
protocol must send a value of "4.0".
* `server`: A string identifying the server or server family for diagnostic
purposes. As examples, "production", "test". Default: "".
#### `daystart` Objects (Update Check Response)
A clock object contains information about the current datetime according to the
server's locale. It has the following members:
* `elapsed_days`: An integer. The number of complete calendar days that have
elapsed since January 1st, 2007 in the server's locale, at the time the
request was received. The client should generally save this value for use
in future update checks (for examples, see `request.app.ping.rd` and
`request.app.installdate`).
#### `systemrequirements` Objects (Update Check Response)
A `systemrequirements` object contains information about the operating system
that the application requires to install. It has the following members:
* `platform`: The operating system family that the application requires
(e.g. "win", "mac", "linux", "ios", "android"), or "" if not applicable.
* `arch`: Expected host processor architecture that the app is compatible
with, or "" if not applicable.
`arch` can be a single entry, or multiple entries separated with `,`.
Entries prefixed with a `-` (negative entries) indicate non-compatible
hosts. Non-prefixed entries indicate compatible guests.
An application is compatible with the current architecture if:
* `arch` is empty, or
* none of the negative entries within `arch` match the current host
architecture exactly, and there are no non-negative entries, or
* one of the non-negative entries within `arch` matches the current
architecture, or is compatible with the current architecture (i.e., it is
a compatible guest for the current host). The latter is determined by
`::IsWow64GuestMachineSupported()` on Windows.
* If `::IsWow64GuestMachineSupported()` is not available, returns `true`
if `arch` is x86.
Examples:
* `arch` == "x86".
* `arch` == "x64".
* `arch` == "x86,x64,-arm64": installation will fail if the underlying host
is arm64.
* `min_os_version`: The minimum required version of the operating system, or
"" if not applicable.
The `min_os_version` is in the format `major.minor.build.patch` for
Windows. The `major`, `minor` and `build` are the values returned by the
`::GetVersionEx` API. The `patch` is the `UBR` value under the registry
path `HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion`.
The `build` and the `patch` components may be omitted if all that is needed
is a minimum `major.minor` version. For example, `6.0` will match all OS
versions that are at or above that version, regardless of `build` and
`patch` numbers.
#### `app` Objects (Update Check Response)
An app object represents a per-application acknowledgement of the request. If an
application appears in the request, it must have a corresponding acknowledgement
in the response. It has the following members:
* `appid`: The [application ID](#application-ids) identifies the application.
Servers must always transmit this attribute.
* `cohort`: The new cohort value for the application. The client should
update the cohort of this application to the new value. Subject to the same
length and language limitations as `request.app.cohort`. Default: "" (empty
string).
* `cohorthint`: The new cohort hint value for the application. The client
should update the cohorthint of this application to this value. Subject to
the same length and language limitations as `request.app.cohorthint`.
Default: "" (empty string).
* `cohortname`: The new cohort name value for the application. The client
should update the cohortname of this application to this value. Subject to
the same length and language limitations as `request.app.cohortname`.
Default: "" (empty string).
* `data`: A list of `data` objects.
* `updatecheck`: An `updatecheck` object, if one was sent in the request.
* `status`: The state of the product on the server. Default: "ok". Known
values:
* "ok": The application is recognized.
* "restricted": The application is recognized, but due to policy
restrictions (such as export law compliance) the server must refuse to
give a meaningful response.
* "error-unknownApplication": The server is not aware of an application
with this ID.
#### `data` Objects (Update Check Response)
Each data object in the response represents an answer to a data request from the
client. It has the following members:
* `name`: The requested data name from `request.app.data.name`, echoed back
to the client.
* `index`: The requested data index from `request.app.data.index`, echoed
back to the client, if valid.
* `status`: The outcome of the data lookup. Default: "ok". Known values:
* "ok": This tag contains the appropriate data response, even if such a
response is the empty string.
* "error-invalidargs": The data request could not be parsed or
understood.
* "error-nodata": The data request was understood, but the server does
not have a value for the requested entry. (This is distinct from having
a zero-length value.)
* `#text`: The value of the requested data index.
#### `updatecheck` Objects (Update Check Response)
An updatecheck response object contains whether or not there is an update
available for the application, and if so, the instructions to install it. It has
the following members:
* `info`: An optional string that provides a rationale for the status
response, for use in debugging. For example, "update disabled by client"
or "bandwidth limit exceeded". Default: "".
* `status`: Indicates the outcome of the updatecheck. Servers must always
send a value here. Known values:
* "ok": An update is available and should be applied.
* "noupdate": No update is available for this application at this time.
* "error-internal": The server encountered an unspecified internal error.
* "error-hash": The server attempted to serve an update, but could not
provide a valid hash for the download.
* "error-osnotsupported": The server recognized the application, but the
client does not meet the minimum system requirements to receive any
version of the application. In particular, it is running on an
incompatible operating system.
* "error-hwnotsupported": The server recognized the application, but the
client does not meet the minimum system requirements to receive any
version of the application. In particular, it is running on
incompatible hardware.
* "error-unsupportedprotocol": This application is incompatible with this
version of the protocol. (For example, it may require multi-package
support from the Omaha 3 protocol, or may require some feature added in
a later version of this protocol.)
* "error-inexpressible": The server finds that it is unable to produce a
list of pipelines for the given product using the set of operations
provided in `acceptformat`.
* `pipelines`: A list of `pipeline` objects.
#### `pipeline` Objects (Update Check Response)
A pipeline object describes a pipeline process that may be applied in order to
update the current binary. A pipeline is represented as a series of operations.
A pipeline object has the following members:
* `operations`: A list of `operation` objects.
* `nextversion`: The expected version of the product, if this pipeline is
able to complete all operations successfully.
* `nextfp`: A `fingerprint` object representing the package fingerprint
associated with the package file that this pipeline installs.
#### `operation` Objects (Update Check Response)
A operation object describes one of many operations to be performed in order to
produce, process, and eventually install a update.
It has
the following members:
* `type`: The type of operation to execute, represented as a string. This can
be any of the operations provided by `acceptformat` to the
[Request Object](#request-object-update-check-request).
For `type == "download"`: Download a payload.
* `size`: The size in bytes of the payload requested for download.
* `outhash_sha256`: The SHA256 hash of the payload downloaded, encoded as a
lowercase hexadecimal string.
* `urls`: The ordered list of url objects from which this payload may be
obtained. Clients must attempt to download from each URL of the appropriate
type in the specified order, falling back to the next URL if a TCP or HTTP
error is encountered. A 4xx or 5xx HTTP response qualifies as an error that
justifies a fallback. A successful download of a file that fails to hash to
the provided `outhash_sha256` or has an unexpected size also qualifies.
Other network errors may also qualify.
For `type == "decompress_lzma"`: Decompress a file produced by the previous
operation. The file is compressed using
[LZMA](https://en.wikipedia.org/wiki/Lempel%E2%80%93Ziv%E2%80%93Markov_chain_algorithm).
For `type == "zucc"`: Apply a differential Zucchini patch produced by a
previous operation to a cached payload. The patch is generated using
[Zucchini](https://chromium.googlesource.com/chromium/src.git/+/main/components/zucchini/README.md).
* `previousfp`: A `fingerprint` object representing the package fingerprint of
the package that must be used as the input for this patch operation.
For `type == "puff"`: Apply a differential Puffin patch produced by a previous
operation to a payload stored in the cache. The patch is generated using
[Puffin](https://chromium.googlesource.com/chromium/src.git/+/main/third_party/puffin/README.md).
* `previousfp`: A `fingerprint` object representing the package fingerprint of
the package that must be used as the input for this patch operation.
For `type == "crx3"`: Decompress a CRX3 package produced by the previous
operation and install it.
* `inhash_sha256`: The SHA256 hash of the payload produced by the previous
operation, encoded as a lowercase hexadecimal string.
* `path`: The path to a payload or directory, relative to the root of the CRX
archive. This may be left blank in cases where execution after install is
not necessary.
* `arguments`: A string indicating command-line arguments that should be
passed to the identified binary to execute.
For `type == "run"`: Execute a binary located at a given path.
* `path`: The path to the executable relative to the install directory
(or in an update with the associated `nextfp`, provided by the parent object
`pipeline`, if this response does not contain an update for this
application) given as a string.
* `arguments`: The command line arguments to be passed to the executable,
formatted as a single string.
#### `url` Objects (Update Check Response)
A url object describes a fully-qualified URL. It has the following members:
* `url`: The fully-qualified URL as a string.
---
## Downloads
Download requests occur when an application update is needed, as a result of a
`response.app.updatecheck.pipelines.operations.urls` member. Download requests
are HTTP GET requests and can use any HTTP implementation.
### Request Headers
In addition to the regular HTTP headers, this protocol defines the following
headers for the download request:
* `X-Goog-Update-SessionId`: The [session ID](#session-ids) of the update
session.
---
## Ping-Backs
Ping-back requests are caused by any operation attempted during an update
session. Ping-backs share a similar structure to update check requests.
Ping-back requests are fire-and-forget: the client can discard the server's
response. Ping-back transactions need to be protected by CUP if and only if the
client handles the server's response.
Ping-back requests can be **bundled** into a single HTTP transaction, or sent
immediately as the events triggering the ping-back occurs. Bundling ping-backs
reduces QPS to the server, but risks ping-back loss if the client crashes,
loses connectivity, or loses power before it transmits the bundle.
### Ping-Back Request Headers
Similarly to update-check requests, ping-back requests have additional headers
for the purpose of easier DoS rejection.
* `X-Goog-Update-AppId`: A comma-separated list of application IDs included
in this request.
* `X-Goog-Update-Updater`: "name-version", where "name" is the name of the
updater as reported in `request.updater` and "version" is the version of
the updater as reported in `request.updaterversion`.
### Ping-Back Request Body
The request body of an ping-back contains a JSON object with the following
members:
* `request`: A `request` object.
#### `request` Objects (Ping-Back Request)
A ping-back `request` object contains all the same members as a update check
`request` object. Differences occur in the `request.app` objects.
#### `app` Objects (Ping-Back Request)
A ping-back `app` object is identical to an update check `app` object, except
for the following differences.
A ping-back `app` object cannot contain any of the following members:
* `data`
* `ping`
* `updatecheck`
A ping-back `app` additionally contains the following members:
* `event`: a list of `event` objects.
#### `event` Objects (Ping-Back Request)
An event object represents a specific report about an operation the client
attmpted as part of this update session. All events have the following members:
* `eventtype`: The event type is a numeric value indicating the type of the
event. It must always be specified by the client. The following values are
known:
* 2: An install session.
* 3: An update session.
* 4: An uninstall session.
* 14: A download operation.
* 60: A decompress_lzma operation.
* 61: A zucchini patch application operation.
* 62: A puffin patch application operation.
* 63: A crx3 package installation operation.
* 41: An app command completion event.
* 42: A run operation.
* `eventresult`: The outcome of the operation. Default: 0. Known values:
* 0: error
* 1: success
* 4: cancelled
* `errorcat`: An error category, for use in distinguishing between different
classes of error codes. Default: 0. The following values are known:
* 0: No category.
* 1: Errors acquiring the download.
* 2: Errors during CRX unpacking.
* 3: Update client errors during installation.
* 4: Errors within the update service itself.
* 5: Error during update check.
* 6: Reserved.
* 7: Application installer errors during installation.
* 8: Errors encountered during patch application.
* `errorcode`: The error code (if any) of the operation. Default: 0. The
meaning of an error code may depend on the error category. 0 always means
"no error" (success).
* Additional values may exist in
(update_client_errors.h)[https://cs.chromium.org/chromium/src/components/update_client/update_client_errors.h]
* `extracode1`: Additional numeric information about the operation's result.
The meaning of an extra code depends on the error category and error code.
Default: 0.
Depending on the event type, additional members may be present:
For `eventtype == 2` events:
* `nextfp`: A `fingerprint` object representing the
[package fingerprint](#differential-updates) that the client was attempting
to update to, regardless of whether that update was successful.
* `nextversion`: The application version that the client was attempting to
update to, regardless of whether the update was successful.
For `eventtype == 3` events:
* All the members of `eventtype == 2` events.
* `previousfp`: A `fingerprint` object representing the
[package fingerprint](#differential-updates) of the application, prior to
the update, regardless of whether that update was successful.
* `previousversion`: The application version the client had prior to the
update, regardless of whether that update was successful.
For `eventtype == 14` events:
* `download_time_ms`: The time elapsed between the start of the download and
the end of the download, in milliseconds. -1 if unavailable.
Default: -1.
* `downloaded_bytes`: The number of bytes successfully received from the
download server. Default: 0.
* `downloader`: A string identifying the download algorithm / stack. Known
values:
* "" (empty string): Unknown downloader.
* "nsurlsession_background": MacOS background NSURLSession.
* "bits": Microsoft BITS.
* "direct": The Chromium network stack.
* `expected_bytes`: The number of bytes expected to be downloaded. Default:
0.
* `url`: The URL from which the download was attempted.
For `eventtype == 60` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 61` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 62` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 63` events:
* All the members of `eventtype == 3` events, including those inherited from
`eventtype == 2` events.
For `eventtype == 41` events:
* `appcommandid`: The id of the app command for which the ping is being sent.
For `eventtype == 42` events:
* `actiontype`: The type of the action that caused this event.
### Ping-Back Response Body
Clients are free to ignore the ping-back response body. However, to allow future
extensions in the ping-back response, the protocol defines a basic ping-back
response body. Clients that do not ignore the ping-back response must protect
the ping request using CUP.
The response body of an ping-back contains a JSON object with the following
members:
* `response`: A `response` object.
#### `response` Objects (Ping-Back Response)
A ping-back `response` object contains all the same members as a update check
`response` object. Differences occur in the `response.app` objects.
#### `app` Objects (Ping-Back Response)
A ping-back response `app` object is identical to an update check response `app`
object, except for the following differences.
A ping-back `app` object cannot contain any of the following members:
* `data`
* `updatecheck`
A ping-back `app` additionally contains the following members:
* `event`: a list of `event` objects.
#### `event` Objects (Ping-Back Response)
A ping-back response `event` object indicates the server's acknowledgement of
the event. It has the following members:
* `status`: Indicates the result of parsing the action on the server side.
Known values:
* "ok": The server acknowledges successful receipt of this event ping.
Codebase Browser
chromium