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