Update changelogs and README
authorSteve McIntyre <steve@einval.com>
Wed, 20 Nov 2019 14:50:44 +0000 (14:50 +0000)
committerSteve McIntyre <steve@einval.com>
Wed, 20 Nov 2019 14:50:44 +0000 (14:50 +0000)
ChangeLog
README
libjte/ChangeLog

index c1790bf..bd51842 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,14 @@
-Version 1.22 (2019-11-05)
-
- * Add support for SHA256 checksums
+Version 1.22 (2019-11-20)
+
+ * Add support for SHA256 checksums, using jigdo format v2
+   + Changes to libjte to generate the new format as an option - still
+     defaults to v1 for cmpatibility for now
+   + libjte updated to major version 2
+   + Add support for v2 in jigdump, jigit-mkimage etc. too
+   + Add new jigsum-sha256 program, for the base64-like output with
+     sha256 checksums
+ * jigdump now also understands jigdo .iso.tmp files
+ * Misc small cleanups
 
 Version 1.21 (2019-02-04)
 
diff --git a/README b/README
index ac6ccdb..ed08d31 100644 (file)
--- a/README
+++ b/README
@@ -1,14 +1,15 @@
 README for JTE 1.22
 
 Steve McIntyre <steve@einval.com>
-05 November 2019
+20 November 2019
 
 License - GPL v2+. See the file COPYING for more details.
 
 JTE - Jigdo Template Export
 ===========================
 
-Introduction
+Introduction - jigdo and JTE
+----------------------------
 
 Jigdo is a useful tool to help in the distribution of large files like CD and
 DVD images. See Richard Atterer's site for more details. Debian CDs and DVD ISO
@@ -20,253 +21,396 @@ made up of smaller files. However, to be this generic is costly. Creating jigdo
 files from ISO images is quite inefficient - to work out which files are
 included in the ISO image, jigdo has to calculate and compare checksums of
 every possible file and every extent in the image. Essentially it has to
-brute-force the image. On my home system, it can take several hours to do this
-for a 4.5GB DVD image.
+brute-force the image. It can take a long time to do this for a large image
+(imagine a 4.5GB DVD image or a 30+GB Blu-Ray image).
 
-There are a few ways to improve this that I can see:
+I first started looking for ways to improve this back in 2004:
 
- 1. Modify jigdo so it knows about the internals of ISO images and can
+ 1. Modify jigdo so it knew about the internals of ISO images and could
     efficiently scan them (bad, not very generic for jigdo)
  2. Write a helper tool to dump extra information for jigdo to use alongside
