Auto-Update Patch Technology

Introduction
Auto-Update Patch Technology (AUPT) is the existing patching technology found in all homebrew patches in the webos-patches feed. AUPT is built into the installation and removal scripts of patches and allows patches to be installed/removed even after faulty installs, partial or full erases, webos doctors and even OTA updates to new WebOS versions!

There is also a concept of placeholder patches in the webos-patches feeds. All patches will at least build a dummy package with version ending in -0. These dummy packages may be installed to serve as a placeholder so that when they are ported to the new webOS version you will see the Update available in Preware. This will be useful to know when a patch has been ported to the new webOS version after an OTA update without having to check the forums every so often.

All patch installations and removals will now log to /media/internal/webos-patches.log and should be examined for detailed information with regards to any patch installation or removal failures.

Installation
Always install patches with Preware or webOS Quick Install v3.01 or later.

Verification
You may wish to verify that all of your installed patches were indeed installed with AUPT built in and that there are no left-over older or incompatible patches installed. In order to do this, you can open the text file .webosinternals.patches.packages found in USB mode from your PC. Each package should contain "aupt-N" indicating the version of aupt built into that patch. If there are ANY lines in that file that contain nothing after the package name that indicates an old incompatible technology was built into that patch. Remove these packages immediately and re-install (see: Installation section)

Emergency File Verification
Upon installation, this package will run through all known stock md5sums and check against the known safe patch technology version(s). Simply install this package and if you receive an error that means that there is some unknown or outdated file modification or patch installation. If installing via Preware you can tap "Show IPKG log" to see which packages/files are touched by outdated/unknown patching technologies. You can also check the webos-patches.log file in USB mode for this information.

Re-installation and Upgrades
There are various scenarios you may find yourself in where a patch may be installed or uninstalled. We will discuss what to do after each of these situations.

webOS Doctor
The webOS Doctor is a great way to ensure you are running completely stock Palm webOS files in the root filesystem. There are 3 situations you can be in with patches installed after WebOS Doctor.


 * If you used a doctor version that is a PRIOR webOS version than the one that was running when you installed the Patches, install "Emergency Patch Recovery" (EPR) to wipe the device of the patch package information. There are no supported downgrade automatic patch installations.


 * If you used a doctor version that is the SAME webOS version as the one that was used to install the Patches, simply install "Emergency Service Enabler" (ESE) to re-apply all of your installed patches.


 * If you used a doctor version that is a LATER webOS version than the one that was running when you installed the Patches, use Preware's Update All feature. Launch Preware, Update Feeds, tap Package updates and tap update all.

Partial/Full Erase
All of your homebrew and App Catalog packages as well as all media data including pictures survive a webOS Doctor and sometimes it is desired to wipe clean the media partition or remove all packages. The situation may arise where you needed to do a partial or full erase without doctoring the device. If you perform a partial or full erase while patches are installed, this will only remove the package data that lists these patches as installed in Preware and webOS Quick Install. The patches will still be applied to Palm's WebOS files. There is not yet a supported method to recover the patch package data. For now it is recommended to clean up all the patches via one of the following methods. These methods are listed in order of robustness. The only -guaranteed- way to ensure stock Palm webOS files is by using the webOS doctor: Webos Doctor Versions


 * Install "Emergency Patch Recovery" (EPR)
 * webOS Repair Utility
 * webOS Doctor

AUPT patches are built with smart post-install scripts that are able to detect when a patch is already applied to the stock webOS files. If you remember all the patches you had installed before the partial/full erase you may simply re-install each Patch individually as usual (Preware or QI v3.01 or later)

Preware
In the past it was recommended and required to remove all patches prior to updating webOS Over The Air (OTA). The new AUPT-6 system strives to makes this unnecessary and allow you to leave patches installed and then update them all after an OTA update to a new version of webOS. Not all (e.g. muffle logging) patches are OTA-safe under the AUPT-4 system so it may still be recommended to do so in the meantime. After a webOS OTA update you may use Preware's Update All feature. After an OTA update perform the following steps:


 * Launch Preware
 * Tap application menu -> Update Feeds
 * Tap Package Updates
 * Tap Update All.

