====== 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.

===== How it keeps you safe =====

  * **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.

===== Turn updates on =====

  - Copy the sample file ''PBUPDATE.CFG.SAMPLE'' that comes with ProBoard to ''Configs\PBUPDATE.CFG''.
  - 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 [[v4:install:upgrade_16bit|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.