-    the ISO image (helper tool written, but modifying jigdo to use this looks
-    HARD)
- 3. Patch ISO creation tools to write .jigdo and .template files
-    alongside the ISO image
-
-I've now done the third of these, and called the code JTE (or Jigdo
-Template Export). The code works fine, and runs in a very small
-fraction of the time taken to run genisoimage and jigdo
-separately. The output .jigdo and .template files work correctly,
-i.e. jigdo-file and the wrapper script jigdo-mirror accept them and
-will generate an ISO image that exactly matches the original.
-
-However, cdrkit / genisoimage is now deprecated in my opinion. The
-nice people working on xorriso (George Danchev and Thomas Schmitt)
-have helped a huge amount by cleaning up some of my code and wrapping
-it properly in a shared library. The code is now included here as
-libjte, and re-licensed slightly as LGPL v2.1 or later.
-
-Tools
-=====
-
-JTE also comes with some extra tools:
-
-jigit-mkimage, a simple and very fast tool to reconstruct image files
-from .jigdo and .template files. It doesn't have any logic to cope
-with downloading missing files, but will list the missing files that
-are needed. It is also much faster for people (like me!) who already
-have full local mirrors.
-
-iso-image.pl is a CGI script to wrap around jigit-mkimage if you'd
-like to be able to offer images for HTTP download without using up
-multiple gigabytes of disk space. And for added network efficiency the
-perl CGI also supports HTTP v1.1 byte ranges so clients can resume
-aborted downloads.
-
-jigit is a first attempt at a user-friendly wrapper for jigit-mkimage
-on a user's machine.
-
-parallel-sums is a simple extra utility to generate checksums quickly
-and efficiently, reading file data only once and calculating checksums
-using multiple algorithms in parallel.
+    the ISO image (I had a helper tool written, but modifying jigdo to use this
+    looked HARD)
+ 3. Patch mkisofs/genisoimage to write .jigdo and .template files alongside the
+    ISO image
+
+I completed the third of these options, and called it JTE (or Jigdo Template
+Export). The code worked fine, and ran in a very small fraction of the time
+taken to run genisoimage and jigdo separately. The output .jigdo and .template
+files worked correctly, i.e. jigdo-file and the wrapper script jigdo-mirror
+accept them and would generate an ISO image that exactly matches the original.
+
+Debian used that code for a number of years within genisoimage, but we've since
+switched over to using xorriso instead for our image building instead. It has a
+lot of useful features that we want compared to genisoimage, not least a
+friendly and engaged author in Thomas Scmitt!
+
+Thomas and I and George Danchev worked together to package up my JTE code into
+libjte such that xorriso could use it effectively. Xorriso has been capable of
+generating jigdo files since 2010.
+
+In late 2019, I took over maintenance of the jigdo upstream code and added
+support for a new (v2) jigdo data format, using SHA256 instead of MD5
+internally. See my jigdo page for more details about that. I have also updated
+the JTE codebase to support this new format, of course.
+
+As genisoimage is effectively dead at this point, I took the decision to not
+add the jigdo v2 support into the genisoimage codebase. If you need to generate
+jigdo v2 format, either use jigdo itself or xorriso if you'd like the
+performance benefit of the libjte integration.
+
+JTE includes a few tools:
+
+  • jigit-mkimage, a simple and very fast tool to reconstruct image files from
+    .jigdo and .template files. It doesn't have any logic to cope with
+    downloading missing files, but will list the missing files that are needed.
+    It is also much faster for people (like me!) who already have full local
+    mirrors.
+  • parallel-sums is a simple extra utility to generate checksums quickly and
+    efficiently, reading file data only once and calculating checksums using
+    multiple algorithms in parallel using threads.
+  • jigsum, jigsum-sha256 and rsyncsum are checksum tools which will output
+    checksums in jigdo's base64-like format rather than the normal hexadecimal
+    format. Useful for debugging jigdo issues.
+  • jigdump is a tool to dump the contents of a jigdo template or .iso.tmp
+    file. Useful for debugging jigdo issues.
+  • mkjigsnap is a utility to help with maintaining the "snapshots" that jigdo
+    needs if you're going to be keeping data around for users in the long term.
+    We use this on some Debian systems.
+
+Why the "jigit" name? The packages and source are named jigit to match the name
+of a long-dead wrapper script.
 
 ----------------------------------------------------------------------
 
-How to use JTE in genisoimage
+Download
+--------
 
-To use the jigdo creation code, specify the location of the output
-.jigdo and .template files alongside the ISO image. You can also
-specify the minimum size beneath which files will just be dropped into
-the binary template file data rather than listed as separate files to
-be found on the mirror, and exclude patterns to ignore certain files
-in the same way. And paths in the original filesystem can be mapped
-onto more global namespaces using the [Servers] section in the .jigdo
-file. For example:
+The jigit source package (and hence the various binary packages it builds) is
+included in the main Debian archive, so your best bet is to get binary packages
+from there. Check for the current version(s) using tracker.debian.org).
+
+Source and backported versions are in the download area [1] alongside
+the current ChangeLog. All the files for download are PGP-signed for
+safety. You can find my keys online if you need them [2].
+
+jigit is maintained in git [3].
+
+[1] https://www.einval.com/~steve/software/JTE/download/
+[2] https://www.einval.com/~steve/pgp/
+[3] https://git.einval.com/cgi-bin/gitweb.cgi?p=jigit.git.
+
+----------------------------------------------------------------------
+
+How to use JTE
+
+To use the jigdo creation code, specify the location of the output .jigdo and
+.template files alongside the ISO image. You can also specify the minimum size
+beneath which files will just be dropped into the binary template file data
+rather than listed as separate files to be found on the mirror, and exclude
+patterns to ignore certain files in the same way. And paths in the original
+filesystem can be mapped onto more global namespaces using the [Servers]
+section in the .jigdo file. For example:
 
 genisoimage -J -r -o /home/steve/test1.iso \
