omaha‎ > ‎

omaha3walkthrough

https://code.google.com/p/omaha/wiki/Omaha3Walkthrough
を適当に翻訳中

注意: TOEIC400点とかの人が紅白を見ながら訳したものなので、あまり信用しないように…

Common Terminology

  • “User/Machine Omaha” - Omaha can be installed in two different ways on a system, and may even have multiple installed copies on a single system simultaneously:
    • User Omaha: Omaha is installed for a single user. The files live in the user’s local application data directory (for example,\Users\%user%\AppData\Local\Google\Update on Win7), and all relevant Registry keys are stored in HKCU\Software\Google. Omaha installs are initiated by a user; subsequent automatic updates are run under that user’s account.
    • Machine Omaha: Omaha is installed in a machine-wide manner. The files live in the machine’s app directory -- for example, \Program Files (x86)\Google\Update -- and all relevant Registry keys are stored in HKLM\Software\Google\Update (for 32-bit) orHKLM\Software\Wow6432Node\Google\Update (for 64-bit). Omaha installs are still typically initiated by a user account, but the automatic updates themselves will run under LocalSystem.
  • “Goopdate” - The core DLL in which nearly all Omaha code lives.
  • “Constant Shell” - The executable commonly known as GoogleUpdate.exe. This is a small, statically linked EXE with no load-time DLL dependencies (not even a CRT!). It attempts to find a copy of goopdate.dll -- the local directory first, if one exists there, otherwise the Omaha install location in the registry. It may verify that the DLL has an intact Authenticode signature from Google, and then loads the DLL and runs its Main() function, passing along any command line switches it received.
  • “Meta-installer” (often abbreviated to MI) - The executable known as GoogleUpdateSetup.exe. A metainstaller is an EXE with a large binary resource containing a compressed TAR archive of all the files needed for an Omaha install. The MI’s code decompresses and extracts the tarball’s contents to a temporary directory, and runs the constant shell inside that directory, passing any command line along. The MI is almost always Authenticode signed.
  • “Tagged Meta-installer” - A copy of the MI that has been configured to pass a predefined command line to Omaha - for example,ChromeSetup.exe. A “tag” refers to a predefined command line. We stow the tag string in an PE section that is not covered by the Authenticode signature; in this way, a meta-installer EXE can be modified to download and install nearly any app that Google offers by simply adding the tag, without having to re-sign it.
  • “CUP” - A proprietary Google protocol, built on top of HTTP. It provides SSL-like authentication/repudiation while avoiding some of the downsides of HTTPS. Acronym for “Client Update Protocol.” CUP is described in more detail in a separate design document.
  • “Code Red” - Describes a situation where a bugged Omaha build or an OS patch has been released that prevents Omaha from updating for a very large percentage of users, and the tools for resolving it. Google-authored applications can link with a static library produced during the Omaha build that checks for Code Red releases through an alternate channel; if a Code Red release is enabled, an executable is downloaded which attempts to repair/reinstall Omaha.

  • ユーザ/マシン omaha - Omahaはシステムに2つの別の方法でインストールできる。そして1つのシステムに同時に複数のコピーがインストールされるかもしれない。
    • User Omaha: omahaは1人のユーザーのためにインストールされる. ファイルはユーザーのローカルアプリケーションデータディレクトリ(例えば,\Users\%user%\AppData\Local\Google\Update on Win7)に存在し、全ての適切なレジストリキーが HKCU\Software\Google に保存される. omahaのインストールは初回はユーザによってされ、その後ユーザーのアカウントで自動的にアップデートされる.
    • Machine Omaha: omahaはマシーン全体の方法によってインストールされます. ファイルはマシンのAppディレクトリに存在します - 例えば\Program Files (x86)\Google\Update. そして全ての適切なレジストリキーが HKLM\Software\Google\Update (for 32-bit) かHKLM\Software\Wow6432Node\Google\Update (for 64-bit) に保存されます. omahaは初回はユーザーによってインストールされますが、それらの自動アップデートはLocal Systemの元で実行されます.
  • Goopdate - コアDLLでomahaの全てのコードが入っているに近いもの.
  • Constant Shell - GoogleUpdate.exeとして一般に知られている実行ファイル. これは小さく、静的にリンクされたexeで実行時にDLLへの依存がない(CRTでさえも!) それは最初にgoopdate.dllを見つけようとする -- ローカルディレクトリを最初に調べ、存在しなかったらomahaインストールディレクトリを調べます. Googleからの完全な認証コードシグネチャを持っているかどうかDLLを調べるかもしれない, それからDLLをロードしてMain関数を走らせ、受け取った全てのコマンドラインスイッチを引き渡す.
  • Meta-installer - GoogleUpdateSetup.exeとして知られている実行ファイル. メタインストーラはomahaのインストールのために必要な全てのファイルの圧縮tarアーカイブを含んだ大きなバイナリリソースを持ったexeです. メタインストーラのコード解凍とtarのコンテンツのテンポラリディレクトリへの展開、そしてディレクトリ内でのシェルの実行、全てのコマンドラインの引き渡し. メタインストーラはほとんどいつも認証コードでサインインしている状態です.
  • Tagged Meta-installer - omahaのための事前に定義されたコマンドラインを引き渡すことで構成されるメタインストーラのコピーです - 例えば, ChromeSetup.exeです.タグは、事前に定義されたコマンドラインを参照します. 我々はタグ文字列を、認証コードシグネチャによって覆われていないPEセクションに詰め込んでいます。この方法では、メタインストーラのexeは、ほとんどすべてのGoogle提供のアプリについて、単にタグを追加することによって、再度サインインすることなく、ダウンロードやインストールの変更が可能です.
  • CUP - 独占的なGoogleプロトコルで, HTTP状に構成されます. それはHTTPSのマイナス面を避け、SSLのような認証/否認を提供します. Client Update Protocolの接頭語です. CUPは別のデザインドキュメントにより詳細に述べられています.
  • Code Red - はomahaビルドの場所を盗聴したり, 非常に広いパーセンテージのユーザを更新するomahaを防止するパッチがリリースされたことや、それを解決するためのツールについて述べます。Google認証されたアプリケーションは、omahaをビルドされている間生成される静的ライブラリへリンクし、CodeRedのリリースのために別のチャンネルを通じてチェックすることが可能です。もしCodeRedリリースが有効なら、exeがomahaを修復/再インストールするためにダウンロードされます.
