Making zsync Downloads
Note that zsync only (currently) supports single-file downloads. I am currently of the opinion that this is sufficient: it is a file distribution method, and, like .tar.gz, it is up to the downloader to worry about extraction, permisions, etc. zsync is not competing with rsync for synchronising directory trees between machines and over shell accounts.
zsync is only useful for files that are either:
- Uncompressed and unencrypted, and where older versions share content with newer versions. Something like a Debian
Packagesfile for instance, thought that is probably too small to be worth syncing with zsync. - Compressed or encrypted piecewise, and older versions have some of the pieces unchanged. For instance daily build .iso images of Linux distribution installers or live images.
- Compressed files or tarballs, unencrypted, compressed in a manner compatible with the rsync algorithm, such as
gzip --rsyncable. It is possible to distribute updates of large compressed source code dumps in this way, such as the Linux kernel, but it depends on the distributor making rsync-friendly snapshots.
So, for example, zsync is useless for individual Debian or RPM package files, and is useless for bzip2 files, because these are not (as far as I know) piecewise compressed or compressed in an rsync-friendly way.
In the compressed file or tarball case, I recommend using the -Z option to zsyncmake to make the most forward-compatible download (and zsync-0.6.4 will issue a warning if a not-forward-compatible download is created).
Distribution
The other consideration is how people will access the zsync download. Remember that people have to have access to both the .zsync meta-file, and the full download that it describes.
The server hosting the full download:
- must support HTTP
Range:requests (almost all do). - should support HTTP multipart/byteranges responses, HTTP/1.1 and pipelining.
- Currently it must not use
Transfer-Encoding: chunked(yes, I know that makes zsync non-compliant). - It should not be generating the content dynamically; the target file must not change between generating the .zsync file and the user attempting the download, or the whole process does not work.
- It should not be HTTPS.
If you are hosting the download yourself, then simply put the .zsync in the same directory on the webserver as the download (this is the setup assumed by default by zsyncmake). zsyncmake inserts a relative URL by default, so this will work even if your download directory is then mirrored to other web servers. If you want the .zsync to be in a different directory, specify the relative URL to the full download (for example, if the .zsync will go in a zsync/ subdirectory, specify -u ../orig_filename.tar.gz).
If the main download and the .zsync are on different servers, specify the full URL to the main download with -u. If you have a set of mirror sites, if you had only a single absolute URL in the .zsync then you would lose the benefit of the mirrors; so you can specify multiple -u options to provide multiple URLs, and the zsync client will choose between them (currently randomely, but it may change later to choose more intelligently).
You can even offer a .zsync for a download provided/hosted by someone else. You have to download the file yourself, and generate a .zsync from it. Specify the original URL with -u, and then put the .zsync on your own webserver.
Other Considerations
I suggest serving .zsync files with a MIME type of application/x-zsync if possible. The zsync client does not need this, though. For example, for Apache, include
application/x-zsync zsync
in your mime.types.
Set suitable content expiry headers on .zsync and other downloads, to help web proxies work out how long they can cache it. zsync itself always goes back to the server, although with the -k option it will use If-Modified-Since headers to avoid redownloading the .zsync unnecessarily.
Do not point the full download at content which is negotiated: it must always be exactly the same as the file supplied to zsyncmake.
See also the page on client/server issues, which contains useful info for webmasters and also explains errors that could be seen by users.
