Import Upstream version 0.7.2
[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 .\" <> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <>.
6 .TH "JIGDO-FILE" "1" "10 July 2005" "" ""
9 jigdo-file \- Prepare files for Jigsaw Download (distribution of huge files, e.g. CD images).
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
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.
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.
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.
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.
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.
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.
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
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='. Using this information,
263 \fBjigdo\fR will create the final download URI for
264 the part, `'.
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//'.
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=\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=', 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.
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.)
316 The mapping specified with an \fB--uri\fR
317 option is ignored if it is already present in the output
318 jigdo file.
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. By default, the compression
338 algorithm used is the same as for \fBgzip\fR(1)\&.
339 .TP
340 \fB--gzip and --bzip2\fR
341 Choose between the gzip and bzip2 compression
342 algorithms. The default is gzip. Bzip2 usually gives
343 a better compression ratio, but compression is
344 significantly slower than with gzip.
345 .TP
346 \fB--min-length=\fIBYTES\fB\fR
347 Set minimum length of a part for
348 \fBjigdo-file\fR to look for it in the image.
349 The default is 1k. Parts smaller than this will never be
350 found in the image, so their data will be included in the
351 template file. The search algorithm used requires such a
352 minimum length, otherwise template generation could become
353 extremely slow. If you know for sure that all your
354 \fIFILES\fR are larger than a certain
355 amount, you can increase \fBjigdo-file\fR\&'s
356 speed slightly by specifying the amount with this option.
357 There is a hard-wired absolute minimum of 256 bytes -
358 anything lower will silently be set to 256.
359 .TP
360 \fB--merge=\fIFILE\fB\fR
361 Include the contents of
362 \fIFILE\fR in the output
363 `\fI\&.jigdo\fR\&' file. The file can contain
364 data which you want added to the output (for example, a
365 `[Servers]\&' section with a list of your
366 servers as entries), or it can be the jigdo file output by
367 an earlier run of \fBjigdo-file\fR\&.
369 It is possible to specify the same file for input
370 with \fB--merge\fR and for output with
371 \fB--jigdo\fR\&. However, you will also need to
372 use \fB--force\fR to make the program overwrite
373 the old version of the jigdo file with the new one.
374 \fIFILE\fR can be `-' for standard
375 input.
377 When \fBadding\fR new information to
378 the supplied file, \fBjigdo-file\fR will not
379 insert new lines into the `[Parts]\&'
380 section if an entry for the same MD5 checksum (but not
381 necessarily with the same URI!) already exists, and it
382 will not insert new lines into the
383 `[Servers]\&' section if a completely
384 identical entry already exists.
386 When \fBreading in\fR the existing
387 \fIFILE\fR, the behaviour is slightly
388 different: The program \fBpreserves\fR
389 entries in the `[Parts]\&' section with
390 identical checksum, but different URIs. For completely
391 identical entries (same checksum and URI), only one entry
392 is preserved and the duplicates are removed. The
393 `[Servers]\&' section is left
394 untouched.
395 .TP
396 \fB--image-section\fR
397 \fBThis is the default.\fR Causes
398 \fBjigdo-file\fR to add an
399 `[Image]\&' section to the
400 `\fI\&.jigdo\fR\&' file.
402 As an exception, a new `[Image]\&'
403 section is \fBnot\fR added if you use
404 \fB--merge\fR and the file to merge contains an
405 `[Image]\&' section with a line which
406 reads `Template-MD5Sum=\&' (end of line
407 after the `='). In this case, the generated template
408 data's MD5 checksum value is just added after the `=' of
409 the first line of this form in the file - no whole new
410 `[Image]\&' section is appended. This
411 behaviour is useful because it allows you to pass via
412 \fB--merge\fR an `[Image]\&'
413 section with arbitrary content and then have the MD5
414 checksum automatically added by
415 \fBjigdo-file\fR\&. The section `FORMAT OF
416 .JIGDO FILES' below explains the
417 `[Image]\&' section contents in greater
418 detail.
419 .TP
420 \fB--no-image-section\fR
421 Do \fBnot\fR include an
422 `[Image]\&' section in the
423 `\fI\&.jigdo\fR\&' file. You need to add one
424 yourself if you use this option. However, doing that is
425 not easy (you also need to add a
426 `Template-MD5Sum\&' line with the correct
427 checksum, or \fBjigdo\fR will complain), so
428 use of this option is discouraged.
429 .TP
430 \fB--servers-section\fR
431 \fBThis is the default.\fR Causes
432 \fBjigdo-file\fR to add a
433 `[Servers]\&' section to the
434 `\fI\&.jigdo\fR\&' file. This default section
435 uses `file:' URIs, which allows for immediate reassembly
436 of the image from the local filesystem, and is also useful
437 if you want to edit the file manually and replace the
438 `file:' URIs with other URIs.
439 .TP
440 \fB--no-servers-section\fR
441 Do \fBnot\fR add a
442 `[Servers]\&' section at the end of the
443 `\fI\&.jigdo\fR\&' file. Useful e.g. if you are
444 going to append the section with a script.
445 .TP
446 \fB--match-exec=\fISHELLCOMMAND\fB\fR
447 Whenever a file is found in the image, execute the
448 supplied command string by passing it to a shell.
449 \fBjigdo-file\fR sets up a number of
450 environment variables with information about the file
451 match. For example, if the file
452 `\fI/path//a/b/file\fR\&' was found in the
453 image and `Label:a/b/file' is going to be written to the
454 `\fI\&.jigdo\fR\&' file:
455 .RS
456 .TP 0.2i
457 \(bu
458 \fBLABEL\fR="Label" - Name of the label for the file. The example assumes
459 that `\fB--label\fR
460 Label=/path\&' was specified by you.
461 In the absence of such an option, \fBLABEL\fR
462 will be set but empty.
463 .TP 0.2i
464 \(bu
465 \fBLABELPATH\fR="/path/" - The path corresponding to the label,
466 or in other words, the prefix of the matched file's
467 path that will \fBnot\fR appear in the
468 output `\fI\&.jigdo\fR\&' file. Is set even
469 without any `\fB--label\fR\&' option present.
470 Ends with a slash.
471 .TP 0.2i
472 \(bu
473 \fBMATCHPATH\fR="a/b/" - The rest of the path, without the
474 leafname of the matched file. Is either empty or ends
475 with a slash.
476 .TP 0.2i
477 \(bu
478 \fBLEAF\fR="file"
479 - The leafname of the matched file.
480 .TP 0.2i
481 \(bu
482 \fBMD5SUM\fR="lNVdUSqbo2yqm33webrhnw" - The md5sum of the
483 matched file, in Base64-like format.
484 .TP 0.2i
485 \(bu
486 \fBFILE\fR="/path//a/b/file" - For convenience, the
487 complete path of the file. The variable is always set
489 .RE
491 Please be careful to correctly quote the string
492 passed to this option, otherwise your supplied command
493 will not work with filenames that contain spaces. As an
494 example, to create a backup of hard links to the matched
495 files, use the following option:
496 --match-exec='mkdir -p "${LABEL:-.}/$MATCHPATH"
497 && ln -f "$FILE" "${LABEL:-.}/$MATCHPATH$LEAF"'
499 By default, no command is executed. Use
500 --match-exec="" to remove a command string which was set
501 with an earlier use of this option.
502 .TP
503 \fB--greedy-matching\fR
504 \fBThis is the default.\fR Imagine
505 that your image contains a \fI\&.tar\fR file
506 which in turn contains another file
507 \fIx\fR, and that you provide both the
508 \fI\&.tar\fR and the files inside it on the
509 command line. When \fBjigdo-file\fR scans the
510 image, it encounters the beginning of the
511 \fI\&.tar\fR file, and then the file
512 \fIx\fR\&.
514 At this point, a decision must be made: Should the
515 smaller file \fIx\fR be recorded as
516 matched, or should it be ignored in favour of the larger
517 (and thus better) match of the \fI\&.tar\fR
518 file? Unfortunately, at this point it is not clear
519 whether there will actually be a full match of the
520 \fI\&.tar\fR, so by default, the program
521 prefers the small match.
522 .TP
523 \fB--no-greedy-matching\fR
524 In the case where a large partial match is present
525 and a shorter match has been confirmed, ignore the small
526 match. (See the option above.)
528 .PP
529 Reads `\fI\&.template\fR\&' and
530 \fIFILES\fR, creates
531 \fIimage\fR (or
532 `\fIimagename.tmp\fR\&'). Provides a rudimentary
533 way of reassembling images - \fBjigdo\fR is usually
534 better suited for this task. However, in contrast to
535 \fBjigdo\fR, no `\fI\&.jigdo\fR\&' file
536 is required.
537 .PP
538 If the image is to be written to a file (and not to
539 standard output), it is possible to create the image in several
540 steps, with several invocations of `\fBjigdo-file
541 make-image\fR\&', as follows: You first invoke
542 \fBjigdo-file\fR, specifying as many files as are
543 available at this time. The program scans the files, and those
544 that are contained in the image are copied to a temporary file,
545 whose name is formed by appending `\fI\&.tmp\fR\&' to
546 the image filename.
547 .PP
548 For all further files which could be parts of the image,
549 you repeat this process. As soon as all parts are present, the
550 temporary file will be truncated slightly (to delete some
551 administrative data that \fBjigdo-file\fR appends
552 at the end) and renamed to the final image name. The possibility
553 of reassembling the image in several steps is especially useful
554 for gathering files from removable media, e.g. several older
555 CDs.
556 .PP
557 Scripts using \fBmake-image\fR can detect
558 whether image creation is complete by checking the exit status:
559 0 signals successful creation, whereas 1 means that more files
560 need to be supplied. Other errors result in an exit status of 2
561 (`recoverable', e.g. file not found) or 3 (non-recoverable, e.g.
562 write error).
563 .TP
564 \fB--check-files\fR
565 \fBThis is the default.\fR Whenever
566 any part is copied to the image, re-check its checksum
567 against the checksum stored in the template. It is
568 recommended that you leave this switched on, even if it
569 slows down image creation a bit.
570 .TP
571 \fB--no-check-files\fR
572 Do not check files' checksums when copying them to
573 the image. This can be safely used when no cache file is
574 used (which means that files will be written to the image
575 immediately after being scanned) or the whole image is
576 checked later with the \fBverify\fR
577 command.
579 .PP
580 Reads `\fI\&.jigdo\fR\&',
581 `\fI\&.template\fR\&' and (if present)
582 `\fIimagename.tmp\fR\&', outputs a list of URIs
583 still needed to completely reassemble the image.
584 .PP
585 Together with the \fBmake-image\fR command,
586 this provides most of the functionality of
587 \fBjigdo\fR on the command line.
588 .PP
589 For each part that is not yet present in the temporary
590 image file, the file checksum is looked up in the
591 `[Parts]\&' section of the jigdo file. Any
592 label in the corresponding entry is then expanded according to
593 the label definitions in the `[Servers]\&'
594 section and printed on standard output. \fBjigdo\fR
595 allows you to specify several alternative locations for each
596 label in this section, but \fBprint-missing\fR will
597 only output the first one for each missing part.
598 .PP
599 If the checksum cannot be found in the
600 `[Parts]\&' section (this Should Not Happen
601 unless you deleted that section), a lookup is instead made for
602 `MD5Sum:\fI<checksum>\fR\&', just like
603 with \fBjigdo\fR\&. (Thus, if you want to get rid of
604 the `[Parts]\&' section, you can do so if you
605 rename each part to its own checksum.)
606 .TP
607 \fB--uri \fILabel=\fB\fR
608 Override the entries in the
609 `\fI\&.jigdo\fR\&' file for any label with a
610 URI of your choice. With the example above, a
611 `[Parts]\&' entry of
612 `Label:some/filename' will cause the line
613 `' to be
614 printed.
616 The supplied value is not quoted by the program; if
617 it contains characters such as space or any of the
618 characters #"'\\ then you must quote it.
619 (Under Unix, you may need to quote the value twice to also
620 protect it from the shell, e.g. \\\\\\\\ or
621 \&'\\\\' to get a single backslash in the
622 URI.)
624 .PP
625 Just like \fBprint-missing\fR, this command
626 outputs a list of URIs still needed to completely reassemble the
627 image. However, \fBall\fR alternative download
628 locations are printed instead of just one. In the output, the
629 URIs for a file are separated from other files' URIs with blank
630 lines. The \fB--uri\fR option has the same effect as
631 for \fBprint-missing\fR\&.
633 .PP
634 Reads \fIimage\fR (presumably
635 generated with \fBmake-image\fR) and
636 `\fI\&.template\fR\&', checks for correct checksum of
637 image.
638 .PP
639 The template data does not only contain checksums of the
640 individual parts, but also of the image as a whole.
641 \fBmake-image\fR already performs a number of
642 internal checks, but if you like, you can additionally check the
643 image with this command.
644 .SS "SCAN, SC"
645 .PP
646 Reads all the \fIFILES\fR and enters
647 them into the cache, unless they are already cached. The
648 \fB--cache\fR option must be present for this
649 command.
650 .TP
651 \fB--no-scan-whole-file\fR
652 \fBThis is the default.\fR This only
653 causes the first \fB--md5-block-size\fR bytes
654 of each file to be read. If the cache is used later by
655 \fBjigdo-file make-image\fR, the rest of the
656 file will be read once these first bytes are recognized in
657 the input image.
658 .TP
659 \fB--scan-whole-file\fR
660 Immediately read the entire file contents and store
661 them in the cache.
662 .SS "MD5SUM, MD5"
663 .PP
664 Reads all the \fIFILES\fR and prints
665 out MD5 checksums of their contents. This command is quite
666 similar to \fBmd5sum\fR(1), except that the checksum is output in the
667 Base64-like encoding which is also used elsewhere by
668 \fBjigdo-file\fR\&.
669 .PP
670 The \fIFILES\fR arguments are
671 processed in the same way as with the other commands, which
672 means that recursion automatically takes place for any arguments
673 that are directories, and that symbolic links are not listed
674 except when the file(s) they point to are not reachable
675 directly.
676 .PP
677 In the checksum list printed on standard output, only the
678 part of the filename following any `//\&' (or
679 `\\.\\\&' on Windows) is printed. Any
680 \fB--cache\fR will be used for querying files' MD5
681 checksums and/or writing the checksums of scanned files.
683 .PP
684 Reads a `\fI\&.template\fR\&' file and outputs
685 low-level information about the image and all parts contained in
686 it, including offset, length and checksum.
687 .PP
688 You can also use this command with temporary image files
689 (by specifying something like
690 \fB--template=imagename.tmp\fR) - in that case, the
691 output also distinguishes between parts that have been written
692 to the image and parts that haven't.
693 .PP
694 The exact output format may change incompatibly between
695 different jigdo releases. The following different types of lines
696 can be output. `have-file' only occurs for
697 `\fI\&.tmp\fR\&' files, indicating a file that has
698 already been successfully written to the temporary file:
700 .nf
701 in-template \fIoffset-in-image length\fR
702 need-file \fIoffset-in-image length file-md5sum filestart-rsyncsum\fR
703 have-file \fIoffset-in-image length file-md5sum filestart-rsyncsum\fR
704 image-info \fIimage-length image-md5sum rsyncsum-size\fR
705 .fi
707 .PP
708 Jigsaw Download was created with the format of ISO9660 CD
709 images in mind - however, the following also applies to many other
710 filesystem formats, as well as to `tar' archives and uncompressed
711 `zip' archives. A CD image contains both information for
712 organizing the filesystem (header with disc name etc., ISO9660
713 directory data, data of extensions such as Joliet or RockRidge,
714 zero padding) and the files contained on the CD. An important
715 property that jigdo relies on is that each file is stored in one
716 contiguous section of the image; it is not split into two or more
717 parts.
718 .PP
719 When \fBjigdo-file\fR is given a number of
720 files that might be contained in an image, it detects whether any
721 of the files are present using a `rolling checksum' inspired by
722 the one used by \fBrsync\fR(1)\&. The resulting data is
723 written to the `\fI\&.template\fR\&' file: If a section
724 of the image could not be matched (e.g. it was directory
725 information), the data is compressed and written directly to the
726 template. However, if a matching file was found, its data is
727 omitted from the template. Instead, only a reference (an MD5
728 checksum of the file) is inserted in the template.
729 .PP
730 Note that the template data only contains binary data, it
731 does not contain any filenames or URIs, since it cannot be easily
732 edited in case any of these values need to be changed. All that
733 information is stored in the `\fI\&.jigdo\fR\&' file, a
734 text file to which you can add URLs for your server(s). The jigdo
735 file provides a mapping for each MD5 checksum to one or more
736 alternative download locations for the corresponding part.
737 .PP
738 Apart from the mapping of MD5 sums to URIs, the jigdo file
739 also contains an URI pointing to a download location for the
740 template file. This way, the \fBjigdo\fR download
741 tool only needs to be given one URI (that of the
742 `\fI\&.jigdo\fR\&' file) to be able to download and
743 reassemble the complete image.
745 .PP
746 The overall format of `\fI\&.jigdo\fR\&' files
747 follows that of `\fI\&.ini\fR\&' files, as also used by
748 the Gnome and KDE projects for some data. The file is organized
749 into sections, each of which is preceded by a line reading
750 `[Sectionname]\&'. Within each section, lines
751 have the form `Label=Value'. Such lines are also called `entries'
752 below. All `\fI\&.jigdo\fR\&' files use UTF-8 as their
753 character encoding.
754 .PP
755 Comments are introduced with the `#\&'
756 character and extend to the end of the line. Whitespace is ignored
757 at line start and end as well as to the left and right of section
758 names and the `=\&' in entries. Furthermore, the
759 jigdo utilities split up the text of the entry value (i.e. the
760 part after the `=\&') into whitespace-separated
761 words, much like the Unix shell. Single \&'' and
762 double "" quotes can be used to prevent that
763 e.g. URIs containing whitespace are split apart. Similarly,
764 characters with special meaning (the characters
765 \&'"#\\ and space/tab) must be quoted with
766 \\ to appear in the value. As with the shell,
767 there is a difference between \&'\~\&' and
768 "\~": Within \&'\~\&',
769 the characters "#\\ and whitespace lose their
770 special meaning and become ordinary characters, whereas within
771 "\~", only the characters
772 \&'# and whitespace lose their special meaning -
773 in other words, backslash escapes still work inside
774 "\~", but not
775 \&'\~\&'\&.
776 .PP
777 `\fI\&.jigdo\fR\&' files can optionally be
778 compressed with \fBgzip\fR(1)\&. \fBjigdo-file\fR always outputs
779 uncompressed files, which you can compress yourself.
780 \fBjigdo-lite\fR supports single uncompressed and
781 compressed files.
782 .PP
783 (Behaviour which may change in the future and which should
784 not be relied upon: \fBjigdo\fR additionally supports
785 any number of concatenated plaintext and gzipped parts in the
786 files - for example, you can compress a
787 `\fI\&.jigdo\fR\&' file and then add a couple of lines
788 of uncompressed data to the end.)
789 .PP
790 In all cases, the `\fI\&.gz\fR\&' extension
791 should be removed from the filename - the tools will determine
792 automatically from the file contents whether a file is compressed
793 or not.
794 .PP
795 Below is a description of the individual section names used
796 by jigdo.
799 .nf
800 [Jigdo]
801 Version=1.1
802 Generator=jigdo-file/1.0.0
803 .fi
804 .PP
805 Information about the version of the jigdo file format
806 used, and the program that generated it. There should be one
807 such section per `\fI\&.jigdo\fR\&' file.
810 .nf
811 [Image]
812 Filename=\fI"filename for saving on user's disc"\fR
813 Template=\fI"URI where to fetch template file"\fR
814 Template-MD5Sum=OQ8riqT1BuyzsrT9964A7g
815 ShortInfo=\fIsingle-line description of the image (200 characters max.)\fR
816 Info=\fIlong description (5000 characters max.)\fR
817 .fi
818 .PP
819 The value for the `Template' entry can be either an URL
820 (absolute or relative to the URL of the jigdo file) or a string
821 of the form `\fILabel\fR:\fIpathname\fR\&' (\fBUNIMPLEMENTED\fR),
822 as described below.
823 .PP
824 The `Template-MD5Sum' entry is added by
825 \fBjigdo-file\fR and specifies the MD5 checksum of
826 the generated `\fI\&.template\fR\&' file. It is used
827 by \fBjigdo\fR to detect cases where the downloaded
828 template data is corrupted or belongs to a different
829 image.
830 .PP
831 Unlike other entry values, the values of the
832 `ShortInfo\&' and `Info\&'
833 entries are \fBnot\fR split up into words,
834 instead all quoting is preserved.
835 .PP
836 The value of the `Info\&' entry is
837 special in that \fBjigdo\fR(1) can optionally parse XML markup it contains. If
838 the markup has errors such as unbalanced/unsupported tags, the
839 string is displayed literally, without XML parsing. Supported
840 tags are <b></b> (bold),
841 <i></i> (italic),
842 <tt></tt> (typewriter font),
843 <u></u> (underline),
844 <big></big> (larger font),
845 <small></small> (smaller font)
846 and <br/> (linebreak). Supported
847 entities include &lt; (`<\&'),
848 &gt; (`>\&') and
849 &amp; (`&\&'). Note that the whole
850 `Info\&' entry must be on one line in the jigdo
851 file.
852 .PP
853 This section may occur multiple times, but all except the
854 first one will be ignored. This is useful e.g. when creating a
855 `\fI\&.jigdo\fR\&' file for a DVD image when you
856 already have `\fI\&.jigdo\fR\&' files for CDs with
857 the same content: You can simply `[Include]\&'
858 (see below) the CDs' jigdo files at the end of the DVD jigdo
859 file, after its `[Image]\&' section.
862 .nf
863 [Parts]
864 xJNkjrq8NYMraeGavUpllw=LabelA:part0
865 GoTResP2EC6Lb_2wTsqOoQ=LabelA:part1
866 kyfebwu6clbYqqWUdFIyaw=LabelB:some/path/part2
867 -J9UAimo0Bqg9c0oOXI1mQ=
868 .fi
869 .PP
870 All lines in the section, which provides the mapping from
871 MD5 checksums to URIs, have the same format: On the left side of
872 the `=\&' the checksum (encoded with a
873 Base64-like encoding) is given, and on the right a string
874 corresponding to the part with this checksum; either a complete
875 URI or a string of the form `\fILabel\fR:\fIpathname\fR\&', which is expanded into
876 one or more URIs by looking up the definition(s) for the
877 \fILabel\fR in the
878 `[Servers]\&' section.
879 .PP
880 In case a particular MD5 checksum cannot be found in any
881 `[Parts]\&' section by
882 \fBjigdo\fR, the program will perform a lookup for
883 `MD5Sum:\fI<checksum>\fR\&', e.g. for
884 `MD5Sum:xJNkjrq8NYMraeGavUpllw\&' if you
885 deleted the line for `part0' above.
886 .PP
887 A checksum appearing multiple times in this section
888 indicates alternative download locations for the part.
889 .PP
890 There may be any number of `[Parts]\&'
891 sections in the file; they are all considered when looking up
892 MD5 checksums.
893 .PP
894 \fBjigdo-file\fR always puts the
895 `[Parts]\&' section at the end of the file, and
896 it even rearranges any file specified with
897 \fB--merge\fR to have only one such section at the
898 end. This is done to allow \fBjigdo\fR to display
899 the information from the `[Image]\&' section
900 while the rest of that file is still being downloaded.
903 .nf
904 [Servers]
905 LabelA=
906 LabelA=
907 LabelB=LabelC:subdirectory/
908 LabelC=
909 .fi
910 .PP
911 All lines in the section, which provides the mapping from
912 server labels to server locations, have the same format: On the
913 left side of the `=\&' the label name is given,
914 and on the right the value to expand the label name to.
915 .PP
916 A label name appearing multiple times in this section
917 indicates alternative download locations for the parts that use
918 the label in the `[Parts]\&' section. This
919 notation makes it very easy to add mirrors to the jigdo
920 file.
921 .PP
922 As shown by the example above, the label values may
923 themselves reference other labels. In this case, the entry
924 `LabelB:some/path/part2' in the `[Parts]\&'
925 section will expand to
926 `'.
927 Loops in the label definitions result in undefined behaviour and
928 must be avoided.
929 .PP
930 There may be any number of `[Servers]\&'
931 sections in the file; they are all considered when looking up
932 labels. Either of `[Parts]\&' or
933 `[Servers]\&', but not both, can be omitted
934 from the jigdo file.
937 .nf
938 [Comment]
939 Any text, except that lines must not begin with `['.
940 .fi
941 .PP
942 All text following a `[Comment]\&' or
943 `[comment]\&' line is ignored, up to the next
944 line with a section label.
947 .nf
948 [Include http://some.url/file.jigdo]
949 .fi
950 .PP
951 Lines of this form cause the content of the specified
952 jigdo file to be downloaded and parsed just like the main jigdo
953 file. The effect will be the same as copying the included file's
954 contents into the file which contains the include
955 directive. (Exception: Any relative URLs are always resolved
956 using the URL of the `\fI\&.jigdo\fR\&' file that
957 contains that relative URL.)
958 .PP
959 The URL argument can be an absolute or relative URL. 
960 Relative URLs are assumed to be relative to the URL of the jigdo
961 file which contains the include directive. Includes can be
962 nested, but it is an error to create a loop of include
963 directives. It is \fBnot\fR possible to use URLs
964 of the form `\fILabel\fR:\fIpathname\fR\&'.
965 .PP
966 The URL cannot be quoted with "". Any
967 `]\&' characters in the argument must be
968 escaped as `%5D\&', and any spaces as
969 `%20\&'.
970 .PP
971 Include directives are only supported by
972 \fBjigdo\fR, they are ignored by
973 \fBjigdo-lite\fR\&.
974 .PP
975 An include directive terminates any previous section, but
976 it does not start a new one. In other words, a new section must
977 always be started after the include line,
978 \fBjigdo\fR does not allow normal entries to appear
979 below the `[Include]\&'.
981 .PP
982 Any file specified with the \fB--cache\fR option
983 is used to store information about the
984 \fIFILES\fR presented to
985 \fBjigdo-file\fR\&. When querying the cache, a file is
986 considered unchanged (and the cached data is used) only if
987 filename, file size and last modification time (mtime) match
988 exactly. For the filename match, not the entire file name is used,
989 but only the part following any `//\&', so that
990 any changes to the part before the `//\&' will
991 not invalidate the cache.
992 .PP
993 Old cache entries are removed from the cache if they have
994 not been read from or written to for the amount of time specified
995 with \fB--cache-expiry\fR\&. Entries are
996 \fBnot\fR immediately removed from the cache if the
997 file they refer to no longer exists - this makes it possible to
998 cache information about files on removable media.
999 .PP
1000 Cache expiry only takes place \fBafter\fR
1001 \fBjigdo-file\fR has done its main work - if any old
1002 entries are accessed before expiry takes place, they will be kept.
1003 For example, if the program is run using the default expiry time
1004 of 30 days, but accesses a cache file with entries generated 2
1005 months ago, then entries in that cache \fBwill\fR
1006 be considered, and only those cache entries that were not needed
1007 during the program run will be expired.
1008 .PP
1009 Due to a peculiarity of the underlying database library
1010 (libdb3), cache files never shrink, they only grow. If a large
1011 number of entries was expired from your cache file and you want it
1012 to shrink, you can either just delete it (of course then
1013 everything will have to be regenerated) or use the utilities
1014 accompanying libdb3 to dump and restore the database, with a
1015 command like `\fBdb3_dump
1016 \fIold-cache.db\fB | db3_load
1017 \fInew-cache.db\fB\fR\&'. For Debian, these programs are supplied in the
1018 package `libdb3-util'.
1019 .PP
1020 If a different \fB--md5-block-size\fR is
1021 specified, the entire file needs to be re-read to update its cache
1022 entry. If a different \fB--min-length\fR is specified,
1023 only the first `md5-block-size' bytes of the file need to be
1024 re-read.
1027 .PP
1028 You have created a CD image
1029 `\fIimage.iso\fR\&' from some of the files stored
1030 in the directory `\fI/home/ftp\fR\&' on your
1031 harddisc, which is also available online as `'.
1032 As you don't want to waste space by effectively hosting the same
1033 data twice (once as files on the FTP server, once inside the
1034 image), and you are fed up with users' downloads aborting after
1035 200MB and their restarting the download dozens of times, you
1036 decide to use jigdo. How do you prepare the image for
1037 download?
1038 .PP
1039 In fact, only one command is necessary:
1040 .sp
1041 .RS
1042 .PP
1043 \fBjigdo-file make-template
1044 --image=image.iso --jigdo=/home/ftp/image.jigdo
1045 --template=/home/ftp/image.template /home/ftp// --label
1046 Mysite=/home/ftp --uri
1047 Mysite=\fR
1048 .RE
1049 .PP
1050 People can now point \fBjigdo\fR at
1051 `' to download your image. The
1052 template file needs to be accessible as
1053 `'.
1054 .PP
1055 Note that nothing prevents you from doing the same for an
1056 FTP server that isn't administrated by you - in that case, you
1057 only need to host the `\fI\&.jigdo\fR\&' and
1058 `\fI\&.template\fR\&' files on your own
1059 server/homepage.
1061 .PP
1062 We assume that you have a large file that is not a
1063 filesystem, e.g. `\fImovie.mpeg\fR\&'. Because of
1064 space problems, you want to distribute the data on two
1065 servers.
1066 .PP
1067 In this case, the parts of the image need to be generated
1068 artificially with the \fBsplit\fR command. For
1069 example, to create chunks of 4MB each, use `\fBsplit -b 4m
1070 movie.mpeg part\fR\&'. Copy the resulting files
1071 `\fIpartXX\fR\&' into
1072 two directories `\fI1\fR\&' and
1073 `\fI2\fR\&' that you create, according to how you
1074 want the files distributed between the servers. Next, create the
1075 jigdo and template files with `\fBjigdo-file make-template
1076 --image=movie.mpeg 1// 2//\fR\&'. You will need to edit the
1077 `\fI\&.jigdo\fR\&' file and provide the right URIs
1078 for the two servers that you are going to upload the
1079 `\fIpartXX\fR\&' files
1080 to.
1082 .PP
1083 Because it is possible to assign a different URI for each
1084 part of an image if necessary, jigdo is very flexible. Only one
1085 example is the possibility of customized versions of images:
1086 Suppose that someone is distributing a CD image, and that you
1087 want to make a few small changes to it and redistribute your own
1088 version. You download the `\fIofficial.iso\fR\&' CD
1089 image with \fBjigdo\fR (passing it the URL of
1090 `\fIofficial.jigdo\fR\&'), write it to CD-R, make
1091 your changes (say, adding files from the
1092 `\fImyfiles\fR\&' directory on your harddisc) and
1093 produce your own version, `\fImyversion.iso\fR\&'.
1094 Next, you instruct \fBjigdo-file\fR to create the
1095 jigdo and template files for your modified image, using the
1096 command
1097 .sp
1098 .RS
1099 .PP
1100 \fBjigdo-file make-template
1101 --image=myversion.iso /mnt/cdrom/ myfiles// --label
1102 My=myfiles/ --uri My=
1103 --merge=official.jigdo\fR
1104 .RE
1105 while `\fIofficial.iso\fR\&' is mounted under
1106 `\fI/mnt/cdrom\fR\&'. By using
1107 \fB--merge\fR, you have told
1108 \fBjigdo-file\fR to take the contents of
1109 `\fIofficial.jigdo\fR\&', add to it a new
1110 `[Image]\&' section for
1111 `\fImyversion.iso\fR\&' and write the resulting
1112 jigdo file to `\fImyversion.jigdo\fR\&' - so now
1113 `\fImyversion.jigdo\fR\&' offers two images for
1114 download, the original version and your modified version. (If
1115 you do not want it to offer the official version, edit it and
1116 remove the `[Image]\&' section that lists
1117 `\fIofficial.iso\fR\&'.)
1118 .PP
1119 Now you can upload the `\fI\&.jigdo\fR\&' file,
1120 the `\fI\&.template\fR\&' file and also the files in
1121 `\fImyfiles\fR\&' to `'.
1122 Thus, for people to download your modified image, you do
1123 \fBnot\fR need to upload the complete image
1124 contents to your web space, but only the changes you
1125 made!
1126 .PP
1127 (In case you only made very few changes, you could also
1128 omit the `myfiles' parameter in the command above, then all your
1129 changes end up in the new template file.)
1131 .PP
1132 It is also no problem to combine data from several sources
1133 that use jigdo. For example, if of five different and unrelated
1134 servers each one distributes a different CD image via jigdo, you
1135 can create a customized DVD image that contains the data from
1136 all these CDs. When people use \fBjigdo\fR to
1137 download your image, the individual files on the DVD are fetched
1138 from the same sources as the original CDs.
1139 .PP
1140 Consequently, even though you will be distributing a 3.2GB
1141 file via your web space, the actual amount of data that is
1142 stored on your server will only be in the order of several
1143 MBs.
1144 .SH "BUGS"
1145 .PP
1146 For certain contents of one of the input files, most notably
1147 a sequence of zero bytes longer than \fB--min-length\fR
1148 at the start of the file and an area of zeros preceding the file
1149 data in the image, \fBjigdo-file make-template\fR may
1150 fail to find the file in the image. Unfortunately, this
1151 restriction cannot be avoided because the program could become
1152 very slow otherwise. If you use the \fB--debug\fR
1153 option, all instances of \fBjigdo-file\fR discarding
1154 possible matches are indicated by lines containing the word
1155 `DROPPED\&'.
1156 .PP
1157 In fact, not only all-zeroes files trigger this behaviour,
1158 but also files which contain at their start a long sequence of
1159 short identical strings. For example, both a file containing only
1160 `a\&' characters and one containing
1161 `abcabcabcabc\&...' are problematic.
1162 .SH "SEE ALSO"
1163 .PP
1164 \fBjigdo\fR(1) (NOT YET IMPLEMENTED),
1165 \fBjigdo-lite\fR(1),
1166 \fBjigdo-mirror\fR(1),
1167 \fBsplit\fR(1) (or `\fBinfo split\fR\&'),
1168 \fBfind\fR(1) (or `\fBinfo find\fR\&'),
1169 \fBmkisofs\fR(1),
1170 \fBmd5sum\fR(1)
1171 .SH "AUTHOR"
1172 .PP
1173 Jigsaw
1174 Download <URL:> was written by Richard Atterer
1175 <jigdo>, to make downloading of CD ROM
1176 images for the Debian Linux distribution more convenient.