snapaid
=======

This is a utility that will make it easier to find and download the
correct snapshot or release.  It will also fetch and verify the GPG
signature and hash of the snapshot to ensure that you are getting the
correct file.

![Screen shot of snapaid.sh find](images/snapaid.find.png?raw=true)

Quick Start
-----------

The only file needed is the snapaid.sh script.  The other files in the
repo are used for generating the index.

Setting up and finding a snapshot:
```
$ wget https://www.funkthat.com/gitea/jmg/snapaid/raw/branch/main/snapaid.sh
$ chmod 755 snapaid.sh
$ ./snapaid.sh find
```

When running with the find argument, you can provide additional terms
and/or selections as arguments.  If you want to automatically download
the latest FreeBSD CURRENT snapshot vmdk that is xz compressed for the
for amd64 architecture, you run the command:
```
sh snapaid.sh find CURRENT vmdk xz amd64 1
```

Each term between `find` and `1` refines the search, and the `1` selects
the first image.  The list is sorted by date, then by release, where
the latest is shown first.

Verifying
---------

If you've already installed and setup snapaid.sh previously, you can skip
the first two lines.

Setting up and verifying a snapshot or release:
```
$ wget https://www.funkthat.com/gitea/jmg/snapaid/raw/branch/master/snapaid.sh
$ chmod 755 snapaid.sh
$ ./snapaid.sh verify FreeBSD-12.2-RELEASE-amd64-mini-memstick.img.xz
```

Note that the provided filename *MUST* match exactly the released name so
that it can be found in the index.  It could be possible in the future
to find it via shasum, but that is not implemented yet.

Notes
-----

This repository will be signed by my FreeBSD GPG key.  It is available
at: https://www.freebsd.org/doc/en_US.ISO8859-1/articles/pgpkeys/pgpkeys-developers.html#pgpkey-jmg

Now that snapaid has migrated from GitHub to Gitea, you will see the
verified lock icon with the commits.  This is because unlike GitHub,
Gitea won't falsely show a commit as verified unless it was signed by
and only by the user's PGP key.

NOTE: The xz vs non-xz versions of some of the images are not able to be
differentiated.  Currently sorting rules should always put the xz version
before the non-xz version.

NOTE: Only snapshots that have SHA512 hashes are included.  This excludes
most snapshots from 2015 and before.  The tool could be updated to include
SHA256, but not a priority currently, and most/all are not available for
download.

backend
-------

The backend is just a simple text file which indexes all the published
snapshots.  It is built from the emails to the freebsd-snapshot and
freebsd-announce lists.  After verification of the email's signature,
the SHA512 entry lines are extracted, the file name is parsed, and added
to the complete index.  The message-id of the email is in the index so
that the frontend can download the original email and verify the GPG
signature locally.  The complete index is used for verifying a snapshot
that has already been downloaded.  Another index is also maintained
which only contains the currently available to download snapshots.  This
may contain snapshots that no longer exist, as it is only
updated/checked when a new snapshot is released.

The procmail rc lines that I use:
```
:0c
* Delivered-To: (freebsd-)?announce@([^@\.]*\.)*freebsd.org
| $HOME/bin/snapwrap.sh

:0
* Delivered-To: (freebsd-)?snapshots@([^@\.]*\.)*freebsd.org
{
:0c
ml/snapshots

:0
| $HOME/bin/snapwrap.sh

}
```

The first rule is used for RELEASE announcements.  They are copied (`c`)
so that a later rule can file them in the proper mailbox.  The second rule
is for the snapshots, and smiilarly organized, but the mailbox filing
happens here.

The `snapwrap.sh` script is included in the repo, but the command to deploy
the database to the FreeBSD.org servers has been deleted, but it is a
simple: `tar -cf - <files> | ssh freefall tar -xf -` type command.