Development/Online Update
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
This is a page summarizing work 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. Work on this started as part of GSoC 2015 work, and bugreport related to this is tdf#68274.
The current status described here matches what is available in the libreoffice-24-2 branch as of early January, 2024.
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 compressed 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 metadata 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. As it seems that Mozilla does the update checking and downloading via JavaScript files, we needed to reimplement this functionality as 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.
The module external/onlineupdate is our integration of the relevant upstream Mozilla code. The corresponding tarball has been generated with external/onlineupdate/generate-sources.sh (it only bundles the relevant parts of the full https://github.com/mozilla/gecko-dev repo). The script external/onlineupdate/monitor-sources.sh can be used to monitor ongoing upstream changes to any of the files included in our tarball snapshot. An announcement that we reuse and bundle the Mozilla code is at “LibreOffice re-using Mozilla’s MAR-based updating functionality”.
Building and Testing
Currently, this feature is only meant to be available on Windows. (It also builds and works to some extent on Linux, but that is not an active development target.)
As a prerequisite, you need a (self-signed) RSA 4096 bit certificate, both as a DER file and stored in an NSS DB:
$ openssl req -x509 -newkey rsa:4096 -keyout .../cert-rsa4096.key.pem -out .../cert-rsa4096.pem # ... -sha1 -nodes -subj /C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommanNameOrHostname $ openssl x509 -outform DER -in .../cert-rsa4096.pem -out .../cert-rsa4096.der $ openssl pkcs12 -export -out .../cert-rsa4096.key.pfx -inkey .../cert-rsa4096.key.pem -in .../cert-rsa4096.pem -name myupdatecert # ... -password pass: $ mkdir .../nssdb $ certutil -N -d .../nssdb # ... --empty-password $ pk12util -i .../cert-rsa4096.key.pfx -d .../nssdb # ... -W
You will also need a web server to serve the update data, located at some BASEURL.
Your build configuration needs the following additional settings:
--enable-online-update-mar --with-online-update-mar-baseurl=BASEURL --with-online-update-mar-certificateder=C:/.../cert-rsa4096.der --with-online-update-mar-certificatename=myupdatecert --with-online-update-mar-certificatepath=C:/.../nssdb --with-package-format=archive msi
Run
$ make
to generate a base version workdir/installation/LibreOffice/msi/install/.../LibreOffice_...msi installation set. (Here and elsewhere, substitute LibreOfficeDev for LibreOffice in a --enable-release-build configuration.) Install it.
To create a delta mar file in the next step, you will also need to save now the generated workdir/installation/LibreOffice/archive/install/.../LibreOffice_...zip archive installation set and accompanying wordkir/installation/LibreOffice/archive/install/metadata file. Copy those two files to some place where they will not be overridden by the next make below.
Then, run
$ git commit -m 'update buildid' --allow-empty $ make $ make create-partial-info ONLINEUPDATE_MAR_OLDARCHIVE=/cygdrive/.../LibreOffice_...zip ONLINEUPDATE_MAR_OLDMETADATA=/cygdrive/.../metadata
to create a new version. (At a minimum, it needs a different git SHA build ID than the base version, which is accomplished with the empty git commit here. Further modifications could be provided as well.) The /cygdrive/.../ paths are the absolute paths to the saved archive installation set and accompanying metadata file from the previous build. This generates a signed workdir/update-info/LibreOffice_...from_..._partial.mar file and corresponding workdir/update-info/LOOnlineUpdater JSON file. The latter will look like
{
"from": "BUILDID",
"see also": "",
"update": {
"hash": "...",
"hash_function": "sha512",
"size": ...,
"url": "BASEURL/LibreOffice_..._from_..._partial.mar"
},
"languages": {}
}
where BUILDID is the git SHA build ID from the first build. Serve the mar file as BASEURL/LibreOffice_..._from_..._partial.mar and serve the JSON file as BASEURL/update/check/1/LibreOffice/BUILDID/PLATFORM/LOOnlineUpdater (where PLATFORM is e.g. Windows_X86_64).
For LibreOffice 24.2, this MAR-based automatic update is only available as an off-by-default experimental feature in LibreOffice. (On the master branch towards LibreOffice 24.8, it is no longer experimental, though.) To enable it, in the base version installation check both ▸ ▸ ▸ ▸ ▸ and ▸ ▸ ▸ ▸ ▸ .
In our source code, the update server URL is hardcoded to TDF's https://update-mar.libreoffice.org/ (in officecfg/registry/schema/org/openoffice/Office/Update.xcs), but can be overriden for testing purposes with the LIBO_UPDATER_URL environment variable. Also for testing purposes, an immediate update check (instead of only once every seven days, cf. isTimeForUpdateCheck in desktop/source/app/app.cxx) can be forced by setting the LIBO_UPDATER_TEST_UPDATE_CHECK environment variable. So run the base version installation with
LIBO_UPDATER_URL=BASEURL LIBO_UPDATER_TEST_UPDATE_CHECK=x "C:/Program Files/.../program/soffice"
to trigger an update check. It should first fetch the JSON update information file BASEURL/update/check/1/LibreOffice/BUILDID/PLATFORM/LOOnlineUpdater, see that it advertises a matching mar file, and then download the advertised BASEURL/LibreOffice_..._from_..._partial.mar file to UserInstallation/updates/0/update.mar. On the next start of C:/Program Files/.../program/soffice, the update code will apply that mar file and restart the updated LibreOffice: “Help - About LibreOffice” should now show the updated build ID.
The update code includes a Windows maintenance service (called LibreOfficeMaintenance, a copy of the upstream MozillaMaintenance service) that allows for privileged modification of the to-be-updated LibreOffice installation without user interaction. That service carries out a number of security and sanity checks, among them two checks that files in the to-be-updated installation set are signed. Those checks would fail for --disable-windows-build-signing. So for testing purposes, in a --disable-windows-build-signing --enable-dbgutil developer build, we apply an external/onlineupdate/unsigned-hack.patch that silences those two (failing) checks.
The update code generates UserInstallation/updates/0/update.log and UserInstallation/updates/0/update-elevated.log files, and our code triggering that update code additionally generates a UserInstallation/updates/updating.log file. (For --enable-sal-log builds, the content of the latter is also printed to stderr with SAL_LOG=+WARN+INFO.desktop.updater.) In addition, the maintenance service generates log files in the LibreOffice installation's program/logs directory.
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.