Version 1.19
[jigit.git] / README
1 README for JTE 1.19
2
3 Steve McIntyre <steve@einval.com>
4 16 June 2011
5
6 License - GPL v2. See the file COPYING for more details.
7
8 JTE - Jigdo Template Export
9 ===========================
10
11 Introduction
12
13 Jigdo is a useful tool to help in the distribution of large files like CD and
14 DVD images. See Richard Atterer's site for more details. Debian CDs and DVD ISO
15 images are published on the web in jigdo format to allow end users to download
16 them more efficiently.
17
18 Jigdo is generic and powerful - it can be used for any large files that are
19 made up of smaller files. However, to be this generic is costly. Creating jigdo
20 files from ISO images is quite inefficient - to work out which files are
21 included in the ISO image, jigdo has to calculate and compare checksums of
22 every possible file and every extent in the image. Essentially it has to
23 brute-force the image. On my home system, it can take several hours to do this
24 for a 4.5GB DVD image.
25
26 There are a few ways to improve this that I can see:
27
28  1. Modify jigdo so it knows about the internals of ISO images and can
29     efficiently scan them (bad, not very generic for jigdo)
30  2. Write a helper tool to dump extra information for jigdo to use alongside
31     the ISO image (helper tool written, but modifying jigdo to use this looks
32     HARD)
33  3. Patch ISO creation tools to write .jigdo and .template files
34     alongside the ISO image
35
36 I've now done the third of these, and called the code JTE (or Jigdo
37 Template Export). The code works fine, and runs in a very small
38 fraction of the time taken to run genisoimage and jigdo
39 separately. The output .jigdo and .template files work correctly,
40 i.e. jigdo-file and the wrapper script jigdo-mirror accept them and
41 will generate an ISO image that exactly matches the original.
42
43 However, cdrkit / genisoimage is now deprecated in my opinion. The
44 nice people working on xorriso (George Danchev and Thomas Schmitt)
45 have helped a huge amount by cleaning up some of my code and wrapping
46 it properly in a shared library. The code is now included here as
47 libjte, and re-licensed slightly as LGPL v2.1 or later.
48
49 Tools
50 =====
51
52 JTE also comes with some extra tools:
53
54 jigit-mkimage, a simple and very fast tool to reconstruct image files
55 from .jigdo and .template files. It doesn't have any logic to cope
56 with downloading missing files, but will list the missing files that
57 are needed. It is also much faster for people (like me!) who already
58 have full local mirrors.
59
60 iso-image.pl is a CGI script to wrap around jigit-mkimage if you'd
61 like to be able to offer images for HTTP download without using up
62 multiple gigabytes of disk space. And for added network efficiency the
63 perl CGI also supports HTTP v1.1 byte ranges so clients can resume
64 aborted downloads.
65
66 jigit is a first attempt at a user-friendly wrapper for jigit-mkimage
67 on a user's machine.
68
69 ----------------------------------------------------------------------
70
71 How to use JTE in genisoimage
72
73 To use the jigdo creation code, specify the location of the output
74 .jigdo and .template files alongside the ISO image. You can also
75 specify the minimum size beneath which files will just be dropped into
76 the binary template file data rather than listed as separate files to
77 be found on the mirror, and exclude patterns to ignore certain files
78 in the same way. And paths in the original filesystem can be mapped
79 onto more global namespaces using the [Servers] section in the .jigdo
80 file. For example:
81
82 genisoimage -J -r -o /home/steve/test1.iso \
83             -jigdo-jigdo /home/steve/test1.jigdo \
84             -jigdo-template /home/steve/test1.template \
85             -jigdo-min-file-size 16384 \
86             -jigdo-ignore "README*" \
87                     -jigdo-force-md5 /pool/ \
88             -jigdo-map Debian=/mirror/debian \
89             -md5-list /home/steve/md5.list \
90             /mirror/jigdo-test
91
92 If the -jigdo-* options are not used, the normal genisoimage execution
93 path is not affected at all. The above invocation will create 3 output
94 files (.iso, .jigdo and .template). Multiple -jigdo-ignore and
95 -jigdo-map options are accepted, for multiple ignore and map patterns.
96
97 Use the -md5-list option to specify the location of a list of files
98 and their md5sums in normal md5sum format. genisoimage will then compare
99 the checksum of each file it is asked to write against the checksum of
100 that file in the list. It will abort on any mismatches. The MD5 list
101 file must list all the files that are expected to be found and listed
102 in the output .jigdo file. The -jigdo-force-md5 option specifies a
103 path where all files are expected to have an MD5 entry
104 (e.g. /pool/). Then if any files do not have a match, they must have
105 been corrupted and genisoimage will abort.
106
107 More options have now been added in version 1.2 so that you can
108 specify the location of boot files within the ISO image. Previously
109 the four architectures alpha, hppa, mips and mipsel needed separate
110 tools to make an ISO image bootable. This also made life very hard
111 when trying to produce jigdo files.  Instead, I've folded boot support
112 for those architectures into this patch so that genisoimage will do all
113 the work:
114
115 +-----------------------------------------------------------------------------+
116 |Alpha                                                                        |
117 |-----------------------------------------------------------------------------|
118 |-alpha-boot     |Specify the location of the boot image (relative to the root|
119 |<FILE>          |of the ISO image)                                           |
120 |-----------------------------------------------------------------------------|
121 |Hppa                                                                         |
122 |-----------------------------------------------------------------------------|
123 |-hppa-cmdline   |Specify the hppa boot command line. Separate elements with  |
124 |<CMDLINE>       |commas or spaces.                                           |
125 |----------------+------------------------------------------------------------|
126 |-hppa-kernel-32 |Specify the location of the 32-bit boot image (relative to  |
127 |<FILE>          |the root of the ISO image)                                  |
128 |----------------+------------------------------------------------------------|
129 |-hppa-kernel-64 |Specify the location of the 64-bit boot image (relative to  |
130 |<FILE>          |the root of the ISO image)                                  |
131 |----------------+------------------------------------------------------------|
132 |-hppa-bootloader|Specify the location of the bootloader code (iplboot,       |
133 |<FILE>          |relative to the root of the ISO image)                      |
134 |----------------+------------------------------------------------------------|
135 |-hppa-ramdisk   |Specify the location of the ramdisk (relative to the root of|
136 |<FILE>          |the ISO image)                                              |
137 |-----------------------------------------------------------------------------|
138 |Mips                                                                         |
139 |-----------------------------------------------------------------------------|
140 |-mips-boot      |Specify the location of the boot image (relative to the root|
141 |<FILE>          |of the ISO image)                                           |
142 |-----------------------------------------------------------------------------|
143 |Mipsel                                                                       |
144 |Mipsel is awkward because we have to parse the ELF header of the boot loader |
145 |and write some locations from it into the boot sector. Ick!                  |
146 |-----------------------------------------------------------------------------|
147 |-mipsel-boot    |Specify the location of the boot image (relative to the root|
148 |<FILE>          |of the ISO image)                                           |
149 +-----------------------------------------------------------------------------+
150
151 ----------------------------------------------------------------------
152
153 How it works
154
155 I've hooked all the places in genisoimage where it will normally write image data.
156 All the normal data write calls (directory entries etc.) I simply pass through
157 and build into the template file. Any file data entries are passed through with
158 information about the original file. If that file is large enough, I grab the
159 filename and the MD5 of the file's data so I can just write a file match record
160 into the template file (and then the jigdo file).
161
162 ----------------------------------------------------------------------
163
164 How fast is it?
165
166 On my laptop (600MHz P3, slow laptop disk) I can make a template file in
167 parallel with the ISO image from a typical 500MB data set in about 2 minutes.
168 By simply not creating the ISO (-o /dev/null), this time halves again. The data
169 set I'm using here is a copy of the woody i386 r2 update CD, as it's a handy
170 image I had lying around.
171
172 On my faster home server machine (1.7GHz Athlon, 512MB RAM, fast SCSI disks), I
173 can produce a 7GB DVD iso image with the jigdo and template files in about 8
174 minutes. A debian-cd run from start to finish to create DVD images takes about
175 25 minutes per architecture.
176
177 Genisoimage is normally I/O-bound on this system, but when running the jigdo
178 creation code it's now CPU bound - it's now running 2 MD5 checksums on each
179 data block that it sees. To boost performance when creating images, running 2
180 copies of debian-cd in parallel on a single system should parallelise nicely -
181 ideally run the CD and DVD versions of each architecture together to get
182 maximum benefit from the dentry and page cache.
183
184 ----------------------------------------------------------------------
185
186 How to use jigit-mkimage
187
188 jigit-mkimage is a faster, local-only version of "jigdo-file
189 make-image", again written in portable C. It takes a few options:
190
191 +-----------------------------------------------------------------------------+
192 |-f <MD5  |Specify a file containing MD5sums for files we should attempt to   |
193 |file>    |use when rebuilding the image                                      |
194 |---------+-------------------------------------------------------------------|
195 |-j <jigdo|Specify the input jigdo file                                       |
196 |file>    |                                                                   |
197 |---------+-------------------------------------------------------------------|
198 |-t       |                                                                   |
199 |<template|Specify the input template file                                    |
200 |file>    |                                                                   |
201 |---------+-------------------------------------------------------------------|
202 |-m <item=|Map <item> to <path> to find the files in the mirror               |
203 |path>    |                                                                   |
204 |---------+-------------------------------------------------------------------|
205 |-M       |Don't attempt to build the image; just verify that all the         |
206 |<Missing |components needed are available. If some are missing, list them in |
207 |file>    |the specified file.                                                |
208 |---------+-------------------------------------------------------------------|
209 |-v       |Make the output logging more verbose.                              |
210 |---------+-------------------------------------------------------------------|
211 |-l <log  |Specify a logfile. If not specified, will log to stderr just like  |
212 |file>    |genisoimage                                                        |
213 |---------+-------------------------------------------------------------------|
214 |         |Don't bother checking md5sums of the input files, or of the output |
215 |-q       |image.                                                             |
216 |         |WARNING: this may lead to corrupt images, but is much faster.      |
217 |---------+-------------------------------------------------------------------|
218 |-s <start|Specify where to start in the image (in bytes). If not specified,  |
219 |offset>  |will start at the beginning (offset 0). Added for iso-image.pl use |
220 |---------+-------------------------------------------------------------------|
221 |-e <end  |Specify where to end in the image (in bytes). If not specified,    |
222 |offset>  |will run all the way to the end of the image. Added for            |
223 |         |iso-image.pl use                                                   |
224 |---------+-------------------------------------------------------------------|
225 |         |Don't attempt to reassemble the image; simply parse the image      |
226 |-z       |descriptor in the template file and print the image size. Added for|
227 |         |iso-image.pl use                                                   |
228 +-----------------------------------------------------------------------------+
229
230 Specifying a start or end offset implies -q - it's difficult to check MD5 sums
231 if the full image is not generated!
232
233 ----------------------------------------------------------------------
234
235 How to use iso-image.pl
236
237 iso-image.pl is a small perl wrapper script written to drive
238 jigit-mkimage and turn it into a CGI. It will parse the incoming
239 request (including byte-ranges) and call jigit-mkimage to actually
240 generate the image pieces wanted.
241
242 Configuration is simple: place iso-image.pl in a cgi-bin directory and set
243 various paths in the script:
244
245   * The path to jigit-mkimage
246   * A log file location
247   * The path to the template and jigdo files
248   * Other options to jigit-mkimage (e.g. -q and match locations)
249
250 ----------------------------------------------------------------------
251
252 How to use jigit
253
254 Jigit is a small, user-friendly wrapper around jigit-mkimage to make
255 life easier for end users to download or upgrade existing CDs and CD
256 images. Configure it by editing /etc/jigit.conf or ~/.jigit.conf, then
257 run jigit with just one command line option, the name of the
258 distribution CD. Answer the questions it asks and it will do the rest.
259
260 ----------------------------------------------------------------------
261
262 External integration
263
264 The current released version of debian-cd in etch supports JTE out of
265 the box. Wodim ships with integrated JTE code too.
266
267 ----------------------------------------------------------------------
268
269 What's left to do?
270
271  1. Testing! :-) This is where you lot come in! Please play with this some more
272     and let me know if you have any problems, especially with data corruption.
273  2. More documentation.
274  3. Support for non-local mirrors in jigit-mkimage.