How google/omaha works
Omaha is a Windows software update platform, not a typical app. Its architecture is centered on installing products, checking for updates, downloading packages, and coordinating silent/background execution through Windows services, COM, scheduled tasks, and installer technology.
1. Top-level shape
The repo is split into a few major execution products:
- goopdate: the main update client/runtime and COM server
- core: launcher and scheduler logic
- service: Windows service entrypoint
- setup and installers: bootstrapper/installer generation
- enterprise: MSI, Group Policy, and managed-install support
- crashhandler: crash capture/reporting
- standalone: standalone installer generation
Supporting code lives in base, common, net, ui, statsreport, and testing.
2. Primary runtime boundary: goopdate
omaha/goopdate contains the bulk of the runtime state machine. It manages app bundles, app state transitions, update requests/responses, package caching, installer orchestration, command-line parsing, and COM-facing APIs. If you are drawing the core architecture, this is the main “brains” box that coordinates everything else.
3. Update workflow
The update flow is:
- product/app metadata is read from the registry and local config
- update_request/update_response types serialize and parse protocol traffic
- net sends requests over HTTP/WinHTTP, sometimes through BITS
- server responses describe available updates and download URLs
- download_manager and package_cache fetch and stage packages
- install_manager/installer_wrapper launch installers and track results
- ping/metrics code records outcomes back to the service
4. Protocol and server boundary
Omaha speaks multiple update protocols, documented in doc/ServerProtocol*.md and doc/ClientUpdateProtocol*.md. The boundary to the update service is intentionally explicit: request/response XML definitions in omaha/common, helper code in goopdate, and ECDSA/CUP support in omaha/net. This is where external servers, manifests, signatures, and anti-tamper checks enter the system.
5. Client-side install and bootstrap
omaha/client handles the “install Omaha itself” and “install apps through Omaha” paths. It includes self-install logic, bundle creation, update/install progress observation, and user-agent or environment-specific behavior. This is distinct from the updater runtime: it is the bootstrap/installer path that gets Omaha onto the machine or updates it.
6. Setup, bootstrapper, and package creation
omaha/setup, omaha/installers, omaha/standalone, and omaha/enterprise/installer generate the distributable artifacts:
- MSIs, EXEs, and metainstallers
- tagged installers and resource scripts
- standalone installers for specific apps
- enterprise installers with MSI custom actions
These components are build-time and install-time, not runtime update logic, but they define how products enter the update ecosystem.
7. Windows integration layer
Omaha is deeply Windows-specific. Important integration points include:
- COM servers and IDL/proxy stubs in goopdate
- Windows service entrypoints in service and core
- scheduled tasks in common/scheduled_task_utils
- registry access and monitoring in base
- WinHTTP and BITS in net
- ETW/event logging, shell/process utilities, and user/session handling in base
This means the architecture is heavily split by OS boundary rather than by network/web tiers.
8. Networking subsystem
omaha/net abstracts transport concerns: HTTP client code, WinHTTP adapters, BITS requests/jobs, proxy auth, network detection, and request wrappers. It also contains CUP/ECDSA request support and related metrics. This layer is the network edge between Omaha and update servers and hides transport selection and Windows API details from higher-level update logic.
9. Shared domain logic
omaha/common holds cross-cutting update-domain code: app registry utilities, command-line handling, config, ping and telemetry models, XML parsing, protocol definitions, policy/group-policy helpers, and signature validation. This is the shared contract layer used by setup, goopdate, enterprise, and networking code.
10. Core OS and utility library
omaha/base is a large platform foundation layer: files, paths, registry, processes, threading, timers, environment, security primitives, ETW, WMI, extraction, signature validation, and general Windows wrappers. Architecturally, it is the lowest reusable layer under the Omaha-specific subsystems.
11. UI and user interaction
omaha/ui provides dialogs and progress windows for interactive update/install flows. Most background updates are silent, but UI is used for consent, progress, and error presentation when user interaction is required. This is a boundary between unattended service behavior and foreground user experience.
12. Crash handling and diagnostics
omaha/crashhandler is a separate executable/service-style component that analyzes dumps, processes crash events, and records crash metrics. The repo also includes Breakpad-related pieces and tools for crash reproduction/handling. This subsystem is isolated because crash collection must survive or outlive the crashing process.
13. Telemetry, metrics, and reporting
statsreport and the various *_metrics.cc files collect local telemetry such as update progress, installer outcomes, and crash statistics. This data typically flows from runtime components to event logs or upload mechanisms, and is separate from the update protocol itself.
14. Enterprise and policy management
omaha/enterprise adds administrative control: ADMX/ADML/ADM templates, MSI custom actions, and installer support for managed deployments. This is the policy boundary where machine-level settings, OEM behavior, and enterprise constraints alter how updates are checked, installed, or suppressed.
15. Testing, fixtures, and build
The repo is test-heavy, with many *_unittest.cc files and a dedicated omaha/testing fixture corpus containing signed binaries, manifests, certs, cached downloads, and minidumps. Build orchestration is primarily SCons (build.scons, main.scons) with Python helpers and some WiX/MSI tooling. The fixtures are architecturally important because the system depends on exact signatures, packaging formats, and installer behaviors.
16. Key data flow to diagram
A good architecture diagram should show: installer/bootstrapper creates/launches Omaha; Omaha stores state in registry/files and schedules background work; the updater runtime builds requests from app metadata and policy; the network layer talks to update servers; download/package logic stages artifacts; installer logic executes app updates; metrics/pings and crash data flow back to logging/reporting paths; enterprise policy and Windows service/COM boundaries modulate the whole path.
Main entry points: goopdate Goopdate · update_request_utils.cc Protocol I/O · common Common · setup Setup
Components 20
Runtime
Updater execution and state management
- Goopdate · Main updater brain: COM server, app orchestration, state machine, request/response handling, downloads, and installs
omaha/goopdate - App state · App bundle and app lifecycle states from init through check, download, install, and stop
omaha/goopdate/app_state.cc - Protocol I/O · Builds update requests, parses responses, and drives web-service interactions
omaha/goopdate/update_request_utils.cc - Downloads · Download manager, package objects, cache, and staging for update payloads
omaha/goopdate/download_manager.cc - Installs · Launches installers, wraps results, and coordinates install completion
omaha/goopdate/install_manager.cc - Core · Launcher, scheduler, and system monitoring for background execution
omaha/core - Service · Windows service entrypoint for background update execution
omaha/service
Install/Bootstrap
Paths that create, package, or install Omaha and apps
- Client · Installs Omaha itself and app bundles; foreground install paths and progress observation
omaha/client - Setup · Installer/bootstrap logic for setting up Omaha and its service
omaha/setup - Installers · Metainstaller and tagged installer generation
omaha/installers - Standalone · Standalone app installer generation and manifests
omaha/standalone - Enterprise · Managed deployment templates, MSI custom actions, and enterprise installer generation
omaha/enterprise
Platform
Shared Windows and domain infrastructure
- Common · Shared update-domain models, protocol definitions, pings, policy helpers, XML, and scheduled tasks
omaha/common - Base · Lowest reusable Windows utility layer: files, registry, threading, processes, security, ETW, and system wrappers
omaha/base - Net · HTTP/WinHTTP/BITS transport, network detection, proxy auth, and CUP/ECDSA request support
omaha/net - UI · Dialogs and progress windows for interactive installs and consent/error presentation
omaha/ui
Diagnostics
Crash and telemetry reporting
- Statsreport · Metrics aggregation, formatting, and persistent reporting helpers
omaha/statsreport - Crashhandler · Crash dump analysis, worker, and crash metrics subsystem
omaha/crashhandler
Connections 23
- Setup → Service: installs/starts · Bootstrapper lays down the service and runtime pieces
- Installers → Setup: packages · Metainstallers are assembled for deployment
- Standalone → Setup: packages · Standalone app installers feed the install path
- Enterprise → Installers: extends · Enterprise deployment artifacts build on installer generation
- Client → Goopdate: boots · Client-side install path hands off to the updater runtime
- Service → Core: hosts · Windows service hosts the background scheduler/core
- Core → Goopdate: launches · Core schedules and launches update work
- Goopdate → Common: uses · Runtime depends on shared domain models and protocol helpers
- Goopdate → Base: uses · Updater runtime relies on Windows foundation utilities
- Goopdate → Net: requests · Builds protocol traffic and sends it through transport layer
- Goopdate → UI: shows · Foreground update/install flows surface dialogs and progress UI
- Goopdate → Statsreport: reports · Runtime emits local metrics and telemetry
- Goopdate → Crashhandler: reports · Crashes and dumps are handed to crash handling paths
- Goopdate → App state: coordinates · Main runtime drives the bundle and app state machine
- App state → Protocol I/O: requests · State transitions trigger update check and protocol I/O
- Protocol I/O → Net: sends via · Protocol layer delegates transport to networking subsystem
- Protocol I/O → Downloads: describes · Responses provide URLs and package metadata for downloads
- Downloads → Installs: hands off · Fetched packages are staged for installer execution
- Installs → Client: serves · Installer orchestration supports app and Omaha install flows
- Common → Base: built on · Shared domain code uses the Windows foundation layer
- Common → Net: feeds · Protocol definitions and request models drive network traffic
- Tools → Testing: uses · Developer tools and fixtures are validated through tests
- Testing → Goopdate: exercises · Test harness targets the updater runtime and related components