-            -jigdo-jigdo /home/steve/test1.jigdo \
-            -jigdo-template /home/steve/test1.template \
-            -jigdo-min-file-size 16384 \
-            -jigdo-ignore "README*" \
-                   -jigdo-force-md5 /pool/ \
-            -jigdo-map Debian=/mirror/debian \
-            -md5-list /home/steve/md5.list \
-            /mirror/jigdo-test
-
-If the -jigdo-* options are not used, the normal genisoimage execution
-path is not affected at all. The above invocation will create 3 output
-files (.iso, .jigdo and .template). Multiple -jigdo-ignore and
--jigdo-map options are accepted, for multiple ignore and map patterns.
-
-Use the -md5-list option to specify the location of a list of files
-and their md5sums in normal md5sum format. genisoimage will then compare
-the checksum of each file it is asked to write against the checksum of
-that file in the list. It will abort on any mismatches. The MD5 list
-file must list all the files that are expected to be found and listed
-in the output .jigdo file. The -jigdo-force-md5 option specifies a
-path where all files are expected to have an MD5 entry
-(e.g. /pool/). Then if any files do not have a match, they must have
-been corrupted and genisoimage will abort.
-
-More options have now been added in version 1.2 so that you can
-specify the location of boot files within the ISO image. Previously
-the four architectures alpha, hppa, mips and mipsel needed separate
-tools to make an ISO image bootable. This also made life very hard
-when trying to produce jigdo files.  Instead, I've folded boot support
-for those architectures into this patch so that genisoimage will do all
-the work:
-
-+-----------------------------------------------------------------------------+
-|Alpha                                                                        |
-|-----------------------------------------------------------------------------|
-|-alpha-boot     |Specify the location of the boot image (relative to the root|
-|<FILE>          |of the ISO image)                                           |
-|-----------------------------------------------------------------------------|
-|Hppa                                                                         |
-|-----------------------------------------------------------------------------|
-|-hppa-cmdline   |Specify the hppa boot command line. Separate elements with  |
-|<CMDLINE>       |commas or spaces.                                           |
-|----------------+------------------------------------------------------------|
-|-hppa-kernel-32 |Specify the location of the 32-bit boot image (relative to  |
-|<FILE>          |the root of the ISO image)                                  |
-|----------------+------------------------------------------------------------|
-|-hppa-kernel-64 |Specify the location of the 64-bit boot image (relative to  |
-|<FILE>          |the root of the ISO image)                                  |
-|----------------+------------------------------------------------------------|
-|-hppa-bootloader|Specify the location of the bootloader code (iplboot,       |
-|<FILE>          |relative to the root of the ISO image)                      |
-|----------------+------------------------------------------------------------|
-|-hppa-ramdisk   |Specify the location of the ramdisk (relative to the root of|
-|<FILE>          |the ISO image)                                              |
-|-----------------------------------------------------------------------------|
-|Mips                                                                         |
-|-----------------------------------------------------------------------------|
-|-mips-boot      |Specify the location of the boot image (relative to the root|
-|<FILE>          |of the ISO image)                                           |
-|-----------------------------------------------------------------------------|
-|Mipsel                                                                       |
-|Mipsel is awkward because we have to parse the ELF header of the boot loader |
-|and write some locations from it into the boot sector. Ick!                  |
-|-----------------------------------------------------------------------------|
-|-mipsel-boot    |Specify the location of the boot image (relative to the root|
-|<FILE>          |of the ISO image)                                           |
-+-----------------------------------------------------------------------------+
+        -jigdo-jigdo /home/steve/test1.jigdo \
+        -jigdo-template /home/steve/test1.template \
+        -jigdo-min-file-size 16384 \
+        -jigdo-ignore "README*" \
+        -jigdo-force-md5 "/pool/" \
+        -jigdo-map Debian=/mirror/debian \
+        -md5-list /home/steve/md5.list \
+        /mirror/jigdo-test
+
+If the -jigdo-* options are not used, the normal genisoimage execution path is
+not affected at all. The above invocation will create 3 output files (.iso,
+.jigdo and .template). Multiple -jigdo-ignore and -jigdo-map options are
+accepted, for multiple ignore and map patterns.
+
+Use the -md5-list option to specify the location of a list of files and their
+md5sums in normal md5sum format. genisoimage will then compare the checksum of
+each file it is asked to write against the checksum of that file in the list.
+It will abort on any mismatches. The MD5 list file must list all the files that
+are expected to be found and listed in the output .jigdo file. The
+-jigdo-force-md5 option specifies a path where all files are expected to have
+an MD5 entry (e.g. /pool/). Then if any files do not have a match, they must
+have been corrupted and genisoimage will abort.
+
+----------------------------------------------------------------------
+
+How JTE works
+
+I hooked all the places in genisoimage where it will normally write image data.
+All the normal data write calls (directory entries etc.) I simply copy through
+and build into the template file. Any file data entries are instead passed
+through with information about the original file. If that file is large enough
+(see -jigdo-min-file-size above), I grab the filename and the MD5 of the file's
+data. If that MD5, size and length match an entry in the md5-list, I can just
+write a file match record into the template file (and then the jigdo file)
+instead of the file data itself.
+
+----------------------------------------------------------------------
+
+How to use jigit-mkimage
+
+jigit-mkimage is a faster, more minimal version of "jigdo-file make-image",
+written in portable C. It takes a few options:
+
+┌─────────┬─────────────────────────────────────────────────────────────┐
+│-f <MD5   │Specify a file containing MD5sums for files we should attempt to   │
+│file>     │use when rebuilding the image                                      │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-j <jigdo │Specify the input jigdo file                                       │
+│file>     │                                                                   │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-t        │                                                                   │
+│<template │Specify the input template file                                    │
+│file>     │                                                                   │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-m <item= │Map <item> to <path> to find the files in the mirror               │
+│path>     │                                                                   │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-M        │Don't attempt to build the image; just verify that all the         │
+│<Missing  │components needed are available. If some are missing, list them in │
+│file>     │the specified file.                                                │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-v        │Make the output logging more verbose.                              │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-l <log   │Specify a logfile. If not specified, will log to stderr just like  │
+│file>     │genisoimage                                                        │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│          │Don't bother checking md5sums of the input files, or of the output │
+│-q        │image.                                                             │
+│          │WARNING: this may lead to corrupt images, but is much faster.      │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-s <start │Specify where to start in the image (in bytes). If not specified,  │
+│offset>   │will start at the beginning (offset 0). Added for iso-image.pl use │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│-e <end   │Specify where to end in the image (in bytes). If not specified,    │
+│offset>   │will run all the way to the end of the image. Added for            │
+│          │iso-image.pl use                                                   │
+├─────────┼─────────────────────────────────────────────────────────────┤
+│          │Don't attempt to reassemble the image; simply parse the image      │
+│-z        │descriptor in the template file and print the image size. Added for│
+│          │iso-image.pl use                                                   │
+└─────────┴─────────────────────────────────────────────────────────────┘
+
+Specifying a start or end offset implies -q - it's difficult to check MD5 sums
+if the full image is not generated!
+
+----------------------------------------------------------------------
+
+(Dead) experiments
+------------------
+
+I had extra plans for JTE that never really came to fruition due to a lack of
+time and energy... :-/ Check git history if you're interested.
+
+* iso-image.pl - on-the-fly rebuild of ISO images for HTTP
+
+iso-image.pl was a small perl wrapper script written to drive mkimage and turn
+it into a CGI. It would parse the incoming request (including byte-ranges) and
+call jigit-mkimage to actually generate the image pieces wanted.
+
+This code worked, but was always too slow for production use. Each CGI request
+needed to index into the ISO image independently, leading to lots and lots of
+overlapping calls to decompress the template data.
+
+* jigdoofus - a better way to do on-the-fly assembly
+
+I started on a new project, creating a FUSE-based filesystem that would rebuild
+ISOs on the fly. I decided to use a database backend and a caching system to
+solve the problem of the repetitive decompression that stopped iso-image.pl. I
+made some progress, but ran out of steam. Code is still in the "jigdoofus"
+branch in git in case anybody ever finds it useful.
+
+* jigit - a friendly wrapper for jigit-mkimage
+
+Similarly to the jigdo-lite script in the jigdo package, I wanted to provide a
+nicer user experience for easy downloading of Debian and Ubuntu CD images. It
+worked, but never really gained much traction. It needed much more effort to
+make things reliable for production use.
 
 ----------------------------------------------------------------------
 