Core Design Breakout

A working Omaha install on Windows consists of three fundamental components:

(------------ user machine ------------)              |    (---- operated by google ----)
[Omaha Client] <--COM RPC--> [Update3 COM Server] <--network--> [Omaha Update Server]

The Omaha Update Server implementation is outside of this document's scope. For the purposes of this doc, you should know that it is an HTTP(S) server, written in Java and running on Google servers, which accepts a HTTP(S) POST request with an XML-formatted body and responds with XML-formatted data. (It can also use the CUP protocol.)

(Note: In addition to Omaha v3 requests, the Update Server also handles requests from Omaha v1 and v2, which used different XML schemas, as well as requests from non-Omaha entities such as Macintosh clients.)

The Omaha COM Server operates on a customer’s machine, at whatever privilege level that the install requires - LocalSystem for machine-wide installs, or the user account for per-user installs. It maintains a state machine for all applications it currently tracks (exposed as a COM object) and worker threads that will advance the state machine automatically in response to certain function calls. It handles all network access and launches all installers, impersonating the client where necessary; as a general rule, it has no UI. It is the heart of Omaha.

(Note: There are actually multiple COM servers supported by Goopdate, which will expose different objects based on the command line used to start them. However, the above, which is known as the Update3 server, is the only one you should generally care about.)

