Development/Online Update

From The Document Foundation Wiki
Jump to: navigation, search

This is a page summarizing plans to change the LibreOffice Online Update process - reusing the mechanism that Mozilla is using. The reasoning is that Mozilla can do silent updates on Windows, is cross-platform, and has the same license as LibreOffice itself. This is part of GSoC 2015 work, and bugreport related to this is tdf#68274.

Summarizing information from Mozilla

Mozilla's "mozilla/tools/update-packaging/" contains code that generates update packages as complete/partial mar files (patches) that can be stored on an update server. A partial mar is a bzip2 archive of binary diffs between the current and new releases, and a complete mar contains a copy of every file in case the partial doesn't work or the installed build is more than one version behind [1]. The names of these mar files should be "update.mar".

This directory also creates snippets which a user's application can fetch from an update server to gain information that a new update is available for the user's given application. These snippets are the XML files documented on the Mozilla wiki. As it seems that Mozilla does the update checking and downloading via JavaScript files, we will need to reimplement this functionality if necessary. Fortunately, "mozilla/toolkit/mozapps/update/nsIUpdateService.idl" contains the necessary documentation for the interfaces of these files. This also means that our infra does not have to exactly follow Mozilla's if we reimplement update checking and downloading.

Paraphrasing https://wiki.mozilla.org/Software_Update, we should use byte-range requests to download the update packages in small pieces. Once an update package is completely downloaded, its hash will be compared to the one from the corresponding XML snippet from the update server. If this is successful and if LibreOffice has permission from the user, update.mar is passed into updater.cpp's NS_main(). The functionality of updater.cpp should be described in https://wiki.mozilla.org/Software_Update#Processing_the_Update. This is also where the Windows Silent Update service is used.

Updater requirements

This process is similar to the one documented at https://wiki.mozilla.org/UpdateGeneration with some slight differences.

  1. Use --with-package-format=archive to create the archived versions of LibreOffice needed. Archived versions of LibreOffice are located in "/core/workdir/installation/" after a successful build.
  2. Use --enable-online-update=mar to build a version of LibreOffice with the necessary executables found in "/core/onlineupdate/".

Signing MAR files

These steps are similar to what is described in https://wiki.mozilla.org./Software_Update:MAR_Signing_and_Verification.

  • Create an NSS db: "mkdir NSSDBDir && cd NSSDBDir; certutil -d . -N". The "certutil" program should be somewhere in "/core/workdir/UnpackedTarball/nss/". Enter a password for the NSS db, or leave it blank if you are testing this functionality.
  • Create a certificate called "mycert": "certutil -S -d . -s "CN=My Cert" -n mycert -x -t ",,u" -g 2048".
  • Get a DER file with the cert: "certutil -L -d . -n mycert -r > mycert.der".
  • Sign a MAR file: "mar -d NSSDBDir/ -n mycert -s update.mar update_signed.mar".
  • Unsign a MAR file: "mar -r update_signed.mar update.mar".

Infra needed

High-level overview (from http://www.aosabook.org/en/ffreleng.html)

5. QA and verify that users can safely update from previous versions to newer versions via updates

Files in tools/update-packaging/:

   - generatesnippet.py:
       - This script generates the complete snippet for a given locale or en-US.
         Most of the parameters received are to generate the MAR's download URL and determine the MAR's filename
       - need to deal with locale/default URL issues
       - TBD
   - make_full_update.sh: stores the contents of a directory into a mar file
   - make_incremental_update.sh: stores the differences between two directories into a mar file
   - make_incremental_updates.py: takes a patchlist file as an argument, and creates a set of partial patches
       - requires application.ini
       - check if the patchfile contains one patch for every line of the file
   - unwrap_full_update.pl: unpacks a full update package generated by make_full_update
   - Makefile.in: looks interesting; will need to figure out what it does
   - test/: appears to have the necessary directory layout of updates to be used by the above files

Files to check:

   - update.link (from GetUpdateFileName() (https://dxr.mozilla.org/mozilla-central/source/toolkit/mozapps/update/updater/updater.cpp#2141))
   - update.status (from IsUpdateStatusPendingService() (https://dxr.mozilla.org/mozilla-central/source/toolkit/mozapps/update/updater/updater.cpp#1886),
                    IsUpdateStatusSucceeded() (https://dxr.mozilla.org/mozilla-central/source/toolkit/mozapps/update/updater/updater.cpp#1919))
   - update-settings.ini (from ReadMARChannelIDs() (https://dxr.mozilla.org/mozilla-central/source/toolkit/mozapps/update/updater/updater.cpp#2124))
   - application.ini (for generatesnippet.py)

General information about updates:

   - https://wiki.mozilla.org/Software_Update

Silent updates:

   - https://wiki.mozilla.org/Windows_Service_Silent_Update
       - we should check the listed test cases once implemented in LibreOffice

Treeherder (test reporting):

   - https://developer.mozilla.org/en-US/Firefox_OS/Automated_testing/Treeherder

See Also testing

The linked site is shown to automatic update users after a successful update process. This is part of the testing for the release process.

Development/Updater/SeeAlso