-How it works
+External integration
+--------------------
+
+* debian-cd
+
+The debian-cd package in Debian is what we use to generate installer CDs and
+DVDs. It has supported JTE since 2005, and we still use it every day.
+
+* cdrkit/genisoimage
+
+genisoimage in Debian shipped with integrated JTE code for a long time, but is
+basically dead upstream. Not recommended for use any more.
+
+* xorriso
+
+xorriso uses libjte to generate jigdo and template files, and has worked this
+way since 2010.
+
+----------------------------------------------------------------------
+
+What's left to do?
+------------------
+
+ 1. Testing! :-) This is where you lot come in! Please play with this some more
+    and let me know if you have any problems, especially with data corruption.
+ 2. More documentation.
+
+
 
-I've hooked all the places in genisoimage where it will normally write image data.
-All the normal data write calls (directory entries etc.) I simply pass through
-and build into the template file. Any file data entries are passed through with
-information about the original file. If that file is large enough, I grab the
-filename and the MD5 of the file's data so I can just write a file match record
-into the template file (and then the jigdo file).
 
 ----------------------------------------------------------------------
 
-How fast is it?
+How to use JTE
+
+To use the jigdo creation code, specify the location of the output .jigdo and
+.template files alongside the ISO image. You can also specify the minimum size
+beneath which files will just be dropped into the binary template file data
+rather than listed as separate files to be found on the mirror, and exclude
+patterns to ignore certain files in the same way. And paths in the original
+filesystem can be mapped onto more global namespaces using the [Servers]
+section in the .jigdo file. For example:
+
+genisoimage -J -r -o /home/steve/test1.iso \
+        -jigdo-jigdo /home/steve/test1.jigdo \
+        -jigdo-template /home/steve/test1.template \
+        -jigdo-min-file-size 16384 \
+        -jigdo-ignore "README*" \
+        -jigdo-force-md5 "/pool/" \
+        -jigdo-map Debian=/mirror/debian \
+        -md5-list /home/steve/md5.list \
+        /mirror/jigdo-test
+
+If the -jigdo-* options are not used, the normal genisoimage execution path is
+not affected at all. The above invocation will create 3 output files (.iso,
+.jigdo and .template). Multiple -jigdo-ignore and -jigdo-map options are
+accepted, for multiple ignore and map patterns.
+
+Use the -md5-list option to specify the location of a list of files and their
+md5sums in normal md5sum format. genisoimage will then compare the checksum of
+each file it is asked to write against the checksum of that file in the list.
+It will abort on any mismatches. The MD5 list file must list all the files that
+are expected to be found and listed in the output .jigdo file. The
+-jigdo-force-md5 option specifies a path where all files are expected to have
+an MD5 entry (e.g. /pool/). Then if any files do not have a match, they must
+have been corrupted and genisoimage will abort.
 
