Tweaked the -exclude option to reduce template file sizes
[jigit.git] / README
1 README for JTE 1.8
2
3 Steve McIntyre <steve@einval.com>
4 27 Aug 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 mkimage, a simple and very fast tool
40 to reconstruct image files from .jigdo and .template files. It's not meant to
41 compete with the normal jigdo-file program. It doesn't have any logic to cope
42 with downloading missing files, for example. But it is much faster for people
43 (like me!) who already have full local mirrors.
44
45 There's now also a perl CGI script iso-image.pl to wrap around mkimage if you'd
46 like to be able to offer images for HTTP download without using up multiple
47 gigabytes of disk space. And for added network efficiency the perl CGI also
48 supports HTTP v1.1 byte ranges so clients can resume aborted downloads.
49
50 The addition of these two extra tools means that I'm now distributing JTE as a
51 tarball rather than just a mkisofs patch; the patch is inside the tarball too.
52
53 ----------------------------------------------------------------------
54
55 How to use JTE
56
57 To use the jigdo creation code, specify the location of the output
58 .jigdo and .template files alongside the ISO image. You can also
59 specify the minimum size beneath which files will just be dropped into
60 the binary template file data rather than listed as separate files to
61 be found on the mirror, and exclude patterns to ignore certain files
62 in the same way. And paths in the original filesystem can be mapped
63 onto more global namespaces using the [Servers] section in the .jigdo
64 file. For example:
65
66 mkisofs -J -r -o /home/steve/test1.iso \
67         -jigdo-jigdo /home/steve/test1.jigdo \
68         -jigdo-template /home/steve/test1.template \
69         -jigdo-min-file-size 16384 \
70         -jigdo-ignore "README*" \
71         -jigdo-map Debian=/mirror/debian \
72         -md5-list /home/steve/md5.list \
73         /mirror/jigdo-test
74
75 If the -jigdo-* options are not used, the normal mkisofs execution
76 path is not affected at all. The above invocation will create 3 output
77 files (.iso, .jigdo and .template). Multiple -jigdo-ignore and
78 -jigdo-map options are accepted, for multiple ignore and map patterns.
79
80 Use the -md5-list option to specify the location of a list of files
81 and their md5sums in normal md5sum format. mkisofs will then compare
82 the checksum of each file it is asked to write against the checksum of
83 that file in the list. It will abort on any mismatches.
84
85 More options have now been added in version 1.2 so that you can
86 specify the location of boot files within the ISO image. Previously
87 the four architectures alpha, hppa, mips and mipsel needed separate
88 tools to make an ISO image bootable. This also made life very hard
89 when trying to produce jigdo files.  Instead, I've folded boot support
90 for those architectures into this patch so that mkisofs will do all
91 the work:
92
93 +-----------------------------------------------------------------------------+
94 |Alpha                                                                        |
95 |-----------------------------------------------------------------------------|
96 |-alpha-boot     |Specify the location of the boot image (relative to the root|
97 |<FILE>          |of the ISO image)                                           |
98 |-----------------------------------------------------------------------------|
99 |Hppa                                                                         |
100 |-----------------------------------------------------------------------------|
101 |-hppa-cmdline   |Specify the hppa boot command line. Separate elements with  |
102 |<CMDLINE>       |commas or spaces.                                           |
103 |----------------+------------------------------------------------------------|
104 |-hppa-kernel-32 |Specify the location of the 32-bit boot image (relative to  |
105 |<FILE>          |the root of the ISO image)                                  |
106 |----------------+------------------------------------------------------------|
107 |-hppa-kernel-64 |Specify the location of the 64-bit boot image (relative to  |
108 |<FILE>          |the root of the ISO image)                                  |
109 |----------------+------------------------------------------------------------|
110 |-hppa-bootloader|Specify the location of the bootloader code (iplboot,       |
111 |<FILE>          |relative to the root of the ISO image)                      |
112 |----------------+------------------------------------------------------------|
113 |-hppa-ramdisk   |Specify the location of the ramdisk (relative to the root of|
114 |<FILE>          |the ISO image)                                              |
115 |-----------------------------------------------------------------------------|
116 |Mips                                                                         |
117 |-----------------------------------------------------------------------------|
118 |-mips-boot      |Specify the location of the boot image (relative to the root|
119 |<FILE>          |of the ISO image)                                           |
120 |-----------------------------------------------------------------------------|
121 |Mipsel                                                                       |
122 |Mipsel is awkward because we have to parse the ELF header of the boot loader |
123 |and write some locations from it into the boot sector. Ick!                  |
124 |-----------------------------------------------------------------------------|
125 |-mipsel-boot    |Specify the location of the boot image (relative to the root|
126 |<FILE>          |of the ISO image)                                           |
127 +-----------------------------------------------------------------------------+
128
129 ----------------------------------------------------------------------
130
131 How it works
132
133 I've hooked all the places in mkisofs where it will normally write image data.
134 All the normal data write calls (directory entries etc.) I simply pass through
135 and build into the template file. Any file data entries are passed through with
136 information about the original file. If that file is large enough, I grab the
137 filename and the MD5 of the file's data so I can just write a file match record
138 into the template file (and then the jigdo file).
139
140 ----------------------------------------------------------------------
141
142 How fast is it?
143
144 On my laptop (600MHz P3, slow laptop disk) I can make a template file in
145 parallel with the ISO image from a typical 500MB data set in about 2 minutes.
146 By simply not creating the ISO (-o /dev/null), this time halves again. The data
147 set I'm using here is a copy of the woody i386 r2 update CD, as it's a handy
148 image I had lying around.
149
150 On my faster home server machine (1.7GHz Athlon, 512MB RAM, fast SCSI disks), I
151 can produce a 7GB DVD iso image with the jigdo and template files in about 8
152 minutes. A debian-cd run from start to finish to create DVD images takes about
153 25 minutes per architecture.
154
155 Mkisofs is normally I/O-bound on this system, but when running the jigdo
156 creation code it's now CPU bound - it's now running 2 MD5 checksums on each
157 data block that it sees. To boost performance when creating images, running 2
158 copies of debian-cd in parallel on a single system should parallelise nicely -
159 ideally run the CD and DVD versions of each architecture together to get
160 maximum benefit from the dentry and page cache.
161
162 ----------------------------------------------------------------------
163
164 How to use mkimage
165
166 mkimage is a faster, local-only version of "jigdo-file make-image", again
167 written in portable C. It takes a few options:
168
169 +-----------------------------------------------------------------------------+
170 |-j <jigdo|Specify the input jigdo file                                       |
171 |file>    |                                                                   |
172 |---------+-------------------------------------------------------------------|
173 |-t       |                                                                   |
174 |<template|Specify the input template file                                    |
175 |file>    |                                                                   |
176 |---------+-------------------------------------------------------------------|
177 |-m <item=|Map <item> to <path> to find the files in the mirror               |
178 |path>    |                                                                   |
179 |---------+-------------------------------------------------------------------|
180 |-l <log  |Specify a logfile. If not specified, will log to stderr just like  |
181 |file>    |mkisofs                                                            |
182 |---------+-------------------------------------------------------------------|
183 |         |Don't bother checking md5sums of the input files, or of the output |
184 |-q       |image.                                                             |
185 |         |WARNING: this may lead to corrupt images, but is much faster       |
186 |---------+-------------------------------------------------------------------|
187 |-s <start|Specify where to start in the image (in bytes). If not specified,  |
188 |offset>  |will start at the beginning (offset 0). Added for iso-image.pl use |
189 |---------+-------------------------------------------------------------------|
190 |-e <end  |Specify where to end in the image (in bytes). If not specified,    |
191 |offset>  |will run all the way to the end of the image. Added for            |
192 |         |iso-image.pl use                                                   |
193 |---------+-------------------------------------------------------------------|
194 |         |Don't attempt to reassemble the image; simply parse the image      |
195 |-z       |descriptor in the template file and print the image size. Added for|
196 |         |iso-image.pl use                                                   |
197 +-----------------------------------------------------------------------------+
198
199 Specifying a start or end offset implies -q - it's difficult to check MD5 sums
200 if the full image is not generated!
201
202 ----------------------------------------------------------------------
203
204 How to use iso-image.pl
205
206 iso-image.pl is a small perl wrapper script written to drive mkimage and turn
207 it into a CGI. It will parse the incoming request (including byte-ranges) and
208 call mkimage to actually generate the image pieces wanted.
209
210 Configuration is simple: place iso-image.pl in a cgi-bin directory and set
211 various paths in the script:
212
213   * The path to mkimage
214   * A log file location
215   * The path to the template and jigdo files
216   * Other options to mkimage (e.g. -q and match locations)
217
218 ----------------------------------------------------------------------
219
220 Debian-cd integration
221
222 I've branched debian-cd in CVS to add JTE support - use the
223 jte_support branch. There have been some more changes in HEAD since
224 that point, so I also have a more recent diff available - see
225 debian-cd.20040818.diff.gz. Let me know if you have any problems...
226
227 ----------------------------------------------------------------------
228
229 What's left to do?
230
231  1. Testing! :-) This is where you lot come in! Please play with this some more
232     and let me know if you have any problems, especially with data corruption.
233  2. More documentation.
234  3. Push patches upstream. This may take a while...
235
236 I hope people find this useful - at the moment I shudder at the thought of
237 releasing sarge (10+ CDs, netinst, business card, 2 DVDs per arch) without
238 making this kind of change. It'll take a week to generate the release images
239 otherwise...
240