The Omaha Client always operates at user privilege levels and owns the UI of Omaha. It has two duties:

  • Setup - Create or update a permanent Omaha install, of either user or machine variety.
  • Install - Invoke the COM server to create a state machine object, fill it out with apps to be managed, and call a suitable function on it such ascheckForUpdate(), download(), or install(). From that point onwards, poll the state object as the COM server does the work for you, and update the UI as the states advance.

In general, when referring to “the client”, we’re referring to the official Google Update client, which happens to live in the same executable as the COM Server; the role that the executable plays is decided simply by which command line is passed to it. However, there are other clients that may access the COM server; some of them we own (the web browser plugins), and some we do not own (partner applications which access our COM APIs directly). The server must stay as secure as possible, and sanitize all input.


WindowsでのOmahaインストールの動作は3つのコンポーネントからなります

omahaアップデートサーバーの実装は、このドキュメントのスコープ外です. このドキュメントの目的のために、あなたはJavaで書かれて走っている、GoogleのHTTP(S)サーバーについて知るべきです。それはHTTP(S) PostリクエストをXML-formatted bodyと共にリクエストをし、XML-formatted dataの返信をします。(また、CUPプロトコルを使用することもできます)

(注:加えて、Omaha v3 リクエストでは、アップデートサーバーはまたOmahav1/v2からのリクエストも扱います。Macのようなomahaではないエンティティからのリクエストと同様に、異なるXMLスキーマを使用していています。)

Omaha COMサーバーは、何の権限レベルがインストールでマシン全体のインストールや各ユーザごとのユーザアカウントでのインストールのためのLocalSystemを要求しても、カスタマーのマシンで動きます。それは現在追跡している(COMオブジェクトとして露出している)すべてのアプリケーションとのためのステートマシンを維持し、確かな関数コールのための返信に自動的にステートマシンを進める。それはすべてのネットワークアクセスを扱い、すべてのインストーラを起動し、必要におおじてクライアントを装います;一般的なルールとして、UIを
持っていないです。omahaの心臓部です。

(注: 実際にGoopdateによってサポートされる複数のCOMサーバーがある。それらはそれらをスタートさせるためのコマンドラインベースの複数のオブジェクトを晒す。しかし、そうはいっても、Update3サーバーとして知られていて、ただあなたは一般的に大切にするだけでよい)

Omahaクライアントはいつもユーザー権限レベルで実行し、omahaのUIを所有します。それは2つの責務を持ちます:
  • Setup - ユーザやマシンに依存しない、永続的なOmahaインストールの作成や更新
  • Install - ステートマシンオブジェクトを作るためにCOMサーバーを呼び出し、管理し、ascheckForUpdate(), download(), or install() のような適切な関数を呼ぶ。以降その時点から、COMサーバーがあなたのために働くようにするためステートオブジェクトをポーリングし、進んだステートによってUIを更新する。
一般的に、クライアントを参照するとき、我々はCOMサーバとしての同じ実行ファイルに存在する公式のGoogleUpdateクライアントを参照する。
(略)

Example Code Flow

