Auto-update design

T(DesignDocument)?

A design for auto-update of the BOINC client software.

Auto-updates come from projects

A project wishing to provide auto-updates should offer a web interface letting users opt in or out. The auto-update mechanism uses BOINC's existing code-signing mechanism; update files are signed with the project's code-signing key.

Version directories

A 'version' of BOINC includes the core client, the Manager, the screensaver, and possibly other files, such as graphics files and XML skin description files. It also contains an 'updater' program. A version is stored under the project directory in a 'version directory' named boinc_MAJ_MIN_REL.

Scheduler RPC changes

A scheduler reply may contain an instruction to download and switch to a new version:

<auto_update>
    <version>
        <major>5</major>
        <minor>9</minor>
        <release>5</release>
    </version>
    <file_ref>
        <file_name>boinc_5.9.5.exe</file_name>
    </file_ref>
    <file_ref>
        <file_name>updater_5.9.5.exe</file_name>
        <main_program>1</main_program>
    </file_ref>
    ...
</auto_update>

A scheduler request (in addition to existing fields for the core client's major/minor/release) has a new optional field

<update_in_progress>
    <version>
        <major>5</major>
        <minor>9</minor>
        <release>5</release>
    </version>
</update_in_progress>

Scheduler changes

The scheduler should send an update request only if

• the client has a version earlier than current;
• the client's version is at least 5.10 (or whenever this feature is added); and
• an update to the current version is not in progress.

Core client changes

Add -launched_by_manager flag; tells the core client that it was launched the the Manager.

The core client maintains an 'update command' structure, which is stored in the client state file. This structure exists only if an update is in progress.

On startup: if an update command is present in the client state file, and it matches the core client's version (i.e. this is the first time the core client is running after an update) remove the update command, and delete the version directory.

When processing a scheduler reply: if an <auto_update> element is present, create an update command structure.

When an update command exists, the core client attempts to download all the files listed in the update command. It stores these files in a version directory. When all the files have been downloaded, and all the signatures match, the core client does:

• If there is a GUI RPC connection from a local Manager, send it a command to exit.
• If there is a GUI RPC connection from a screensaver, send it a command to exit.
• Launch the updater program (the file marked as 'main program' in the update command structure). Pass it command-line arguments:
  • --run_manager if there is a GUI RPC connection from a local Manager.
  • --run_core if the core client was not launched from the manager
  • --run_as_service if the core client was running as a service (Windows).
• exit.

The updater program does the following:

• Copy files from the version directory to the main BOINC directory.
• If 'launched_from_manager' exists, launch the Manager (it will launch the core client). Exit.
• (Windows) If the core client is registered as a service, start it. Otherwise launch the core client.
• (Others) Launch the core client.
• If 'run_manager' exists, launch the Manager.

Manager changes

The reply to the get_cc_status() RPC (which is done every second) includes an optional <quit> tag. If present, quit. The authorize() RPC request includes a flag saying whether the Manager launched this client.

Screensaver changes

The screensaver periodically does GUI RPCs to the core client. Each GUI RPC reply includes an optional flag telling it to quit (this exists already).

Pathological cases

A user can enable multiple projects for auto-update. If an update is in progress, update commands for the same version from other projects will be ignored.