-On my laptop (600MHz P3, slow laptop disk) I can make a template file in
-parallel with the ISO image from a typical 500MB data set in about 2 minutes.
-By simply not creating the ISO (-o /dev/null), this time halves again. The data
-set I'm using here is a copy of the woody i386 r2 update CD, as it's a handy
-image I had lying around.
+----------------------------------------------------------------------
 
-On my faster home server machine (1.7GHz Athlon, 512MB RAM, fast SCSI disks), I
-can produce a 7GB DVD iso image with the jigdo and template files in about 8
-minutes. A debian-cd run from start to finish to create DVD images takes about
-25 minutes per architecture.
+How JTE works
 
-Genisoimage is normally I/O-bound on this system, but when running the jigdo
-creation code it's now CPU bound - it's now running 2 MD5 checksums on each
-data block that it sees. To boost performance when creating images, running 2
-copies of debian-cd in parallel on a single system should parallelise nicely -
-ideally run the CD and DVD versions of each architecture together to get
-maximum benefit from the dentry and page cache.
+I hooked all the places in genisoimage where it will normally write image data.
+All the normal data write calls (directory entries etc.) I simply copy through
+and build into the template file. Any file data entries are instead passed
+through with information about the original file. If that file is large enough
+(see -jigdo-min-file-size above), I grab the filename and the MD5 of the file's
+data. If that MD5, size and length match an entry in the md5-list, I can just
+write a file match record into the template file (and then the jigdo file)
+instead of the file data itself.
 
 ----------------------------------------------------------------------
 
 How to use jigit-mkimage
 