Let’s walk through an example - the user downloads a Chrome installer from a machine that has no version of Omaha at all. What actually happens:

  • The Chrome installer EXE (~500KB) is actually a tagged meta-installer. It decompresses the Omaha files to a temporary directory and invokes the constant shell with the following command line. The part after the /install is the tag string:
  • GoogleUpdate /install "bundlename=Google%20Chrome%20Bundle&appguid={8A69D345-D564-463C-AFF1-A69D9E530F96}&
    appname=Google%20Chrome&needsadmin=False&lang=en"
  • The constant shell loads goopdate.dll from the temporary directory and passes along this command line; we start by parsing it. The/install flag tells us that we’re operating as the Client, and we need to install Omaha; we examine and sanitize the tag (known from here on as extra-args) to figure out whether we need a user or machine Omaha. We decide from “needsadmin=false” that a user Omaha install is warranted. (If needsadmin were equal to true, we would attempt to re-launch ourselves in a new, elevated process.)
  • We check the machine to see if there’s already a user Omaha installed with a version newer than or equal to ours. (If it’s equal to ours, we will do some supplementary checking to make sure that the installed copy is sane and working properly, and if not, we over-install.) Let’s assume that there is no user Omaha installed. We will create the direct directory in AppData, copy over the files, and then make entries in the Registry to do the following:
    • Register our COM servers
    • Create scheduled tasks to check for an update every five hours
    • Expose our web browser plugins to IE/Firefox/Chrome/Safari/Opera
    • Store initial configuration/state for Omaha itself in the Registry
    • Register Omaha itself as an Omaha-managed application, so it can check for updates for itself
  • The client then starts a new copy of itself in its permanent installed location, modifying the command line from /install to /handoff. Once again, the constant shell loads Goopdate and passes the command line along - this time, however, we’re using the constant shell in the newly-created permanent install of Omaha, rather than the one in the temp directory.
  • This time, the command line is /handoff - we decide that we’re a Client again, but now we assume that we’re running from a permanently installed copy, and are being asked to to download and install an app from the network. The Client uses COM to create a copy of an Update3 object called the AppBundle, which is implemented on the our COM server. Windows will start the COM server (which is done by running the constant shell, again - but this time, with a different command line, triggering Server mode) and returns to the client a AppBundle* - which is actually a COM RPC proxy for an AppBundle in the COM server process.
  • The client adds the supplied GUID from the tag to the AppBundle, and asks the COM server to check for an update. The COM server spins up a worker thread which will manipulate the app bundle; it checks the machine for an existing install of that app (let’s assume it finds none), then formats an XML request and sends it securely to the Update Server over the network.
  • The Google-managed server will respond with an XML response that contains a URL to download the Chrome installer, its size, and hash. The COM server parses this, stores the info in the App Bundle, then shifts its state into “Ready to Download”. The client, which has been polling it and watching the status, calls download() on the bundle - which triggers the worker thread to start downloading it. Using a similar handoff of polling and invoking methods, the client will order the server to cache the downloaded installer, verify its integrity, and start the installer.
  • The Chrome installer, which is managed by the Chrome team, installs Chrome. As part of its install, it writes data to Omaha’s area of the Registry, registering itself as being managed by Omaha.
  • Finally, the Chrome installer process exits. The COM Server sends a ping (an XML request formatted with the success/failure of the Chrome installer, as denoted by the EXE’s exit code, plus supplemental info about download duration and the like) to the Update Server. The COM client releases the AppBundle and exits.
  • The COM Server no longer has any active clients, and will shut down on its own in a minute or two.
  • Five hours later, a scheduled task fires that starts up the constant shell with the commandline /ua. This triggers a Client who reads the registry to get a full list of all applications currently being managed by Omaha. It creates an App Bundle (starting the COM Server) and adds all the apps to it; the COM Server checks for updates, and the whole process starts again.

A crucial thing to pick up here is that, since one file (goopdate.dll) does many different tasks based simply on the command line, a typical Omaha task will involve many processes being created. A typical clean install of Machine Chrome may involve as many as 15 different instances of GoogleUpdate.exe being started, each doing small parts of the task.


