3.1. Preparing The ISO For Download

A CD image is a filesystem called iso9660, but for this discussion, we can safely talk about a CD image as being a big file called an "ISO image" (about 650MB) that contains files at various offsets. For instance, if a CD contains a 567 byte file named README, the ISO image might contain the README file's contents between offsets 20480000 and 20480567. You can visualize a CD image as:

                    --------------------------------------------------------
      ISO Image:    |xxxx| file-0 |xx| file-1 |xxx| file-2 |x| file-3 |xxxx|
                    --------------------------------------------------------
      

The "x" areas of the image contain things like directory information, zero padding, disk name, boot block, etc.

jigdo-file takes two things as input: the complete CD image (so the ISO already needs to have been made) and a set of files which may or may not be in the image. Here's a visualization of jigdo-file's input:

                    --------------------------------------------------------
      ISO Image:    |xxxx| file-0 |xx| file-1 |xxx| file-2 |x| file-3 |xxxx|
                    --------------------------------------------------------

                         ----------  ----------              ----------    ----------
      Loose Files:       | file-0 |  | file-1 |              | file-3 |    | file-4 |
                         ----------  ----------              ----------    ----------
      

Through magic, jigdo-file finds out which of the loose files are contained in the ISO image and their offsets within the ISO file. It outputs two files: a ".template" file and a ".jigdo" file.

3.2. The .template File

Given an input of an ISO image and a set of files which may or may not be in the ISO image, jigdo-file outputs a .template file for that ISO image. Here's what the .template file looks like:

                    --------------------------------------------------------
      .template:    |xxxx| md5-0  |xx| md5-1  |xxx|cccccccc|x| md5-3  |xxxx|
                    --------------------------------------------------------
      

jigdo-file found that the files file-0, file-1 and file-3 were contained in the ISO image. It removed the contents of the these files and replaced them with each file's md5 checksum (the md5-0, md5-1, etc).

The "x" data (directory information, zero padding, etc) within the ISO image is compressed and written to the .template file. Finally, any files within the ISO image that weren't supplied as loose files (like file-2) are also compressed and written to the .template file. This is shown as "c" data in the .template file visualization.

Loose files which were supplied to jigdo-file that aren't found in the ISO image (like file-4) are ignored.

3.3. The .jigdo File

Given an input of an ISO image and a set of loose files which may or may not be in the ISO image, jigdo-file outputs a .jigdo file for that ISO image. The Debian .jigdo files are gzipped, so you need to use zcat or zless to view them. Here's what a .jigdo file looks like when you gunzip it:

      md5-0=http://somemirror.org/file-0
      md5-1=http://somemirror.org/file-1
      md5-2=http://somemirror.org/file-2
      md5-3=http://somemirror.org/file-3
      

The .jigdo file simply provides a mapping between the md5sum of a file within the ISO image and the download URL of that file. There are some other things within the .jigdo file, and if you look through it, you'll see the .jigdo file has the same format as a ".ini" file. It should be self explanatory, but if you want the nitty-gritty details, see the jigdo documentation.

The format shown above is not quite what you'd see in a typical .jigdo file, but it's very similar. If you look at the [Servers] section at the bottom of the .jigdo file, you'll see exactly what the difference is between what I showed above and an actual .jigdo file.

3.4. Downloading The Image

Once you use jigdo-file to generate a .jigdo and .template file for an ISO image, anyone can use jigdo-lite to download that image. jigdo-lite downloads all the files of a Debian ISO using wget, assembles them and forms a copy of the original ISO image on the fly.