Guide Update mirror

Guide: the update mirror

What it is. OnAir normally asks api.github.com for the newest release and downloads the package from github.com. Where those are unreachable or slow (for example in China), you can point OnAir at a mirror: a web address that forwards those two requests. It is off by default; nothing is sent to any mirror unless you turn it on.

Where the settings are

Click the version button at the top right. The update window has Check now, Check for updates automatically, Download and install them by themselves, Include beta versions, and the mirror settings.

Update source

Choice	Meaning
Automatic: GitHub	GitHub only, unless you tick Use the mirror when GitHub cannot be reached. The mirror is then asked only after GitHub failed or timed out.
GitHub only	The mirror is never contacted.
Mirror only	Only the mirror is contacted. GitHub is never asked, so its checksum cannot be fetched (see below).

Mirror address takes https://mirror.example/{url} ({url} is replaced by the GitHub address; {urlenc} is the same, percent-encoded) or a base address such as https://mirror.example/gh (the GitHub address is appended after a /). It must be https.

The field is pre-filled with the project's own mirror, https://mirror.on-air.dev/{url}, a small Cloudflare Worker run by the maintainer. It forwards only the project's release list and release files. It is used only when you choose Mirror only or tick Use the mirror when GitHub cannot be reached. If it does not work from your network, type another mirror's address.

What a mirror can and cannot see

A mirror sees that you check for updates, your IP address and the version you run. OnAir only ever asks it for the project's own addresses (the releases list and release files of adswill/OnAir), never anything else.

How a package from a mirror is checked

1. Downloads are https only, with at most 5 redirects, a size limit (the size the release lists plus a little) and timeouts.
2. The SHA-256 of the package must match. When the list of versions came through the mirror, OnAir asks github.com itself for the checksum (the digest in its API, else the release's SHA256SUMS file). If the mirror's checksum differs from GitHub's, the update is refused. The window says "The list came through the mirror; the checksum was confirmed by GitHub."
3. If GitHub cannot be reached at all (or you chose Mirror only), only the mirror vouches for the package. OnAir says so ("only the mirror vouches for this package. Nothing is installed without your confirmation") and downloads only after you tick I understand, download it anyway. Such a package is never installed by itself: not at start, not when you close OnAir. You press Restart now and update.

So a bad mirror can refuse to answer or log your requests, but it cannot swap the package when GitHub is reachable.

Step by step: using a mirror in a blocked network

1. Click the version button.
2. Under Update source choose Automatic: GitHub and tick Use the mirror when GitHub cannot be reached. Check the Mirror address.
3. Press Check now. If GitHub fails, the mirror is tried.
4. When the update is found, press Download and install. If the window asks for confirmation because only the mirror vouched for it, read the text and decide.

Running your own mirror

The repository contains a small example, web/mirror-worker/worker.js. It forwards only GET requests for the project's release API and release downloads, with a strict allowlist, no cookies and no logging. Deploy it to your own Cloudflare account with Wrangler, then give OnAir https://<your-worker>.workers.dev/{url}. A mirror run by someone else is only as trustworthy as they are; the checksum rules limit the damage.

Troubleshooting

• "Not checked yet" or "checking...": the network is blocked; try a mirror or use GitHub only and download by hand from the release page.
• The update did not install: the window shows the setup exit code. Windows asks for permission to run the installer, Linux .deb installs ask for your password.
• Mirror refused: the checksum did not match GitHub's. Do not override; try again later.

Related

Install | Privacy | FAQ | Troubleshooting