例を通じてみてみましょう - ユーザーがomahaが全く入っていないマシンからChromeインストーラをダウンロードします。すると次のようなことが実際に起きます

  • Chromeインストーラのexe(500KBくらい) は実際タグ付けされたメタインストーラです。それはOmahaファイルをテンポラリディレクトリに解凍し、次のコマンドラインでコンスタントシェルを処理します。/installより後の部分はタグの文字列です
    GoogleUpdate /install "bundlename=Google%20Chrome%20Bundle&appguid={8A69D345-D564-463C-AFF1-A69D9E530F96}&
    appname=Google%20Chrome&needsadmin=False&lang=en"
  • コンスタントシェルはgoopdate.dllをテンポラリディレクトリから読み込み、このコマンドラインを伝達します;我々はそれをパースすることによって開始します。
    /install フラグは、我々に、我々がクライアントとして実行し、我々がomahaをインストールする必要があることを伝えます; 我々はここで、1人のユーザか、マシン全体のインストールのどちらを必要としているか見つけ出すために、
    余分な引数として与えられているものに検査やサニタイズを行います。”needsadmin=false"により、我々は1人のユーザへのインストールが保証されているということを、決定します。(もしneedsadminがtrueなら我々は自身のプロセスを権限のあるプロセスとして新規に再起動させます。)
  • 我々は既に我々のインストールしようとしているomahaと同じかそれ以上先のバージョンのユーザーomahaがインストールされていないかチェックします。(もしバージョンが等しいなら、我々はインストールされているコピーが確かなワーキングプロパティかどうか確かめるためにいくつかの補足的なチェックを行います。もし違っていれば、上書きインストールします。) ユーザーomahaが全くインストールされていないことを想定してみましょう。我々はAppDataに直接ディレクトリを作成し、ファイルを上書きコピーし、それから次のことをするためレジストリにエントリを登録します。
    • 我々のCOMサーバーの登録
    • 5時間ごとにアップデートをチェックするためのスケジュールタスクの作成
    • IE/Firefox/Chrome/Safari/Operaへ我々のウェブブラウザプラグインを晒す
    • omaha自身の最初の構成/状態をレジストリへ登録する
    • omaha自身をomaha管理アプリケーションとして登録し、自身のアップデートをチェックすることができる
  • クライアントはそれからその永続的なインストール場所に置いた自身の新しいコピーを開始し、コマンドラインを/install から /handoffに変更する。もう一度コンスタントシェルはGoopdateを読み込み、コマンドラインを引き渡す - しかしながら、この時、我々は、テンポラリディレクトリにあるものではなく、新しく作成された永続的なomahaのインスト―ルにある、コンスタントシェルを使う。
  • この時、コマンドラインは /handoffである - 我々は再びクライアント権限であることを決定します、しかし我々は永続的にインストールされたコピーから起動していて、ネットワークからアプリをダウンロードしたりインストールしたりするために訊ねられています。クライアントはAppBundleと呼ばれるUpdate3オブジェクトのコピーを作るためにCOMを使用する。AppBundleは我々のCOMサーバーに実装されている。WindowsはCOMサーバーを開始する。(COMサーバーはコンスタントシェルから実行されるが、再び、このタイミングで、サーバーモードを有効にした別のコマンドラインで実行される。) そしてクライアントにAppBundle* (COMサーバープロセスのAppBundleのためのCOM RPC proxy)を返す。
  • クライアントは tagをもとにAppBundleへ与えられたGUIDを追加する。それからCOMサーバーにアップデートのチェックを問い合わせる。COMサーバーはワーカースレッドを回し、app bundleを操作する。それはマシンにインストールされたアプリケーションをチェックし、XMLリクエストを整形し、ネットワークを通じて安全にUpdateサーバーに送ります。
  • Google管理のサーバーは、ChromeインストーラダウンロードするためのURLと、そのサイズ、およびそのハッシュをを含んだXMLを返信します。COMサーバーはこれをパースし、App Bundleに情報を保存し、それから“Ready to Download”という状態に繊維します。クライアントはそれをポーリングし、ステータスを監視し、ワーカースレッドがダウンロード開始するトリガーである、Bundleのdownload()を呼びます。ポーリングと関数の処理の似たようなhandoffを使用することで、クライアントはサーバーにインストーラのダウンロードをキャッシュさせることを要求し、徐々にダウンロードし、インストーラを開始します。
  • Chromeインストーラーは、Chromeチームによって管理されており、Chromeをインストールします。そのインストールでは、レジストリのomahaのエリアにデータを書き込み、自身をomahaによって管理されるように登録します。
  • 最後にChromeインストーラのプロセスは終了します。COMサーバーはping (Chromeインストーラが成功したか失敗したかをexeの終了コードで判断したものと、ダウンロード中かどうかなどの追加情報を、XML整形したリクエスト) をアップデートサーバーに送ります。COMサーバーはAppBundleを解放して終了します。
  • COMサーバーは、もはやアクティブなクライアントを何も持っておらず、1, 2分で自身を終了させます。
  • 5時間後に、スケジュールタスクによって、コマンドラインのコンスタントシェルが開始されます。これはomahaによって管理されている現在のアプリケーションの全てのリストを取得するためにレジストリを読むべく、クライアントを起動します。それはAppBundleを作成し(COMサーバーの起動), それから全てのアプリをそれに追加します。COMサーバーはアップデートのチェックおよび全体のプロセスの再起動を行います。