-jigit-mkimage is a faster, local-only version of "jigdo-file
-make-image", again written in portable C. It takes a few options:
-
-+-----------------------------------------------------------------------------+
-|-f <MD5  |Specify a file containing MD5sums for files we should attempt to   |
-|file>    |use when rebuilding the image                                      |
-|---------+-------------------------------------------------------------------|
-|-j <jigdo|Specify the input jigdo file                                       |
-|file>    |                                                                   |
-|---------+-------------------------------------------------------------------|
-|-t       |                                                                   |
-|<template|Specify the input template file                                    |
-|file>    |                                                                   |
-|---------+-------------------------------------------------------------------|
-|-m <item=|Map <item> to <path> to find the files in the mirror               |
-|path>    |                                                                   |
-|---------+-------------------------------------------------------------------|
-|-M       |Don't attempt to build the image; just verify that all the         |
-|<Missing |components needed are available. If some are missing, list them in |
-|file>    |the specified file.                                                |
-|---------+-------------------------------------------------------------------|
-|-v       |Make the output logging more verbose.                              |
-|---------+-------------------------------------------------------------------|
-|-l <log  |Specify a logfile. If not specified, will log to stderr just like  |
-|file>    |genisoimage                                                        |
-|---------+-------------------------------------------------------------------|
-|         |Don't bother checking md5sums of the input files, or of the output |
-|-q       |image.                                                             |
-|         |WARNING: this may lead to corrupt images, but is much faster.      |
-|---------+-------------------------------------------------------------------|
-|-s <start|Specify where to start in the image (in bytes). If not specified,  |
-|offset>  |will start at the beginning (offset 0). Added for iso-image.pl use |
-|---------+-------------------------------------------------------------------|
-|-e <end  |Specify where to end in the image (in bytes). If not specified,    |
-|offset>  |will run all the way to the end of the image. Added for            |
-|         |iso-image.pl use                                                   |
-|---------+-------------------------------------------------------------------|
-|         |Don't attempt to reassemble the image; simply parse the image      |
-|-z       |descriptor in the template file and print the image size. Added for|
-|         |iso-image.pl use                                                   |
-+-----------------------------------------------------------------------------+
+jigit-mkimage is a faster, more minimal version of "jigdo-file make-image",
+written in portable C. It takes a few options:
+
+┌─────────┬───────────────────────────────────────────────────────────────────┐
+│-f <MD5  │Specify a file containing MD5sums for files we should attempt to   │
+│file>    │use when rebuilding the image                                      │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-j <jigdo│Specify the input jigdo file                                       │
+│file>    │                                                                   │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-t       │                                                                   │
+│<template│Specify the input template file                                    │
+│file>    │                                                                   │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-m <item=│Map <item> to <path> to find the files in the mirror               │
+│path>    │                                                                   │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-M       │Don't attempt to build the image; just verify that all the         │
+│<Missing │components needed are available. If some are missing, list them in │
+│file>    │the specified file.                                                │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-v       │Make the output logging more verbose.                              │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-l <log  │Specify a logfile. If not specified, will log to stderr just like  │
+│file>    │genisoimage                                                        │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│         │Don't bother checking md5sums of the input files, or of the output │
+│-q       │image.                                                             │
+│         │WARNING: this may lead to corrupt images, but is much faster.      │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-s <start│Specify where to start in the image (in bytes). If not specified,  │
+│offset>  │will start at the beginning (offset 0). Added for iso-image.pl use │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│-e <end  │Specify where to end in the image (in bytes). If not specified,    │
+│offset>  │will run all the way to the end of the image. Added for            │
+│         │iso-image.pl use                                                   │
+├─────────┼───────────────────────────────────────────────────────────────────┤
+│         │Don't attempt to reassemble the image; simply parse the image      │
+│-z       │descriptor in the template file and print the image size. Added for│
+│         │iso-image.pl use                                                   │
+└─────────┴───────────────────────────────────────────────────────────────────┘
 
 Specifying a start or end offset implies -q - it's difficult to check MD5 sums
 if the full image is not generated!
 
 ----------------------------------------------------------------------
 
-How to use iso-image.pl
+(Dead) experiments
 