(SEE: Known Issues section for known roadbumps in Preware's Update All function with regards to patches)

WebOS Quick Install
WebOS Quick Install is fully compatible with webOS-Internals Auto-Update Patch Technology (AUPT). When you enter the Tweaks section, after a webOS update, WebOS Quick Install will detect the version change and will open an update helper.

For on-feed patches, the update helper will update out-of-date patches to the new version's equivalent (or a dummy package if an updated patch has not yet been released).

For [ .patch files installed with WebOS Quick Install], the update helper will uninstall them. It will also check to see if the patch can be successfully re-applied. If it can be re-applied, the patch will be reinstalled.

Submissions
Submit all patches to be included into the webos-patches feed found in Preware and webOS Quick Install to: http://patches.webos-internals.org/

aupt-1

 * First implementation

aupt-2

 * Attempt to re-order logic in prerm to check for OTA first before trying to -R the patch

aupt-3

 * Fixed order of OTA checking to avoid potential rare case of OTA containing changes that allow a patch to -R incorrectly
 * Fixed bug in aupt-2 so that patches actually get unapplied
 * Renamed backups file to file_list in patch control dir to avoid potential conflicts with Palm backup operations

aupt-5 (used in alpha patches feed)

 * Attempt to make all patches OTA safe and to support also patching of 3rd party applications
 * Also these scripts now supports themes, Theme Manager already utilizes these scripts to install themes
 * Has support for moving to aupt-6 at some point that uses different name for backup files
 * Added more check and made patching to abort in situations where end result can not be guaranteed such as if md5sum can not be retrieved for the file to be pathed
 * Binary patches are also now handled correctly and made sure that only original file can be binary patches
 * Disallowed replacing of files through additional files (can be configured to allow it if really needed)
 * Should support situations where OTA has removed/added files or even made the exact same change for the file than a patch

aupt-6 (not in use at all, yet)

 * Defaults to new backup file name (.webosinternals.orig. )
 * Updates old backup files if found, and wont install if older than aupt-5 patches installed

AUPT Notes (aupt-5)
- Install can (should :) only fail on following situation:

* Entered patch information is incorrect * One of the required binaries can not be found * Md5sum can not be find for the files to be patched * Generation of patch control data or backup files fails * Patch can not be fully applied and patch reversing test fails * File to be binary patched does not exist at all in the given path * File to be binary patched is not orginal state or already patched * Additional file already exists and is not the same file is not an   actual additional file (i.e. file is provided by system package)

- Un-install can (should :) only fail on following situation:

* Entered patch information is incorrect * One of the required binaries can not be found * Patch can not be unapplied cleanly and the files that fail are not updated by OTA (ok if patch is fully unapplied already) * Binary patch can not be restored and it is not updated by an OTA

- OTA / Update handling on patch installation (postinst)

* Check if file that has backup file is in original state, if it is then its most likely updated by ota so remove backup, so it gets re-created * Check if cryptofs files are being modified for the first time, if they are then update the file_control version info

- OTA / Update handling on removal of the patch (prerm)

* If md5sum cannot be fetched for a file that exists then its most likely removed by an OTA or is a file created by the patch so   make sure that file and backup remain removed after removal of    the patch (created_list) * Check if the files md5sum is the same as what the unmodified file should have, if yes then the file has been replaced by an OTA, so make sure that the file is as it is after removal of the patch and allow patching of that file to fail (restore_list) * Check if backup file has different md5sum now than when the patch was installed, if it has then its change is cause by OTA most likely so allow this restoring of this file to fail, also make sure that this file stays uneffected by the removal of the patch (restore_list) * Check if the file has been removed then it is most likely don by OTA so allow patching of that file to fail * If cryptofs file has been restored to original state then remove the version info of that file since its not needed anymore

Preware
There are some known bumps in Preware's update-all with regards to patches, but no major roadblocks. The known issues and workarounds for them are:


 * It will stop when trying to update a dependent package. The workaround here is to remove patches that depend on another patch or package that has an update. For instance the uscl memos patch depends on universal command line patch. The update all will fail when it gets to these patches, and you can workaround that by removing the uscl memos patch and then re-running update all.
 * When the "install" part of the remove/install update process for a patch fails, Preware's installed list doesn't refresh automatically so the failed patch still lists on the update screen as installed. You can workaround this by updating feeds or tapping "remove" on the left-over package in Preware.

Miscellaneous

 * There are rare circumstances where a collection of patches in the same category may have to be installed/removed in a certain order and may fail (safely) to install or remove in different orders.
 * aupt-2 has a bug in the removal logic that cause it to see all packages as updated and removes the package without actually unapplying the patch.

Known Conflicts

 * Greg's great Messaging Plugins solution contains a patch to the messaging application that has yet to be incorporated with AUPT. This may cause conflicts with some messaging patches causing installation to fail and should -always- be removed prior to a webOS OTA update.
 * Themes have yet to be incorporated into AUPT and may cause conflicts with patches. Themes should also -always- be removed prior to a webOS OTA update.

Troubleshooting
Patching is by nature a very ugly beast. There are bound to be unforeseen issues and difficult to debug situations. In the end you can always get back to a completely stock webOS by performing a full erase followed by a webOS doctor. Here we will list some known problems and workarounds.

Emergency
In the event that you find yourself in an unsupported situation with regards to patching or simply want to ensure a clean slate of stock Palm WebOS files without any patches, the following is the only guaranteed method:


 * Backup / take not of any homebrew packages installed as well as any App Catalog applications that are not backed up via your Palm Profile
 * Go into device info -> reset -> Partial Erase to erase all applications.
 * Perform webOS Doctor to ensure all Palm webOS files are stock.

You may also try the quick solution of installing "Emergency Patch Recovery" (EPR). Please note that this relies on information that patches saved/stored and is not a robust or guaranteed way to ensure patches are completely removed. It is very safe and works a vast majority of the time as intended, it simply is not guaranteed to clean up everything.