ここに非常に重要なことをピックアップしますが、1つのファイル(goopdate.dll)から、コマンドラインベースで多くの異なるタスクを行います。典型的なomahaのタスクは生成された多くのプロセスを処理することです。マシン全体のchromeのクリーンインストールは、小さなタスクにより行われ、15くらいの異なるGoogleUpdate.exeインスタンスによって行われるかもしれません。

The Omaha Files

So, what files are actually in a permanent install of Omaha once it’s completed?

GoogleUpdate.exeThe Constant Shell. Just takes the command line given to it and passes it to goopdate.dll; if necessary, it will validate that goopdate has an intact digital signature from Google.
GoogleCrashHandler.exeA copy of the constant shell, renamed for Omaha2 compatibility reasons. Expected to always be started with /crashhandler.
GoogleUpdateBroker.exe
GoogleUpdateOnDemand.exe
COM Forwarders. Both of these are small EXEs whose sole purpose is to take their own command line, append a command line switch to the end, and pass it to the Constant Shell.
goopdate.dllThe central Omaha3 binary.
goopdateres_*.dllResource-only DLLs, one per language, containing localized strings. As part of its startup, Goopdate will read the “lang” extra-args parameter if one exists (or the Registry) and select a language to load.
npGoogleUpdate3.dllOur web browser plugin. (It actually contains two plugins: ActiveX plugins for IE, and an NPAPI plugin for Firefox, Chrome, and other browsers that use that.) Allows Javascript on selected subdomains of google.com to access and use the COM Server.
psmachine.dll
psuser.dll
Custom marshaling stubs used by the COM Server. Used in order to work around some Windows bugs that are triggered by having both Machine and User Omaha installed simultaneously.


では、Omahaの永続的なインストールを一度完了すると実際何のファイルがインストールされているか?
GoogleUpdate.exeコンスタントシェル。ただコマンドラインを受け取って、それをgoopdate.dllに引きwタスだけのもの。必要な場合は、goopdateがGoogleからの正しい電子証明を持っているか確認する。
GoogleCrashHandler.exeコンスタントシェルのコピーで、Omaha2の互換性のためにリネームされたもの。常に/crashhandlerで開始されることが望まれる。
GoogleUpdateBroker.exe
GoogleUpdateOnDemand.exe
COM 関係。どちらも小さなexeで、これらの目的は独自のコマンドラインを実行することです。最後にコマンドラインスイッチを追加し、それをコンスタントシェルへ引き渡します。
goopdate.dllomaha3バイナリの中心。
goopdateres_*.dllリソースだけのDLL。言語ごとに1つあり、ローカライズ文字列を含んでいます。スタートアップの部分で、Goopdateは追加パラメータの"lang"かレジストリを読み取り、もし存在すれば読み込む言語を選択します。
npGoogleUpdate3.dll我々のウェブブラウザプラグインです。(実際のところ2つのプラグインを含んでいます:IEのためのActiveXと、FireFox,Chrome,他のブラウザのためのNPAPIプラグインです). Javascriptで、アクセスのためにgoogle.comのサブドメインを選択し、COMサーバーを使用できます。
psmachine.dll
psuser.dll
COMサーバーによって使用されている、カスタムのマーシャリング スタブです。マシーンインストールとユーザーインストールのomahaで同時にトリガさる、いくつかのウインドウズのバグ回りで使用されています。

















Comments