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