4369eed7923fb58a81c51ec7713fc2ed191c6227
[jigdo.git] / doc / jigdo-file.1
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document. This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "JIGDO-FILE" "1" "20 June 2004" "" ""
7
8 .SH NAME
9 jigdo-file \- Prepare files for Jigsaw Download (distribution of huge files, e.g. CD images).
10 .SH SYNOPSIS
11
12 \fBjigdo-file\fR \fB \fI COMMAND\fB
13 \fR [ \fB--image=\fIcdrom.iso\fB\fR ] [ \fB--jigdo=\fIcdrom.jigdo\fB\fR ] [ \fB--template=\fIcdrom.template\fB\fR ] [ \fB--force\fR ] [ \fBMORE OPTIONS\fR ] [ \fB\fIFILES\fB\fR\fI ...\fR | \fB--files-from=\fIf\fB\fR ]
14  \fBCommon COMMANDs: make-template,
15 make-image, verify\fR
16
17 .SH "DESCRIPTION"
18 .PP
19 Jigsaw Download, or short jigdo, is a scheme developed
20 primarily to make it easy to distribute huge filesystem images
21 (e.g. CD (ISO9660) or DVD (UDF) images) over the internet, but it
22 could also be used for other data which is awkward to handle due
23 to its size, like audio/video files or large software
24 packages.
25 .PP
26 jigdo tries to ensure that the large file (always called
27 \fIimage\fR from now on) is downloaded in small
28 parts which can be stored on different servers. People who want to
29 download the image do so by telling the \fBjigdo\fR(1) \fB(NOT IMPLEMENTED YET)\fR
30 download tool to process one `\fI.jigdo\fR' file;
31 using it, \fBjigdo\fR downloads the parts and
32 reassembles the image. \fBjigdo-file\fR is used to
33 prepare the files for download.
34 .PP
35 What makes jigdo special is that the parts that are used to
36 reconstruct the image can have any size and content - they only
37 need to be contained in a contiguous region anywhere in the
38 image.
39 .PP
40 For example, if you wish to distribute an ISO9660 image
41 which contains a snapshot of an FTP server, you can instruct
42 \fBjigdo-file\fR to prepare the download data in such
43 a way that when people use \fBjigdo\fR to download
44 the image, \fBjigdo\fR actually fetches the
45 individual files from the FTP server and assembles them into an
46 exact copy of your image - during the download! (If the image is
47 not a filesystem dump, you can use
48 \fBsplit\fR(1) to create the small parts that the image will be
49 reassembled from.)
50 .PP
51 You are completely free to choose where the individual parts
52 of the image are stored: They may be in entirely different
53 directories on different servers (e.g. because of
54 storage/bandwidth constraints), but this is invisible to the
55 people downloading your image. The information about available
56 servers only needs to be added to the
57 `\fI.jigdo\fR' file by you before distributing
58 it.
59 .PP
60 The `DETAILS' section below contains technical details on
61 how jigdo works. The `EXAMPLES' section lists a number of common
62 scenarios and may help you to get an idea of what jigdo is useful
63 for.
64 .SH "OPTIONS"
65 .PP
66 Many options are specific to a particular
67 \fICOMMAND\fR; the ones below are general or
68 used by several commands. Further options are listed below with
69 the individual commands. All options are silently ignored if they
70 are not applicable to the current command. For any
71 \fIBYTES\fR parameters to options, you can
72 append one of the letters `k', `M' or `G' to the amount you
73 specify, to indicate kilobytes, megabytes or gigabytes.
74 .TP
75 \fB-h --help\fR
76 Output short summary of commands and options.
77 .TP
78 \fB-H --help-all\fR
79 Output complete summary of commands and options.
80 .TP
81 \fB-v --version\fR
82 Output program version.
83 .TP
84 \fB-i --image=\fIcdrom.iso\fB\fR
85 Specify location of the file containing the image. The
86 image is the large file that you want to distribute.
87 .TP
88 \fB-j --jigdo=\fIcdrom.jigdo\fB\fR
89 Specify location of the Jigsaw Download description
90 file. The jigdo file is a human-readable file generated by
91 \fBjigdo-file\fR, to which you add information
92 about all the servers you are going to upload the files to.
93 \fBjigdo\fR will download this file as the
94 first step of retrieving the image.
95 .TP
96 \fB-t --template=\fIcdrom.template\fB\fR
97 Specify location of the image `template' file. The
98 template file is a binary file generated by
99 \fBjigdo-file\fR, it contains information on
100 how to reassemble the image and also (in compressed form)
101 all the data from the image which was not found in any of
102 the parts.
103
104 Depending on the command, each of these three files is
105 used sometimes for input, sometimes for output. If the file
106 is to be used for output for a particular command and the
107 output file already exists, \fBjigdo-file\fR
108 exits with an error, unless \fB--force\fR is
109 present.
110
111 In most cases, you will only need to specify one out
112 of \fB-i\fR \fB-j\fR
113 \fB-t\fR, because any missing filenames will be
114 deduced from the one you specify. This is done by first
115 stripping any extension from the supplied name and then
116 appending nothing (if deducing \fB--image\fR),
117 `\fI.jigdo\fR' or
118 `\fI.template\fR'.
119 .TP
120 \fB-r --report=default|noprogress|quiet|grep\fR
121 Control how verbose the program is, and what format
122 the output has: \fBnoprogress\fR is the same as
123 \fBdefault\fR except that no `x%
124 done' progress messages are printed.
125 \fBquiet\fR restricts the output to what is
126 absolutely necessary, mostly error messages.
127 \fBgrep\fR is only different from
128 \fBdefault\fR for the
129 \fBmake-template\fR command: It enables output
130 in a simple `\fI<offset>
131 <file>\fR' format which is useful when
132 searching for binary files in other binary files.
133 .TP
134 \fB-f --force\fR
135 Overwrite existent output files without
136 complaining.
137 .TP
138 \fB--no-force\fR
139 \fBThis is the default.\fR Refuse to
140 overwrite existent output files.
141 .TP
142 \fB-c --cache=\fIjigdo-cache.db\fB\fR
143 \fBjigdo-file\fR usually needs to read
144 the entire contents of all the
145 \fIFILES\fR you specify. If you use it
146 repeatedly (e.g. because you make a new CD image available
147 daily), caching the file information will increase the
148 program's speed significantly. The cache file is
149 automatically created if it is not yet present. Data is
150 usually both read from and written to it.
151 .TP
152 \fB--no-cache\fR
153 \fBThis is the default.\fR Do not use a
154 cache.
155 .TP
156 \fB--cache-expiry=\fISECONDS\fB\fR
157 Set maximum age of cache entries. Any entries older
158 than this will be removed from the cache. The default is 30
159 days. You can append one of the letters `h', `d', `w', `m',
160 `y' to denote hours, days, weeks, months or years,
161 respectively. A value of `0' or `off' disables expiry, so
162 that all entries will stay in the cache forever. See the
163 section `CACHE FILES' below for more information.
164 .TP
165 \fB--readbuffer=\fIBYTES\fB\fR
166 Set size of internal buffers. The default is 128k - if
167 you have a fast disc, increasing this value may make
168 \fBjigdo-file\fR faster, but in general,
169 changing it is not necessary.
170 .TP
171 \fB--md5-block-size=\fIBYTES\fB\fR
172 \fBUninteresting internal parameter.\fR
173 Set size of blocks into which files are subdivided. The
174 default is 128k. If you change it, any cache file will have
175 to be regenerated. Internally, \fBjigdo-file\fR
176 may choose to use a slightly larger or smaller value.
177 .TP
178 \fB-T --files-from=\fIfile\fB\fR
179 Read file and directory names from the specified file.
180 If \fIfile\fR is `-', read names from
181 standard input. Each line in the file is taken as a name, so
182 the names may contain spaces, but not newline characters. An
183 empty line causes \fBjigdo-file\fR to stop
184 reading from the file.
185
186 \fBfind\fR(1) is a powerful tool for generating file
187 lists, but make sure to use `\fBfind -type
188 f\fR' if possible - otherwise, if you instruct
189 \fBfind\fR to output both a filename and a
190 symlink to that filename, \fBjigdo-file\fR will
191 read the file contents twice.
192 .TP
193 \fB--hex\fR
194 Output checksums in hexadecimal instead of Base64-like
195 format. This should not be used with the
196 \fBmake-template\fR command, because the
197 resulting `\fI.jigdo\fR' file violates the
198 `\fI.jigdo\fR' file format. Its intended use
199 is to make \fBjigdo-file\fR more interoperable
200 with other Unix shell utilities like \fBmd5sum\fR(1).
201 .TP
202 \fB--no-hex\fR
203 \fBThis is the default.\fR Use jigdo's
204 own Base64-like encoding of checksums.
205 .TP
206 \fB--debug[=help|=all|=\fIUNIT,~UNIT...\fB ]\fR
207 Switch on or off debugging output. Just `--debug' is
208 equivalent to `--debug=all'. The argument is a
209 comma-separated list of unit names for which debugging
210 output is to be enabled, or disabled if the name is preceded
211 by `~'. The special name `all' means all units. By default,
212 debugging output is switched off except for the units
213 `assert' and `general'. The exact list of available units
214 for which debugging can be switched on depends on whether
215 jigdo was compiled with debugging support - the list can be
216 printed with `--debug=help'.
217 .TP
218 \fB\fIFILES\fB\fR
219 Names of files or directories to use as input. These
220 are the parts that are contained in the image. In case one
221 of the names is a directory, the program recursively scans
222 the directory and adds all files contained in it. While
223 doing this, it follows symbolic links, but avoids symlink
224 loops.
225
226 If one of the filenames starts with the character `-',
227 you must precede the list of files with `--'. A value of `-'
228 has \fBno\fR special meaning in this list, it
229 stands for a file whose name is a single hyphen.
230 .SH "COMMANDS"
231 .PP
232 The command name is the first non-option argument passed to
233 \fBjigdo-file\fR. Most commands have short
234 abbreviations as well as long names. \fBThe short command
235 names should not be used in scripts - there may be incompatible
236 changes to them in the future!\fR
237 .SS "MAKE-TEMPLATE, MT"
238 .PP
239 Reads \fIimage\fR and
240 \fIFILES\fR, creates
241 `\fI.jigdo\fR' and
242 `\fI.template\fR'. This is the main functionality
243 of \fBjigdo-file\fR.
244 .PP
245 It is possible to specify both \fB--image=-\fR
246 and \fB--files-from=-\fR. In this case, first the
247 list of files is read from standard input until an empty line is
248 encountered. Everything following it is assumed to be the image
249 data. This can be useful if you use \fBmkisofs\fR(1) or similar programs that can output the complete
250 image on their standard output, because there is no need to
251 store the image on disc temporarily.
252 .PP
253 If a \fIFILES\fR argument contains
254 the characters `//' (Unix) or
255 `\\.\\' (Windows), this has special meaning. In
256 the final jigdo file that users will download, each of the parts
257 is referenced in the `[Parts]' section with a
258 URI of the form `Label:some/filename'. (See `FORMAT OF .JIGDO
259 FILES' below for a detailed description.) The
260 `[Servers]' section gives a mapping of labels
261 to servers on the internet, with lines like
262 `Label=http://myserver.org/jigdofiles/'. Using this information,
263 \fBjigdo\fR will create the final download URI for
264 the part, `http://myserver.org/jigdofiles/some/filename'.
265 Specifying `//' (or `\\.\\')
266 in a file or directory name serves to `cut off' the names at the
267 right directory level. For example, if the Unix path of one of
268 your \fIFILES\fR is `/path/some/filename',
269 you can tell \fBjigdo-file\fR to cut off after the
270 `/path' by passing it the argument `/path//some/filename', or
271 `/path//' if you want the whole directory scanned. The path
272 names need not be absolute; `somedirectory//' is also
273 possible.
274 .TP
275 \fB--label \fILabel=/path\fB\fR
276 Specify a name to use as the label name for a path
277 on disc. (Influences the output jigdo file.) If you used
278 `//' in the
279 \fIFILES\fR arguments as described
280 above, \fBjigdo-file\fR will by default pick
281 label names automatically (`A', `B' etc.). With this
282 option, you can give labels more meaningful names. Note
283 that the label name will only be used if one or more
284 \fIFILES\fR begin with
285 `/path//'.
286
287 Try to use label names that start with uppercase
288 characters, to disambiguate them clearly from protocol
289 names like `http', `ftp'.
290 .TP
291 \fB--uri \fILabel=http://some.server.org/\fB\fR
292 By default, using \fB--label\fR as
293 described above will cause lines of the form
294 `Label=file:/path/' to be written to the
295 `[Servers]' section of the output jigdo
296 file. If you want to override the `file:' URI so that the
297 line reads `Label=http://some.server.org/', you can do so
298 by specifying \fB--uri\fR along with
299 \fB--label\fR. Giving just \fB--uri
300 \fILabel=...\fB\fR without the
301 corresponding \fB--label
302 \fILabel=...\fB\fR has no
303 effect, and even if you specify both, an entry is only
304 added to the `[Servers]' section if the
305 label is referenced by at least one
306 `[Parts]' entry.
307
308 The supplied value is not quoted by the program; if
309 it contains characters such as space or any of the
310 characters #"'\\ then you must quote it.
311 (Under Unix, you may need to quote the value twice to also
312 protect it from the shell, e.g. \\\\\\\\ or
313 \&'\\\\' to get a single backslash in the
314 URI.)
315
316 The mapping specified with an \fB--uri\fR
317 option is ignored if it is already present in the output
318 jigdo file.
319
320 Users of the Windows version may notice that the
321 `\\' directory separators are converted
322 into `/' in the `file:' URIs that are
323 generated by default. This is done to increase
324 cross-platform compatibility of `file:' - the
325 \fBprint-missing\fR command of the Windows
326 version will automatically re-convert the characters when
327 it prints the URIs. In case you supply your own `file:'
328 URIs under Windows using \fB--uri\fR, you must
329 also exchange `/' and
330 `\\'.
331 .TP
332 \fB-0 to -9\fR
333 Set amount of compression in the output template
334 file, from \fB-0\fR (no compression) to
335 \fB-9\fR (maximum compression). The default is
336 \fB-9\fR, which can make the template
337 generation quite slow. The compression algorithm used is
338 the same as for \fBgzip\fR(1).
339 .TP
340 \fB--min-length=\fIBYTES\fB\fR
341 Set minimum length of a part for
342 \fBjigdo-file\fR to look for it in the image.
343 The default is 1k. Parts smaller than this will never be
344 found in the image, so their data will be included in the
345 template file. The search algorithm used requires such a
346 minimum length, otherwise template generation could become
347 extremely slow. If you know for sure that all your
348 \fIFILES\fR are larger than a certain
349 amount, you can increase \fBjigdo-file\fR's
350 speed slightly by specifying the amount with this option.
351 There is a hard-wired absolute minimum of 256 bytes -
352 anything lower will silently be set to 256.
353 .TP
354 \fB--merge=\fIFILE\fB\fR
355 Include the contents of
356 \fIFILE\fR in the output
357 `\fI.jigdo\fR' file. The file can contain
358 data which you want added to the output (for example, a
359 `[Servers]' section with a list of your
360 servers as entries), or it can be the jigdo file output by
361 an earlier run of \fBjigdo-file\fR.
362
363 It is possible to specify the same file for input
364 with \fB--merge\fR and for output with
365 \fB--jigdo\fR. However, you will also need to
366 use \fB--force\fR to make the program overwrite
367 the old version of the jigdo file with the new one.
368 \fIFILE\fR can be `-' for standard
369 input.
370
371 When \fBadding\fR new information to
372 the supplied file, \fBjigdo-file\fR will not
373 insert new lines into the `[Parts]'
374 section if an entry for the same MD5 checksum (but not
375 necessarily with the same URI!) already exists, and it
376 will not insert new lines into the
377 `[Servers]' section if a completely
378 identical entry already exists.
379
380 When \fBreading in\fR the existing
381 \fIFILE\fR, the behaviour is slightly
382 different: The program \fBpreserves\fR
383 entries in the `[Parts]' section with
384 identical checksum, but different URIs. For completely
385 identical entries (same checksum and URI), only one entry
386 is preserved and the duplicates are removed. The
387 `[Servers]' section is left
388 untouched.
389 .TP
390 \fB--image-section\fR
391 \fBThis is the default.\fR Causes
392 \fBjigdo-file\fR to add an
393 `[Image]' section to the
394 `\fI.jigdo\fR' file.
395
396 As an exception, a new `[Image]'
397 section is \fBnot\fR added if you use
398 \fB--merge\fR and the file to merge contains an
399 `[Image]' section with a line which
400 reads `Template-MD5Sum=' (end of line
401 after the `='). In this case, the generated template
402 data's MD5 checksum value is just added after the `=' of
403 the first line of this form in the file - no whole new
404 `[Image]' section is appended. This
405 behaviour is useful because it allows you to pass via
406 \fB--merge\fR an `[Image]'
407 section with arbitrary content and then have the MD5
408 checksum automatically added by
409 \fBjigdo-file\fR. The section `FORMAT OF
410 \&.JIGDO FILES' below explains the
411 `[Image]' section contents in greater
412 detail.
413 .TP
414 \fB--no-image-section\fR
415 Do \fBnot\fR include an
416 `[Image]' section in the
417 `\fI.jigdo\fR' file. You need to add one
418 yourself if you use this option. However, doing that is
419 not easy (you also need to add a
420 `Template-MD5Sum' line with the correct
421 checksum, or \fBjigdo\fR will complain), so
422 use of this option is discouraged.
423 .TP
424 \fB--servers-section\fR
425 \fBThis is the default.\fR Causes
426 \fBjigdo-file\fR to add a
427 `[Servers]' section to the
428 `\fI.jigdo\fR' file. This default section
429 uses `file:' URIs, which allows for immediate reassembly
430 of the image from the local filesystem, and is also useful
431 if you want to edit the file manually and replace the
432 `file:' URIs with other URIs.
433 .TP
434 \fB--no-servers-section\fR
435 Do \fBnot\fR add a
436 `[Servers]' section at the end of the
437 `\fI.jigdo\fR' file. Useful e.g. if you are
438 going to append the section with a script.
439 .TP
440 \fB--match-exec=\fISHELLCOMMAND\fB\fR
441 Whenever a file is found in the image, execute the
442 supplied command string by passing it to a shell.
443 \fBjigdo-file\fR sets up a number of
444 environment variables with information about the file
445 match. For example, if the file
446 `\fI/path//a/b/file\fR' was found in the
447 image and `Label:a/b/file' is going to be written to the
448 `\fI.jigdo\fR' file:
449 .RS
450 .TP 0.2i
451 \(bu
452 \fBLABEL\fR="Label" - Name of the label for the file. The example assumes
453 that `\fB--label\fR
454 Label=/path' was specified by you.
455 In the absence of such an option, \fBLABEL\fR
456 will be set but empty.
457 .TP 0.2i
458 \(bu
459 \fBLABELPATH\fR="/path/" - The path corresponding to the label,
460 or in other words, the prefix of the matched file's
461 path that will \fBnot\fR appear in the
462 output `\fI.jigdo\fR' file. Is set even
463 without any `\fB--label\fR' option present.
464 Ends with a slash.
465 .TP 0.2i
466 \(bu
467 \fBMATCHPATH\fR="a/b/" - The rest of the path, without the
468 leafname of the matched file. Is either empty or ends
469 with a slash.
470 .TP 0.2i
471 \(bu
472 \fBLEAF\fR="file"
473 - The leafname of the matched file.
474 .TP 0.2i
475 \(bu
476 \fBMD5SUM\fR="lNVdUSqbo2yqm33webrhnw" - The md5sum of the
477 matched file, in Base64-like format.
478 .TP 0.2i
479 \(bu
480 \fBFILE\fR="/path//a/b/file" - For convenience, the
481 complete path of the file. The variable is always set
482 to $LABELPATH$MATCHPATH$LEAF.
483 .RE
484
485 Please be careful to correctly quote the string
486 passed to this option, otherwise your supplied command
487 will not work with filenames that contain spaces. As an
488 example, to create a backup of hard links to the matched
489 files, use the following option:
490 --match-exec='mkdir -p "${LABEL:-.}/$MATCHPATH"
491 && ln -f "$FILE" "${LABEL:-.}/$MATCHPATH$LEAF"'
492
493 By default, no command is executed. Use
494 --match-exec="" to remove a command string which was set
495 with an earlier use of this option.
496 .SS "MAKE-IMAGE, MI"
497 .PP
498 Reads `\fI.template\fR' and
499 \fIFILES\fR, creates
500 \fIimage\fR (or
501 `\fIimagename.tmp\fR'). Provides a rudimentary
502 way of reassembling images - \fBjigdo\fR is usually
503 better suited for this task. However, in contrast to
504 \fBjigdo\fR, no `\fI.jigdo\fR' file
505 is required.
506 .PP
507 If the image is to be written to a file (and not to
508 standard output), it is possible to create the image in several
509 steps, with several invocations of `\fBjigdo-file
510 make-image\fR', as follows: You first invoke
511 \fBjigdo-file\fR, specifying as many files as are
512 available at this time. The program scans the files, and those
513 that are contained in the image are copied to a temporary file,
514 whose name is formed by appending `\fI.tmp\fR' to
515 the image filename.
516 .PP
517 For all further files which could be parts of the image,
518 you repeat this process. As soon as all parts are present, the
519 temporary file will be truncated slightly (to delete some
520 administrative data that \fBjigdo-file\fR appends
521 at the end) and renamed to the final image name. The possibility
522 of reassembling the image in several steps is especially useful
523 for gathering files from removable media, e.g. several older
524 CDs.
525 .PP
526 Scripts using \fBmake-image\fR can detect
527 whether image creation is complete by checking the exit status:
528 0 signals successful creation, whereas 1 means that more files
529 need to be supplied. Other errors result in an exit status of 2
530 (`recoverable', e.g. file not found) or 3 (non-recoverable, e.g.
531 write error).
532 .TP
533 \fB--check-files\fR
534 \fBThis is the default.\fR Whenever
535 any part is copied to the image, re-check its checksum
536 against the checksum stored in the template. It is
537 recommended that you leave this switched on, even if it
538 slows down image creation a bit.
539 .TP
540 \fB--no-check-files\fR
541 Do not check files' checksums when copying them to
542 the image. This can be safely used when no cache file is
543 used (which means that files will be written to the image
544 immediately after being scanned) or the whole image is
545 checked later with the \fBverify\fR
546 command.
547 .SS "PRINT-MISSING, PM"
548 .PP
549 Reads `\fI.jigdo\fR',
550 `\fI.template\fR' and (if present)
551 `\fIimagename.tmp\fR', outputs a list of URIs
552 still needed to completely reassemble the image.
553 .PP
554 Together with the \fBmake-image\fR command,
555 this provides most of the functionality of
556 \fBjigdo\fR on the command line.
557 .PP
558 For each part that is not yet present in the temporary
559 image file, the file checksum is looked up in the
560 `[Parts]' section of the jigdo file. Any
561 label in the corresponding entry is then expanded according to
562 the label definitions in the `[Servers]'
563 section and printed on standard output. \fBjigdo\fR
564 allows you to specify several alternative locations for each
565 label in this section, but \fBprint-missing\fR will
566 only output the first one for each missing part.
567 .PP
568 If the checksum cannot be found in the
569 `[Parts]' section (this Should Not Happen
570 unless you deleted that section), a lookup is instead made for
571 `MD5Sum:\fI<checksum>\fR', just like
572 with \fBjigdo\fR. (Thus, if you want to get rid of
573 the `[Parts]' section, you can do so if you
574 rename each part to its own checksum.)
575 .TP
576 \fB--uri \fILabel=http://some.server.org/\fB\fR
577 Override the entries in the
578 `\fI.jigdo\fR' file for any label with a
579 URI of your choice. With the example above, a
580 `[Parts]' entry of
581 `Label:some/filename' will cause the line
582 `http://some.server.org/some/filename' to be
583 printed.
584
585 The supplied value is not quoted by the program; if
586 it contains characters such as space or any of the
587 characters #"'\\ then you must quote it.
588 (Under Unix, you may need to quote the value twice to also
589 protect it from the shell, e.g. \\\\\\\\ or
590 \&'\\\\' to get a single backslash in the
591 URI.)
592 .SS "PRINT-MISSING-ALL, PMA"
593 .PP
594 Just like \fBprint-missing\fR, this command
595 outputs a list of URIs still needed to completely reassemble the
596 image. However, \fBall\fR alternative download
597 locations are printed instead of just one. In the output, the
598 URIs for a file are separated from other files' URIs with blank
599 lines. The \fB--uri\fR option has the same effect as
600 for \fBprint-missing\fR.
601 .SS "VERIFY, VER"
602 .PP
603 Reads \fIimage\fR (presumably
604 generated with \fBmake-image\fR) and
605 `\fI.template\fR', checks for correct checksum of
606 image.
607 .PP
608 The template data does not only contain checksums of the
609 individual parts, but also of the image as a whole.
610 \fBmake-image\fR already performs a number of
611 internal checks, but if you like, you can additionally check the
612 image with this command.
613 .SS "SCAN, SC"
614 .PP
615 Reads all the \fIFILES\fR and enters
616 them into the cache, unless they are already cached. The
617 \fB--cache\fR option must be present for this
618 command.
619 .SS "MD5SUM, MD5"
620 .PP
621 Reads all the \fIFILES\fR and prints
622 out MD5 checksums of their contents. This command is quite
623 similar to \fBmd5sum\fR(1), except that the checksum is output in the
624 Base64-like encoding which is also used elsewhere by
625 \fBjigdo-file\fR.
626 .PP
627 The \fIFILES\fR arguments are
628 processed in the same way as with the other commands, which
629 means that recursion automatically takes place for any arguments
630 that are directories, and that symbolic links are not listed
631 except when the file(s) they point to are not reachable
632 directly.
633 .PP
634 In the checksum list printed on standard output, only the
635 part of the filename following any `//' (or
636 `\\.\\' on Windows) is printed. Any
637 \fB--cache\fR will be used for querying files' MD5
638 checksums and/or writing the checksums of scanned files.
639 .SS "LIST-TEMPLATE, LS"
640 .PP
641 Reads a `\fI.template\fR' file and outputs
642 low-level information about the image and all parts contained in
643 it, including offset, length and checksum.
644 .PP
645 You can also use this command with temporary image files
646 (by specifying something like
647 \fB--template=imagename.tmp\fR) - in that case, the
648 output also distinguishes between parts that have been written
649 to the image and parts that haven't.
650 .PP
651 The exact output format may change incompatibly between
652 different jigdo releases. The following different types of lines
653 can be output. `have-file' only occurs for
654 `\fI.tmp\fR' files, indicating a file that has
655 already been successfully written to the temporary file:
656
657 .nf
658 in-template \fIoffset-in-image length\fR
659 need-file \fIoffset-in-image length file-md5sum filestart-rsyncsum\fR
660 have-file \fIoffset-in-image length file-md5sum filestart-rsyncsum\fR
661 image-info \fIimage-length image-md5sum rsyncsum-size\fR
662 .fi
663 .SH "DETAILS"
664 .PP
665 Jigsaw Download was created with the format of ISO9660 CD
666 images in mind - however, the following also applies to many other
667 filesystem formats, as well as to `tar' archives and uncompressed
668 `zip' archives. A CD image contains both information for
669 organizing the filesystem (header with disc name etc., ISO9660
670 directory data, data of extensions such as Joliet or RockRidge,
671 zero padding) and the files contained on the CD. An important
672 property that jigdo relies on is that each file is stored in one
673 contiguous section of the image; it is not split into two or more
674 parts.
675 .PP
676 When \fBjigdo-file\fR is given a number of
677 files that might be contained in an image, it detects whether any
678 of the files are present using a `rolling checksum' inspired by
679 the one used by \fBrsync\fR(1). The resulting data is
680 written to the `\fI.template\fR' file: If a section
681 of the image could not be matched (e.g. it was directory
682 information), the data is compressed and written directly to the
683 template. However, if a matching file was found, its data is
684 omitted from the template. Instead, only a reference (an MD5
685 checksum of the file) is inserted in the template.
686 .PP
687 Note that the template data only contains binary data, it
688 does not contain any filenames or URIs, since it cannot be easily
689 edited in case any of these values need to be changed. All that
690 information is stored in the `\fI.jigdo\fR' file, a
691 text file to which you can add URLs for your server(s). The jigdo
692 file provides a mapping for each MD5 checksum to one or more
693 alternative download locations for the corresponding part.
694 .PP
695 Apart from the mapping of MD5 sums to URIs, the jigdo file
696 also contains an URI pointing to a download location for the
697 template file. This way, the \fBjigdo\fR download
698 tool only needs to be given one URI (that of the
699 `\fI.jigdo\fR' file) to be able to download and
700 reassemble the complete image.
701 .SH "FORMAT OF .JIGDO FILES"
702 .PP
703 The overall format of `\fI.jigdo\fR' files
704 follows that of `\fI.ini\fR' files, as also used by
705 the Gnome and KDE projects for some data. The file is organized
706 into sections, each of which is preceded by a line reading
707 `[Sectionname]'. Within each section, lines
708 have the form `Label=Value'. Such lines are also called `entries'
709 below. All `\fI.jigdo\fR' files use UTF-8 as their
710 character encoding.
711 .PP
712 Comments are introduced with the `#'
713 character and extend to the end of the line. Whitespace is ignored
714 at line start and end as well as to the left and right of section
715 names and the `=' in entries. Furthermore, the
716 jigdo utilities split up the text of the entry value (i.e. the
717 part after the `=') into whitespace-separated
718 words, much like the Unix shell. Single '' and
719 double "" quotes can be used to prevent that
720 e.g. URIs containing whitespace are split apart. Similarly,
721 characters with special meaning (the characters
722 \&'"#\\ and space/tab) must be quoted with
723 \\ to appear in the value. As with the shell,
724 there is a difference between '\~' and
725 "\~": Within '\~',
726 the characters "#\\ and whitespace lose their
727 special meaning and become ordinary characters, whereas within
728 "\~", only the characters
729 \&'# and whitespace lose their special meaning -
730 in other words, backslash escapes still work inside
731 "\~", but not
732 \&'\~'.
733 .PP
734 `\fI.jigdo\fR' files can optionally be
735 compressed with \fBgzip\fR(1). \fBjigdo-file\fR always outputs
736 uncompressed files, which you can compress yourself. 
737 \fBjigdo-lite\fR supports single uncompressed and
738 compressed files. \fBjigdo\fR additionally supports
739 any number of concatenated plaintext and gzipped parts in the
740 files - for example, you can compress a
741 `\fI.jigdo\fR' file and then add a couple of lines
742 of uncompressed data to the end. In all cases, the
743 `\fI.gz\fR' extension should be removed from the
744 filename - the tools will determine automatically from the file
745 contents whether a file is compressed or not.
746 .PP
747 Below is a description of the individual section names used
748 by jigdo.
749 .SS "JIGDO SECTION"
750
751 .nf
752 [Jigdo]
753 Version=1.1
754 Generator=jigdo-file/1.0.0
755 .fi
756 .PP
757 Information about the version of the jigdo file format
758 used, and the program that generated it. There should be one
759 such section per `\fI.jigdo\fR' file.
760 .SS "IMAGE SECTION"
761
762 .nf
763 [Image]
764 Filename=\fI"filename for saving on user's disc"\fR
765 Template=\fI"URI where to fetch template file"\fR
766 Template-MD5Sum=OQ8riqT1BuyzsrT9964A7g
767 ShortInfo=\fIsingle-line description of the image (200 characters max.)\fR
768 Info=\fIlong description (5000 characters max.)\fR
769 .fi
770 .PP
771 The value for the `Template' entry can be either an URL
772 (absolute or relative to the URL of the jigdo file) or a string
773 of the form `\fILabel\fR:\fIpathname\fR' (\fBUNIMPLEMENTED\fR),
774 as described below.
775 .PP
776 The `Template-MD5Sum' entry is added by
777 \fBjigdo-file\fR and specifies the MD5 checksum of
778 the generated `\fI.template\fR' file. It is used
779 by \fBjigdo\fR to detect cases where the downloaded
780 template data is corrupted or belongs to a different
781 image.
782 .PP
783 Unlike other entry values, the values of the
784 `ShortInfo' and `Info'
785 entries are \fBnot\fR split up into words,
786 instead all quoting is preserved.
787 .PP
788 The value of the `Info' entry is
789 special in that \fBjigdo\fR(1) can optionally parse XML markup it contains. If
790 the markup has errors such as unbalanced/unsupported tags, the
791 string is displayed literally, without XML parsing. Supported
792 tags are <b></b> (bold),
793 <i></i> (italic),
794 <tt></tt> (typewriter font),
795 <u></u> (underline),
796 <big></big> (larger font),
797 <small></small> (smaller font)
798 and <br/> (linebreak). Supported
799 entities include &lt; (`<'),
800 &gt; (`>') and
801 &amp; (`&'). Note that the whole
802 `Info' entry must be on one line in the jigdo
803 file.
804 .PP
805 This section may occur multiple times, but all except the
806 first one will be ignored. This is useful e.g. when creating a
807 `\fI.jigdo\fR' file for a DVD image when you
808 already have `\fI.jigdo\fR' files for CDs with
809 the same content: You can simply `[Include]'
810 (see below) the CDs' jigdo files at the end of the DVD jigdo
811 file, after its `[Image]' section.
812 .SS "PARTS SECTION"
813
814 .nf
815 [Parts]
816 xJNkjrq8NYMraeGavUpllw=LabelA:part0
817 GoTResP2EC6Lb_2wTsqOoQ=LabelA:part1
818 kyfebwu6clbYqqWUdFIyaw=LabelB:some/path/part2
819 -J9UAimo0Bqg9c0oOXI1mQ=http://some.where.com/part3
820 .fi
821 .PP
822 All lines in the section, which provides the mapping from
823 MD5 checksums to URIs, have the same format: On the left side of
824 the `=' the checksum (encoded with a
825 Base64-like encoding) is given, and on the right a string
826 corresponding to the part with this checksum; either a complete
827 URI or a string of the form `\fILabel\fR:\fIpathname\fR', which is expanded into
828 one or more URIs by looking up the definition(s) for the
829 \fILabel\fR in the
830 `[Servers]' section.
831 .PP
832 In case a particular MD5 checksum cannot be found in any
833 `[Parts]' section by
834 \fBjigdo\fR, the program will perform a lookup for
835 `MD5Sum:\fI<checksum>\fR', e.g. for
836 `MD5Sum:xJNkjrq8NYMraeGavUpllw' if you
837 deleted the line for `part0' above.
838 .PP
839 A checksum appearing multiple times in this section
840 indicates alternative download locations for the part.
841 .PP
842 There may be any number of `[Parts]'
843 sections in the file; they are all considered when looking up
844 MD5 checksums.
845 .PP
846 \fBjigdo-file\fR always puts the
847 `[Parts]' section at the end of the file, and
848 it even rearranges any file specified with
849 \fB--merge\fR to have only one such section at the
850 end. This is done to allow \fBjigdo\fR to display
851 the information from the `[Image]' section
852 while the rest of that file is still being downloaded.
853 .SS "SERVERS SECTION"
854
855 .nf
856 [Servers]
857 LabelA=http://myserver.org/
858 LabelA=ftp://mirror.myserver.org/
859 LabelB=LabelC:subdirectory/
860 LabelC=http://some.where.com/jigdo/
861 .fi
862 .PP
863 All lines in the section, which provides the mapping from
864 server labels to server locations, have the same format: On the
865 left side of the `=' the label name is given,
866 and on the right the value to expand the label name to.
867 .PP
868 A label name appearing multiple times in this section
869 indicates alternative download locations for the parts that use
870 the label in the `[Parts]' section. This
871 notation makes it very easy to add mirrors to the jigdo
872 file.
873 .PP
874 As shown by the example above, the label values may
875 themselves reference other labels. In this case, the entry
876 `LabelB:some/path/part2' in the `[Parts]'
877 section will expand to
878 `http://some.where.com/jigdo/subdirectory/some/path/part2'.
879 Loops in the label definitions result in undefined behaviour and
880 must be avoided.
881 .PP
882 There may be any number of `[Servers]'
883 sections in the file; they are all considered when looking up
884 labels. Either of `[Parts]' or
885 `[Servers]', but not both, can be omitted
886 from the jigdo file.
887 .SS "COMMENT SECTION"
888
889 .nf
890 [Comment]
891 Any text, except that lines must not begin with `['.
892 .fi
893 .PP
894 All text following a `[Comment]' or
895 `[comment]' line is ignored, up to the next
896 line with a section label.
897 .SS "INCLUDE DIRECTIVE"
898
899 .nf
900 [Include http://some.url/file.jigdo]
901 .fi
902 .PP
903 Lines of this form cause the content of the specified
904 jigdo file to be downloaded and parsed just like the main jigdo
905 file. The effect will be the same as copying the included file's
906 contents into the file which contains the include directive.
907 .PP
908 The URL argument can be an absolute or relative URL. 
909 Relative URLs are assumed to be relative to the URL of the jigdo
910 file which contains the include directive. Includes can be
911 nested, but it is an error to create a loop of include
912 directives. It is \fBnot\fR possible to use URLs
913 of the form `\fILabel\fR:\fIpathname\fR'.
914 .PP
915 The URL cannot be quoted with "". Any
916 `]' characters in the argument must be
917 escaped as `%5D', and any spaces as
918 `%20'.
919 .PP
920 Include directives are only supported by
921 \fBjigdo\fR, they are ignored by
922 \fBjigdo-lite\fR.
923 .PP
924 An include directive terminates any previous section, but
925 it does not start a new one. In other words, a new section must
926 always be started after the include line,
927 \fBjigdo\fR does not allow normal entries to appear
928 below the `[Include]'.
929 .SH "CACHE FILES"
930 .PP
931 Any file specified with the \fB--cache\fR option
932 is used to store information about the
933 \fIFILES\fR presented to
934 \fBjigdo-file\fR. When querying the cache, a file is
935 considered unchanged (and the cached data is used) only if
936 filename, file size and last modification time (mtime) match
937 exactly. For the filename match, not the entire file name is used,
938 but only the part following any `//', so that
939 any changes to the part before the `//' will
940 not invalidate the cache.
941 .PP
942 Old cache entries are removed from the cache if they have
943 not been read from or written to for the amount of time specified
944 with \fB--cache-expiry\fR. Entries are
945 \fBnot\fR immediately removed from the cache if the
946 file they refer to no longer exists - this makes it possible to
947 cache information about files on removable media.
948 .PP
949 Cache expiry only takes place \fBafter\fR
950 \fBjigdo-file\fR has done its main work - if any old
951 entries are accessed before expiry takes place, they will be kept.
952 For example, if the program is run using the default expiry time
953 of 30 days, but accesses a cache file with entries generated 2
954 months ago, then entries in that cache \fBwill\fR
955 be considered, and only those cache entries that were not needed
956 during the program run will be expired.
957 .PP
958 Due to a peculiarity of the underlying database library
959 (libdb3), cache files never shrink, they only grow. If a large
960 number of entries was expired from your cache file and you want it
961 to shrink, you can either just delete it (of course then
962 everything will have to be regenerated) or use the utilities
963 accompanying libdb3 to dump and restore the database, with a
964 command like `\fBdb3_dump
965 \fIold-cache.db\fB | db3_load
966 \fInew-cache.db\fB\fR'. For Debian, these programs are supplied in the
967 package `libdb3-util'.
968 .PP
969 If a different \fB--md5-block-size\fR is
970 specified, the entire file needs to be re-read to update its cache
971 entry. If a different \fB--min-length\fR is specified,
972 only the first `md5-block-size' bytes of the file need to be
973 re-read.
974 .SH "EXAMPLES"
975 .SS "PREPARING YOUR CD IMAGE FOR DISTRIBUTION"
976 .PP
977 You have created a CD image
978 `\fIimage.iso\fR' from some of the files stored
979 in the directory `\fI/home/ftp\fR' on your
980 harddisc, which is also available online as `ftp://mysite.org'.
981 As you don't want to waste space by effectively hosting the same
982 data twice (once as files on the FTP server, once inside the
983 image), and you are fed up with users' downloads aborting after
984 200MB and their restarting the download dozens of times, you
985 decide to use jigdo. How do you prepare the image for
986 download?
987 .PP
988 In fact, only one command is necessary:
989 .sp
990 .RS
991 .PP
992 \fBjigdo-file make-template
993 --image=image.iso --jigdo=/home/ftp/image.jigdo
994 --template=/home/ftp/image.template /home/ftp// --label
995 Mysite=/home/ftp --uri
996 Mysite=ftp://mysite.org/\fR
997 .RE
998 .PP
999 People can now point \fBjigdo\fR at
1000 `ftp://mysite.org/image.jigdo' to download your image. The
1001 template file needs to be accessible as
1002 `ftp://mysite.org/image.template'.
1003 .PP
1004 Note that nothing prevents you from doing the same for an
1005 FTP server that isn't administrated by you - in that case, you
1006 only need to host the `\fI.jigdo\fR' and
1007 `\fI.template\fR' files on your own
1008 server/homepage.
1009 .SS "PREPARING AN ARBITRARY LARGE FILE FOR DISTRIBUTION"
1010 .PP
1011 We assume that you have a large file that is not a
1012 filesystem, e.g. `\fImovie.mpeg\fR'. Because of
1013 space problems, you want to distribute the data on two
1014 servers.
1015 .PP
1016 In this case, the parts of the image need to be generated
1017 artificially with the \fBsplit\fR command. For
1018 example, to create chunks of 4MB each, use `\fBsplit -b 4m
1019 movie.mpeg part\fR'. Copy the resulting files
1020 `\fIpartXX\fR' into
1021 two directories `\fI1\fR' and
1022 `\fI2\fR' that you create, according to how you
1023 want the files distributed between the servers. Next, create the
1024 jigdo and template files with `\fBjigdo-file make-template
1025 --image=movie.mpeg 1// 2//\fR'. You will need to edit the
1026 `\fI.jigdo\fR' file and provide the right URIs
1027 for the two servers that you are going to upload the
1028 `\fIpartXX\fR' files
1029 to.
1030 .SS "CUSTOMIZED VERSIONS OF IMAGES"
1031 .PP
1032 Because it is possible to assign a different URI for each
1033 part of an image if necessary, jigdo is very flexible. Only one
1034 example is the possibility of customized versions of images:
1035 Suppose that someone is distributing a CD image, and that you
1036 want to make a few small changes to it and redistribute your own
1037 version. You download the `\fIofficial.iso\fR' CD
1038 image with \fBjigdo\fR (passing it the URL of
1039 `\fIofficial.jigdo\fR'), write it to CD-R, make
1040 your changes (say, adding files from the
1041 `\fImyfiles\fR' directory on your harddisc) and
1042 produce your own version, `\fImyversion.iso\fR'.
1043 Next, you instruct \fBjigdo-file\fR to create the
1044 jigdo and template files for your modified image, using the
1045 command
1046 .sp
1047 .RS
1048 .PP
1049 \fBjigdo-file make-template
1050 --image=myversion.iso /mnt/cdrom/ myfiles// --label
1051 My=myfiles/ --uri My=http://my.homepage.net/
1052 --merge=official.jigdo\fR
1053 .RE
1054 while `\fIofficial.iso\fR' is mounted under
1055 `\fI/mnt/cdrom\fR'. By using
1056 \fB--merge\fR, you have told
1057 \fBjigdo-file\fR to take the contents of
1058 `\fIofficial.jigdo\fR', add to it a new
1059 `[Image]' section for
1060 `\fImyversion.iso\fR' and write the resulting
1061 jigdo file to `\fImyversion.jigdo\fR' - so now
1062 `\fImyversion.jigdo\fR' offers two images for
1063 download, the original version and your modified version. (If
1064 you do not want it to offer the official version, edit it and
1065 remove the `[Image]' section that lists
1066 `\fIofficial.iso\fR'.)
1067 .PP
1068 Now you can upload the `\fI.jigdo\fR' file,
1069 the `\fI.template\fR' file and also the files in
1070 `\fImyfiles\fR' to `http://my.homepage.net/'.
1071 Thus, for people to download your modified image, you do
1072 \fBnot\fR need to upload the complete image
1073 contents to your web space, but only the changes you
1074 made!
1075 .PP
1076 (In case you only made very few changes, you could also
1077 omit the `myfiles' parameter in the command above, then all your
1078 changes end up in the new template file.)
1079 .SS "COMBINING MANY JIGDO-MANAGED IMAGES INTO ONE"
1080 .PP
1081 It is also no problem to combine data from several sources
1082 that use jigdo. For example, if of five different and unrelated
1083 servers each one distributes a different CD image via jigdo, you
1084 can create a customized DVD image that contains the data from
1085 all these CDs. When people use \fBjigdo\fR to
1086 download your image, the individual files on the DVD are fetched
1087 from the same sources as the original CDs.
1088 .PP
1089 Consequently, even though you will be distributing a 3.2GB
1090 file via your web space, the actual amount of data that is
1091 stored on your server will only be in the order of several
1092 MBs.
1093 .SH "BUGS"
1094 .PP
1095 For certain contents of one of the input files, most notably
1096 a sequence of zero bytes longer than \fB--min-length\fR
1097 at the start of the file and an area of zeros preceding the file
1098 data in the image, \fBjigdo-file make-template\fR may
1099 fail to find the file in the image. Unfortunately, this
1100 restriction cannot be avoided because the program could become
1101 very slow otherwise. If you use the \fB--debug\fR
1102 option, all instances of \fBjigdo-file\fR discarding
1103 possible matches are indicated by lines containing the word
1104 `DROPPED'.
1105 .PP
1106 In fact, not only all-zeroes files trigger this behaviour,
1107 but also files which contain at their start a long sequence of
1108 short identical strings. For example, both a file containing only
1109 `a' characters and one containing
1110 `abcabcabcabc...' are problematic.
1111 .SH "SEE ALSO"
1112 .PP
1113 \fBjigdo\fR(1) (NOT YET IMPLEMENTED),
1114 \fBjigdo-lite\fR(1),
1115 \fBjigdo-mirror\fR(1),
1116 \fBsplit\fR(1) (or `\fBinfo split\fR'),
1117 \fBfind\fR(1) (or `\fBinfo find\fR'),
1118 \fBmkisofs\fR(1),
1119 \fBmd5sum\fR(1)
1120 .SH "AUTHOR"
1121 .PP
1122 Jigsaw
1123 Download <URL:http://atterer.net/jigdo/> was written by Richard Atterer
1124 <jigdo atterer.net>, to make downloading of CD ROM
1125 images for the Debian Linux distribution more convenient.