-iso-image.pl is a small perl wrapper script written to drive
-jigit-mkimage and turn it into a CGI. It will parse the incoming
-request (including byte-ranges) and call jigit-mkimage to actually
-generate the image pieces wanted.
+I had extra plans for JTE that never really came to fruition due to a lack of
+time and energy... :-/ Check git history if you're interested.
 
-Configuration is simple: place iso-image.pl in a cgi-bin directory and set
-various paths in the script:
+iso-image.pl - on-the-fly rebuild of ISO images for HTTP
 
-  * The path to jigit-mkimage
-  * A log file location
-  * The path to the template and jigdo files
-  * Other options to jigit-mkimage (e.g. -q and match locations)
+iso-image.pl was a small perl wrapper script written to drive mkimage and turn
+it into a CGI. It would parse the incoming request (including byte-ranges) and
+call jigit-mkimage to actually generate the image pieces wanted.
 
-----------------------------------------------------------------------
+This code worked, but was always too slow for production use. Each CGI request
+needed to index into the ISO image independently, leading to lots and lots of
+overlapping calls to decompress the template data.
+
+jigdoofus - a better way to do on-the-fly assembly
 
-How to use jigit
+I started on a new project, creating a FUSE-based filesystem that would rebuild
+ISOs on the fly. I decided to use a database backend and a caching system to
+solve the problem of the repetitive decompression that stopped iso-image.pl. I
+made some progress, but ran out of steam. Code is still in the "jigdoofus"
+branch in git in case anybody ever finds it useful.
 
-Jigit is a small, user-friendly wrapper around jigit-mkimage to make
-life easier for end users to download or upgrade existing CDs and CD
-images. Configure it by editing /etc/jigit.conf or ~/.jigit.conf, then
-run jigit with just one command line option, the name of the
-distribution CD. Answer the questions it asks and it will do the rest.
+jigit - a friendly wrapper for jigit-mkimage
+
+Similarly to the jigdo-lite script in the jigdo package, I wanted to provide a
+nicer user experience for easy downloading of Debian and Ubuntu CD images. It
+worked, but never really gained much traction. It needed much more effort to
+make things reliable for production use.
 
 ----------------------------------------------------------------------
 
 External integration
 
-The current released version of debian-cd in etch supports JTE out of
-the box. Wodim ships with integrated JTE code too.
+debian-cd
+
+The debian-cd package in Debian is what we use to generate installer CDs and
+DVDs. It has supported JTE since 2005, and we still use it every day.
+
+cdrkit/genisoimage
+
+genisoimage in Debian shipped with integrated JTE code for a long time, but is
+basically dead upstream. Not recommended for use any more.
+
+xorriso
+
+xorriso uses libjte to generate jigdo and template files, and has worked this
+way since 2010.
 
 ----------------------------------------------------------------------
 
@@ -275,4 +419,4 @@ What's left to do?
  1. Testing! :-) This is where you lot come in! Please play with this some more
     and let me know if you have any problems, especially with data corruption.
  2. More documentation.
- 3. Support for non-local mirrors in jigit-mkimage.
+
index a793b66..3651777 100644 (file)
@@ -1,3 +1,30 @@
+libjte-2.0.0 (20th November 2019)
+============
+
+* New major version with support for using SHA256 checksums instead of
+  MD5 in the jigdo format. This is a breaking change - old clients
+  will not be able to work with the new format and will bail
+  out. Default is to still generate the old v1.1 format for
+  compatibility for now. Call libjte_set_checksum_algorithm() to make
+  an explicit choice at the beginning of the jigdo setup.
+
+* Several old MD5-specific functions in the API now marked deprecated:
+  + libjte_set_md5_path()
+  + libjte_add_md5_demand()
+  + libjte_decide_file_jigdo()
+  + libjte_write_match_record()
+    
+*  Added new functions needed to allow for more checksum choice:
+  + libjte_set_checksum_algorithm()
+  + libjte_set_checksum_path()
+  + libjte_add_checksum_demand()
+  + libjte_decide_file_jigdo2()
+  + libjte_write_match_record2()
+    
+* The "Simplified" API is unchanged for existing users *except* when
+  choosing to use sha256 instead of md5 - it just needs a call to
+  libjte_set_checksum_algorithm() at startup to make that choice.
+
 libjte-0.1.1 (not released yet)
 ===============================================================================
 * Thomas: porting libjte to Solaris 9: avoiding <stdint.h> if not available,