Program updates

A running v4 system can keep its programs current. PBDispatch checks a web folder for newer ProBoard programs and plug-ins, tells you what it found, and, only when you say so, downloads, verifies and installs them with a backup you can roll back.

Updates are off until you create a settings file, and nothing is ever installed without your say-so unless you schedule it yourself.

• Signed releases. Every release is signed by the publisher. PBDispatch refuses anything whose signature does not match the public key in your settings, and every file must match the size and SHA-256 checksum in the signed list. A hacked web server or a damaged download cannot install anything.
• Programs only. Only .exe, .dll and .p3x files with plain names can be written. Updates never touch your data, configuration, menus or screens.
• Only what you already have. An update replaces programs you already run. It adds new ones only if you set installnew yes.
• Your own builds are protected. List a program you built yourself as a pin and no release will replace it.
• Backup and roll back. Replaced files are copied to Update\Backup (a folder next to PBDispatch.exe) first (the newest five backups are kept), and Tools > ProBoard Updates > Roll Back puts the newest one back.

1. Copy the sample file PBUPDATE.CFG.SAMPLE that comes with ProBoard to Configs\PBUPDATE.CFG.
2. Edit it. Set url to the publisher's web folder, which must start with https:, and paste the publisher's publickey line. - Restart PBDispatch. Its log shows “Program updates enabled”. If you delete PBUPDATE.CFG, updates are off again. Here is a sample file with the usual settings: <code> url https://www.proboardbbs.com/PBupdate/ publickey PASTE-THE-BASE64-TEXT-HERE channel stable checkhours 24 autostage no installnew no idleonly yes </code> ^ Setting ^ Meaning ^ | url | Required. The publisher's folder; https only. PBDispatch adds x64/ or Win32/ itself. | | publickey | The publisher's public key. Updates are refused unless the signature verifies with it. You can give more than one line. | | channel | stable for normal releases. A publisher may offer others, such as beta. | | checkhours | How often PBDispatch looks, in hours. 0 means only when you ask. A check only tells you. | | autostage | yes downloads and verifies after a check finds an update, so installing is instant. It still installs nothing. | | installnew | yes also adds programs from the release that you do not have yet. | | idleonly | yes refuses to install while ProBoard.exe is running, that is, while callers are online. Recommended. | | reportname | An optional name for your board in the publisher's web log. Leave it out to stay anonymous. | | pin | A program never to replace. One line each, for example pin ProBoard.exe or pin PEX/MyPlugin.p3x. | | pexdir | Where plug-ins live, if not the PEX folder next to PBDispatch.exe. | | maxfilemb | Refuse any single download bigger than this many megabytes. | | enabled | no switches updates off without deleting the file. | ===== Check for and install an update ===== In PBDispatch, choose Tools > ProBoard Updates > Check for Updates / Install. It shows what would change and offers to install it, or only to download it. - The first time, if every file on your PC already matches the published release, PBDispatch just records that you are on that release. - Later releases are offered when their number is higher than the one you have. - A program you changed yourself within the same release is not offered. An install does this: - Downloads only the changed files into Update\Staged and checks them. - Stops if ProBoard.exe is running, unless you choose to force it. Windows lets you replace a running program, but the running copy keeps using the old code until it restarts. - Copies the files it will replace into Update\Backup. - Renames each old program to .old and moves the new one into place. If anything fails it puts the old ones back. - For a release that changes data file formats, asks you to confirm that you have run Upgrade Data first. See Upgrading from 16-bit ProBoard. Restart ProBoard and PBDispatch afterwards. A release replaces all its programs in one step, so do not install while callers are online unless you are sure. ===== Updating on a schedule ===== PBDispatch can run an update with no window, which suits a nightly job: <code> PBDispatch.exe /update check PBDispatch.exe /update download /spread 60 PBDispatch.exe /update install PBDispatch.exe /update rollback PBDispatch.exe /update status </code> * check only looks, and exits with code 10 if an update is available. * download downloads and verifies without installing. * install backs up and installs. Add /force to install while callers are online, or /pbupgraded to confirm you have run Upgrade Data. * Always add /spread <minutes> (0 to 180) to scheduled jobs. It waits a random time first, so that hundreds of boards do not all ask the publisher's server in the same minute. Everything is logged in LOGS\UPDATE.LOG. The exit codes are 0 (done, or nothing to do), 1 (error), 2 (blocked because ProBoard.exe is running), 3 (the release needs Upgrade Data first) and 10 (a check found an update). For example, a nightly download from PBEVENTS.CFG: <code> event NightlyUpdateCheck at 04:30 action run “C:\ProBoard\PBDispatch.exe /update download /spread 60” endevent </code> ===== Privacy: what the publisher can see ===== Each check asks the publisher's web server for one file. The server's log therefore shows your IP address, the time, the release you have installed, whether you run x64 or Win32, the channel, the client name PBDispatch-Update and which program files you downloaded. If you set reportname, it also shows that name. Nothing else about your PC, your board, your users or your files is sent. ===== What updates do not replace ===== * The installer (PBInstall.exe'') and the sample plug-ins are not part of an update. * Menus, screens, documents and the SDK files are not updated, and PBInstall does not overwrite your copies of them either. If you want a newer version of one, copy it from a new package yourself.