You are here
Please note that this page applies to v16.0 (Debian 10/Buster based) and newer TurnKey Linux releases. If you need to check the integrity of a legacy build prior to v16.0, please see the legacy release verification page.
TurnKey rotates our image signing keys for each major release so it's important to use the key relevant to the release that you are using. E.g. if you download the v18.2 WordPress ISO (turnkey-wordpress-18.2-bookworm-amd64.iso) then first verify the hash file is signed by the "bookworm" release key and then verify that ISO hash. and the signiture of the hash file release of an appliance (based on Debian "Bookworm") you'll need to verify the ISO (or other downloaded build) with the "bookworm" key. E.g. The keys can be found
All TurnKey Linux software appliance images have an accompanying '.hash' file. This file contains the SHA256 and SHA512 checksums of the relevant image. It is also signed with the private component of the relevant GPG release key (in the case of v18.x; the "bookworm-images" key). It also contains instructions on how to check the SHA sums, as well as verify the signature.
Getting the .hash file
Using 18.2 WordPres ISO as an example, you can find the relevant .hash file by clicking the "Manifest & Sigs" link on the appliance page. I.e. in our case, we'd browse to the WordPress appliance page, click the "Manifest & Sigs" link next to the ISO download link. Then find the .hash file that exactly matches the name of the downloaded image (with an additional '.hash' suffix) download the file. E.g. for Core v18.2 (Debian 12/Bookworm based images):
https://releases.turnkeylinux.org/turnkey-wordpress/18.2-bookworm-amd64/turnkey-wordpress-18.2-bookworm-amd64.iso.hash
The '.hash' files are also available direct from one of our mirrors, e.g. you will find both the ISO and the .hash file together via http://mirror.turnkeylinux.org/turnkeylinux/images/iso/
Note the ISO and matching hash file have (almost) identical names - with the exception of the .hash' suffix. I.e. WordPress v18.2 ISO and relevant .hash file filenames:
turnkey-wordpress-18.2-bookworm-amd64.iso turnkey-wordpress-18.2-bookworm-amd64.iso.hash
As noted above, the file itself contains instructions, but we'll cover the whole process here. The verification is essentially a 2 step process:
- Verify the hash file signature to check the hash file was provided by us; then
- Verify the hash of the ISO file against the relevant hash in the .hash file.
Verify the hash file signature
To verify the integrity of the downloaded hash file, you must first add the public component of the TurnKey Linux release key to your keychain. The first step is to find the appropriate key. The key to use will depend on the Debian codename of the TurnKey release you wish to use (hint: it's in the name of the file - between the TKL version number and the architecture). Also, here is a table that maps TurnKey versions to Debian codenames:| Notes | TurnKey version | Debian codename |
|---|---|---|
| Deprecated version | v15.x (e.g. 15.0, 15.1, etc) | Stretch (aka Debian 9) |
| Deprecated version | v16.x (e.g. 16.0, 16.1, etc) | Buster (aka Debian 10) |
| Legacy version (at the time of writing) | v17.x (e.g. v17.1) | Bullseye (aka Debian 11) |
| Current version | v18.x | Bookworm (aka Debian 12) |
| Upcoming/new release (in progress at time of writing) | v19.x | Trixie (aka Debian 13) |
| Unreleased future version | v20.x | Forky (aka Debian 14) |
Note that we rotate our keys for each major version release so be sure to use the key for the relevant specific release. The has file contains the instructions to download the key from a public key server but the keys are also avaialble from GitHub. using Linux, you can use GPG to download the key directly from TurnKey's GitHub "common" repository and add it to your GPG keyring (this example uses v16.x/'buster' - be sure to update the CODENAME value):
$ CODENAME=buster # NOTE update this to relevant release codename
$ curl https://raw.githubusercontent.com/turnkeylinux/common/master/keys/tkl-$CODENAME-images.asc | gpg --import
$ gpg --list-keys --with-fingerprint release-$CODENAME-images@turnkeylinux.org
pub rsa4096 2020-02-05 [SC] [expires: 2040-01-31]
A8B2 EF42 8781 9B03 D351 6CCA 7623 1C20 425E 9772
uid [ unknown] TurnKey GNU/Linux Buster Images (GPG signing key for TurnKey Linux Buster Images) <release-buster-images@turnkeylinux.com>
sub rsa4096 2020-02-05 [S] [expires: 2040-01-31]
(As is hopefully obvious, the return text will vary depending on the codename being used).
Then verify that the .hash file is signed with our key (still using the v16.x/Buster based example).
$ gpg --verify turnkey-core-16.0-buster-amd64.iso.hash gpg: Signature made using RSA key ID 76231C20425E9772 gpg: Good signature from " TurnKey GNU/Linux Buster Images (GPG signing key for TurnKey Linux Buster Images) <release-buster-images@turnkeylinux.com>"
Verify the checksum of the ISO against the hash file
Ensure that the ISO file and the .hash file are in the same directory. The quickest, easiest way is to use the relevant flavour of the shasum tool to automatically check the ISO against the checksums in the .hash file; like this:
$ sha256sum -c turnkey-core-16.0-buster-amd64.iso.hash turnkey-core-16.0-buster-amd64.iso: OK sha256sum: WARNING: 32 lines are improperly formatted $ sha512sum -c turnkey-core-16.0-buster-amd64.iso.hash turnkey-core-16.0-buster-amd64.iso: OK sha512sum: WARNING: 32 lines are improperly formatted
Please note that you can safely ignore the warning regarding "improperly formatted lines". That's just because we also include instructions within the hash file (and obviously they aren't properly formatted checksums!). The important part is where it says "turnkey-core-16.0-buster-amd64.iso: OK".
Alternatively, you can generate the checksum and manually compare that against the relevant checksum in the .hash file. E.g.:
$ sha256sum turnkey-core-16.0-buster-amd64.iso 171bb1c9fdba78830e7c5c0d084cf4b448ae564b041fff592f46a9306d51dbf7 turnkey-core-16.0-buster-amd64.iso $ sha512sum turnkey-core-16.0-buster-amd64.iso 20470be463dcb7f3b3a8a6ba4d8b25643775c8495547c75ba7c3ed545b4b0535892d84c40c987d00acf5eddbc49c9195556e750935456e9e538e5cccca7b3093 turnkey-core-16.0-buster-amd64.iso
What to do if it fails?
If the first (signature validation) step fails, then there is a slim chance that the file has been corrupted. If you can open it in a Linux friendly text editor (i.e. NOT notepad or any word processing software) and read it clearly, then corruption is highly unlikely and something malicious is possible. If this occurs, please alert us ASAP by posting on the forums ideally, or emailing to support AT turnkeylinux.org.
If the second step (validating the ISO checksum) fails, then corruption is the most likely cause. I suggest that you copy the checksum that you got from your original ISO (so we can compare later), and try downloading the image again.
Repeat the second step again and hopefully it should now work. If not, compare the first ISO's checksum against the checksum generated from the new ISO. If they don't match (i.e. you now have 2 ISOs and a .hash file; neither of the ISO checksums match each other, or the hash in the .hash file) then it seems likely that there is something messing up your internet traffic and corrupting the image. You can try again, or perhaps try from a different mirror?
If the 2 ISO checksums that you generated match, but don't match the checksum from the .hash file, then something fishy may well be going on! As above, please let us know about that ASAP. Again, by posting on the forums, or emailing to support AT turnkeylinux.org.