1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 <TITLE>jigdo-file</TITLE><META NAME="GENERATOR" CONTENT="Modular DocBook
6 HTML Stylesheet Version 1.79"></HEAD>
7 <BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF"
8 VLINK="#840084" ALINK="#0000FF">
9 <H1><A NAME="AEN1"></A>jigdo-file</H1>
10 <DIV><A NAME="AEN14"></A>
11 <H2>Name</H2>jigdo-file -- Prepare files for Jigsaw Download
12 (distribution of huge files, e.g. CD images).</DIV>
13 <DIV><A NAME="AEN17"></A>
15 <P><B>jigdo-file</B> { <TT><I> COMMAND</I></TT> } [<CODE>--image=<TT><I
16 >cdrom.iso</I></TT></CODE>] [<CODE>--jigdo=<TT><I>cdrom.jigdo</I></TT
17 ></CODE>] [<CODE>--template=<TT><I>cdrom.template</I></TT></CODE>]
18 [<CODE>--force</CODE>] [MORE OPTIONS] [<TT><I>FILES</I></TT> | <CODE
19 >--files-from=<TT><I>f</I></TT></CODE>]<BR> Common COMMANDs:
20 make-template, make-image, verify </P></DIV>
21 <DIV><A NAME="DESCRIPTION"></A>
23 <P>Jigsaw Download, or short jigdo, is a scheme developed primarily to
24 make it easy to distribute huge filesystem images (e.g. CD (ISO9660) or
25 DVD (UDF) images) over the internet, but it could also be used for
26 other data which is awkward to handle due to its size, like audio/video
27 files or large software packages.</P>
28 <P>jigdo tries to ensure that the large file (always called <I>image</I
29 > from now on) is downloaded in small parts which can be stored on
30 different servers. People who want to download the image do so by
31 telling the <SPAN><SPAN>jigdo</SPAN>(1)</SPAN> <SPAN><I>(NOT
32 IMPLEMENTED YET)</I></SPAN> download tool to process one `<TT
33 >.jigdo</TT>' file; using it, <B>jigdo</B> downloads the parts and
34 reassembles the image. <B>jigdo-file</B> is used to prepare the files
36 <P>What makes jigdo special is that the parts that are used to
37 reconstruct the image can have any size and content - they only need to
38 be contained in a contiguous region anywhere in the image.</P>
39 <P>For example, if you wish to distribute an ISO9660 image which
40 contains a snapshot of an FTP server, you can instruct <B
41 >jigdo-file</B> to prepare the download data in such a way that when
42 people use <B>jigdo</B> to download the image, <B>jigdo</B> actually
43 fetches the individual files from the FTP server and assembles them
44 into an exact copy of your image - during the download! (If the image
45 is not a filesystem dump, you can use <SPAN><SPAN>split</SPAN
46 >(1)</SPAN> to create the small parts that the image will be
47 reassembled from.)</P>
48 <P>You are completely free to choose where the individual parts of the
49 image are stored: They may be in entirely different directories on
50 different servers (e.g. because of storage/bandwidth constraints), but
51 this is invisible to the people downloading your image. The information
52 about available servers only needs to be added to the `<TT>.jigdo</TT
53 >' file by you before distributing it.</P>
54 <P>The `DETAILS' section below contains technical details on how jigdo
55 works. The `EXAMPLES' section lists a number of common scenarios and
56 may help you to get an idea of what jigdo is useful for.</P></DIV>
57 <DIV><A NAME="OPTIONS"></A>
59 <P>Many options are specific to a particular <TT><I>COMMAND</I></TT>;
60 the ones below are general or used by several commands. Further options
61 are listed below with the individual commands. All options are silently
62 ignored if they are not applicable to the current command. For any <TT
63 ><I>BYTES</I></TT> parameters to options, you can append one of the
64 letters `k', `M' or `G' to the amount you specify, to indicate
65 kilobytes, megabytes or gigabytes.</P>
69 <DT><CODE>-h</CODE> <CODE>--help</CODE></DT>
71 <P>Output short summary of commands and options.</P></DD>
72 <DT><CODE>-H</CODE> <CODE>--help-all</CODE></DT>
74 <P>Output complete summary of commands and options.</P></DD>
75 <DT><CODE>-v</CODE> <CODE>--version</CODE></DT>
77 <P>Output program version.</P></DD>
78 <DT><CODE>-i</CODE> <CODE>--image=<TT><I>cdrom.iso</I></TT></CODE
81 <P>Specify location of the file containing the image. The image is
82 the large file that you want to distribute.</P></DD>
83 <DT><CODE>-j</CODE> <CODE>--jigdo=<TT><I>cdrom.jigdo</I></TT></CODE
86 <P>Specify location of the Jigsaw Download description file. The
87 jigdo file is a human-readable file generated by <B>jigdo-file</B>,
88 to which you add information about all the servers you are going to
89 upload the files to. <B>jigdo</B> will download this file as the
90 first step of retrieving the image.</P></DD>
91 <DT><CODE>-t</CODE> <CODE>--template=<TT><I>cdrom.template</I></TT
94 <P>Specify location of the image `template' file. The template file
95 is a binary file generated by <B>jigdo-file</B>, it contains
96 information on how to reassemble the image and also (in compressed
97 form) all the data from the image which was not found in any of the
99 <P>Depending on the command, each of these three files is used
100 sometimes for input, sometimes for output. If the file is to be used
101 for output for a particular command and the output file already
102 exists, <B>jigdo-file</B> exits with an error, unless <CODE
103 >--force</CODE> is present.</P>
104 <P>In most cases, you will only need to specify one out of <CODE
105 >-i</CODE> <CODE>-j</CODE> <CODE>-t</CODE>, because any missing
106 filenames will be deduced from the one you specify. This is done by
107 first stripping any extension from the supplied name and then
108 appending nothing (if deducing <CODE>--image</CODE>), `<TT
109 >.jigdo</TT>' or `<TT>.template</TT>'.</P></DD>
110 <DT><CODE>-r</CODE> <CODE
111 >--report=default|noprogress|quiet|grep</CODE></DT>
113 <P>Control how verbose the program is, and what format the output
114 has: <CODE>noprogress</CODE> is the same as <CODE>default</CODE>
115 except that no `<SAMP>x% done</SAMP>' progress messages are printed.
116 <CODE>quiet</CODE> restricts the output to what is absolutely
117 necessary, mostly error messages. <CODE>grep</CODE> is only
118 different from <CODE>default</CODE> for the <B>make-template</B>
119 command: It enables output in a simple `<TT><I><offset>
120 <file></I></TT>' format which is useful when searching for
121 binary files in other binary files.</P></DD>
122 <DT><CODE>-f</CODE> <CODE>--force</CODE></DT>
124 <P>Overwrite existent output files without complaining.</P></DD>
125 <DT><CODE>--no-force</CODE></DT>
127 <P><SPAN><I>This is the default.</I></SPAN> Refuse to overwrite
128 existent output files.</P></DD>
129 <DT><CODE>-c</CODE> <CODE>--cache=<TT><I>jigdo-cache.db</I></TT
132 <P><B>jigdo-file</B> usually needs to read the entire contents of all
133 the <TT><I>FILES</I></TT> you specify. If you use it repeatedly
134 (e.g. because you make a new CD image available daily), caching the
135 file information will increase the program's speed significantly.
136 The cache file is automatically created if it is not yet present.
137 Data is usually both read from and written to it.</P></DD>
138 <DT><CODE>--no-cache</CODE></DT>
140 <P><SPAN><I>This is the default.</I></SPAN> Do not use a cache.</P
142 <DT><CODE>--cache-expiry=<TT><I>SECONDS</I></TT></CODE></DT>
144 <P>Set maximum age of cache entries. Any entries older than this will
145 be removed from the cache. The default is 30 days. You can append
146 one of the letters `h', `d', `w', `m', `y' to denote hours, days,
147 weeks, months or years, respectively. A value of `0' or `off'
148 disables expiry, so that all entries will stay in the cache forever.
149 See the section `CACHE FILES' below for more information.</P></DD>
150 <DT><CODE>--readbuffer=<TT><I>BYTES</I></TT></CODE></DT>
152 <P>Set size of internal buffers. The default is 128k - if you have a
153 fast disc, increasing this value may make <B>jigdo-file</B> faster,
154 but in general, changing it is not necessary.</P></DD>
155 <DT><CODE>--md5-block-size=<TT><I>BYTES</I></TT></CODE></DT>
157 <P><SPAN><I>Uninteresting internal parameter.</I></SPAN> Set size of
158 blocks into which files are subdivided. The default is 128k. If you
159 change it, any cache file will have to be regenerated. Internally,
160 <B>jigdo-file</B> may choose to use a slightly larger or smaller
162 <DT><CODE>-T</CODE> <CODE>--files-from=<TT><I>file</I></TT></CODE
165 <P>Read file and directory names from the specified file. If <TT><I
166 >file</I></TT> is `-', read names from standard input. Each line in
167 the file is taken as a name, so the names may contain spaces, but
168 not newline characters. An empty line causes <B>jigdo-file</B> to
169 stop reading from the file.</P>
170 <P><SPAN><SPAN>find</SPAN>(1)</SPAN> is a powerful tool for
171 generating file lists, but make sure to use `<B>find -type f</B>' if
172 possible - otherwise, if you instruct <B>find</B> to output both a
173 filename and a symlink to that filename, <B>jigdo-file</B> will read
174 the file contents twice.</P></DD>
175 <DT><CODE>--hex</CODE></DT>
177 <P>Output checksums in hexadecimal instead of Base64-like format.
178 This should not be used with the <B>make-template</B> command,
179 because the resulting `<TT>.jigdo</TT>' file violates the `<TT
180 >.jigdo</TT>' file format. Its intended use is to make <B
181 >jigdo-file</B> more interoperable with other Unix shell utilities
182 like <SPAN><SPAN>md5sum</SPAN>(1)</SPAN>.</P></DD>
183 <DT><CODE>--no-hex</CODE></DT>
185 <P><SPAN><I>This is the default.</I></SPAN> Use jigdo's own
186 Base64-like encoding of checksums.</P></DD>
187 <DT><CODE>--debug</CODE>[<SPAN>=<TT>help</TT>|=<TT>all</TT>|=<TT><I
188 >UNIT,~UNIT...</I></TT> </SPAN>]</DT>
190 <P>Switch on or off debugging output. Just `--debug' is equivalent to
191 `--debug=all'. The argument is a comma-separated list of unit names
192 for which debugging output is to be enabled, or disabled if the name
193 is preceded by `~'. The special name `all' means all units. By
194 default, debugging output is switched off except for the units
195 `assert' and `general'. The exact list of available units for which
196 debugging can be switched on depends on whether jigdo was compiled
197 with debugging support - the list can be printed with
198 `--debug=help'.</P></DD>
199 <DT><TT><I>FILES</I></TT></DT>
201 <P>Names of files or directories to use as input. These are the parts
202 that are contained in the image. In case one of the names is a
203 directory, the program recursively scans the directory and adds all
204 files contained in it. While doing this, it follows symbolic links,
205 but avoids symlink loops.</P>
206 <P>If one of the filenames starts with the character `-', you must
207 precede the list of files with `--'. A value of `-' has <SPAN><I
208 >no</I></SPAN> special meaning in this list, it stands for a file
209 whose name is a single hyphen.</P></DD></DL></DIV></DIV>
210 <DIV><A NAME="COMMANDS"></A>
212 <P>The command name is the first non-option argument passed to <B
213 >jigdo-file</B>. Most commands have short abbreviations as well as long
214 names. <SPAN><I>The short command names should not be used in scripts -
215 there may be incompatible changes to them in the future!</I></SPAN></P
217 <DIV><A NAME="MAKE-TEMPLATE"></A>
218 <H3><B>make-template</B>, <B>mt</B></H3>
219 <P>Reads <TT><I>image</I></TT> and <TT><I>FILES</I></TT>, creates `<TT
220 >.jigdo</TT>' and `<TT>.template</TT>'. This is the main functionality
221 of <B>jigdo-file</B>.</P>
222 <P>It is possible to specify both <CODE>--image=-</CODE> and <CODE
223 >--files-from=-</CODE>. In this case, first the list of files is read
224 from standard input until an empty line is encountered. Everything
225 following it is assumed to be the image data. This can be useful if
226 you use <SPAN><SPAN>mkisofs</SPAN>(1)</SPAN> or similar programs that
227 can output the complete image on their standard output, because there
228 is no need to store the image on disc temporarily.</P>
229 <P>If a <TT><I>FILES</I></TT> argument contains the characters `<TT
230 >//</TT>' (Unix) or `<TT>\.\</TT>' (Windows), this has special
231 meaning. In the final jigdo file that users will download, each of the
232 parts is referenced in the `<TT>[Parts]</TT>' section with a URI of
233 the form `Label:some/filename'. (See `FORMAT OF .JIGDO FILES' below
234 for a detailed description.) The `<TT>[Servers]</TT>' section gives a
235 mapping of labels to servers on the internet, with lines like
236 `Label=http://myserver.org/jigdofiles/'. Using this information, <B
237 >jigdo</B> will create the final download URI for the part,
238 `http://myserver.org/jigdofiles/some/filename'. Specifying `<TT
239 >//</TT>' (or `<TT>\.\</TT>') in a file or directory name serves to
240 `cut off' the names at the right directory level. For example, if the
241 Unix path of one of your <TT><I>FILES</I></TT> is
242 `/path/some/filename', you can tell <B>jigdo-file</B> to cut off after
243 the `/path' by passing it the argument `/path//some/filename', or
244 `/path//' if you want the whole directory scanned. The path names need
245 not be absolute; `somedirectory//' is also possible.</P>
249 <DT><CODE>--label <TT><I>Label=/path</I></TT></CODE></DT>
251 <P>Specify a name to use as the label name for a path on disc.
252 (Influences the output jigdo file.) If you used `<TT>//</TT>' in
253 the <TT><I>FILES</I></TT> arguments as described above, <B
254 >jigdo-file</B> will by default pick label names automatically
255 (`A', `B' etc.). With this option, you can give labels more
256 meaningful names. Note that the label name will only be used if one
257 or more <TT><I>FILES</I></TT> begin with `/path//'.</P>
258 <P>Try to use label names that start with uppercase characters, to
259 disambiguate them clearly from protocol names like `http',
261 <DT><CODE>--uri <TT><I>Label=http://some.server.org/</I></TT></CODE
264 <P>By default, using <CODE>--label</CODE> as described above will
265 cause lines of the form `Label=file:/path/' to be written to the
266 `<TT>[Servers]</TT>' section of the output jigdo file. If you want
267 to override the `file:' URI so that the line reads
268 `Label=http://some.server.org/', you can do so by specifying <CODE
269 >--uri</CODE> along with <CODE>--label</CODE>. Giving just <CODE
270 >--uri <TT><I>Label=...</I></TT></CODE> without the corresponding
271 <CODE>--label <TT><I>Label=...</I></TT></CODE> has no effect, and
272 even if you specify both, an entry is only added to the `<TT
273 >[Servers]</TT>' section if the label is referenced by at least one
274 `<TT>[Parts]</TT>' entry.</P>
275 <P>The supplied value is not quoted by the program; if it contains
276 characters such as space or any of the characters <TT>#"'\</TT>
277 then you must quote it. (Under Unix, you may need to quote the
278 value twice to also protect it from the shell, e.g. <TT>\\\\</TT>
279 or <TT>'\\'</TT> to get a single backslash in the URI.)</P>
280 <P>The mapping specified with an <CODE>--uri</CODE> option is
281 ignored if it is already present in the output jigdo file.</P>
282 <P>Users of the Windows version may notice that the `<TT>\</TT>'
283 directory separators are converted into `<TT>/</TT>' in the `file:'
284 URIs that are generated by default. This is done to increase
285 cross-platform compatibility of `file:' - the <B>print-missing</B>
286 command of the Windows version will automatically re-convert the
287 characters when it prints the URIs. In case you supply your own
288 `file:' URIs under Windows using <CODE>--uri</CODE>, you must also
289 exchange `<TT>/</TT>' and `<TT>\</TT>'.</P></DD>
290 <DT><CODE>-0</CODE> to <CODE>-9</CODE></DT>
292 <P>Set amount of compression in the output template file, from <CODE
293 >-0</CODE> (no compression) to <CODE>-9</CODE> (maximum
294 compression). The default is <CODE>-9</CODE>, which can make the
295 template generation quite slow. By default, the compression
296 algorithm used is the same as for <SPAN><SPAN>gzip</SPAN>(1)</SPAN
298 <DT><CODE>--gzip</CODE> and <CODE>--bzip2</CODE></DT>
300 <P>Choose between the gzip and bzip2 compression algorithms. The
301 default is gzip. Bzip2 usually gives a better compression ratio,
302 but compression is significantly slower than with gzip.</P></DD>
303 <DT><CODE>--min-length=<TT><I>BYTES</I></TT></CODE></DT>
305 <P>Set minimum length of a part for <B>jigdo-file</B> to look for it
306 in the image. The default is 1k. Parts smaller than this will never
307 be found in the image, so their data will be included in the
308 template file. The search algorithm used requires such a minimum
309 length, otherwise template generation could become extremely slow.
310 If you know for sure that all your <TT><I>FILES</I></TT> are larger
311 than a certain amount, you can increase <B>jigdo-file</B>'s speed
312 slightly by specifying the amount with this option. There is a
313 hard-wired absolute minimum of 256 bytes - anything lower will
314 silently be set to 256.</P></DD>
315 <DT><CODE>--merge=<TT><I>FILE</I></TT></CODE></DT>
317 <P>Include the contents of <TT><I>FILE</I></TT> in the output `<TT
318 >.jigdo</TT>' file. The file can contain data which you want added
319 to the output (for example, a `<TT>[Servers]</TT>' section with a
320 list of your servers as entries), or it can be the jigdo file
321 output by an earlier run of <B>jigdo-file</B>.</P>
322 <P>It is possible to specify the same file for input with <CODE
323 >--merge</CODE> and for output with <CODE>--jigdo</CODE>. However,
324 you will also need to use <CODE>--force</CODE> to make the program
325 overwrite the old version of the jigdo file with the new one. <TT
326 ><I>FILE</I></TT> can be `-' for standard input.</P>
327 <P>When <SPAN><I>adding</I></SPAN> new information to the supplied
328 file, <B>jigdo-file</B> will not insert new lines into the `<TT
329 >[Parts]</TT>' section if an entry for the same MD5 checksum (but
330 not necessarily with the same URI!) already exists, and it will not
331 insert new lines into the `<TT>[Servers]</TT>' section if a
332 completely identical entry already exists.</P>
333 <P>When <SPAN><I>reading in</I></SPAN> the existing <TT><I>FILE</I
334 ></TT>, the behaviour is slightly different: The program <SPAN><I
335 >preserves</I></SPAN> entries in the `<TT>[Parts]</TT>' section
336 with identical checksum, but different URIs. For completely
337 identical entries (same checksum and URI), only one entry is
338 preserved and the duplicates are removed. The `<TT>[Servers]</TT>'
339 section is left untouched.</P></DD>
340 <DT><CODE>--image-section</CODE></DT>
342 <P><SPAN><I>This is the default.</I></SPAN> Causes <B>jigdo-file</B
343 > to add an `<TT>[Image]</TT>' section to the `<TT>.jigdo</TT>'
345 <P>As an exception, a new `<TT>[Image]</TT>' section is <SPAN><I
346 >not</I></SPAN> added if you use <CODE>--merge</CODE> and the file
347 to merge contains an `<TT>[Image]</TT>' section with a line which
348 reads `<TT>Template-MD5Sum=</TT>' (end of line after the `='). In
349 this case, the generated template data's MD5 checksum value is just
350 added after the `=' of the first line of this form in the file - no
351 whole new `<TT>[Image]</TT>' section is appended. This behaviour is
352 useful because it allows you to pass via <CODE>--merge</CODE> an
353 `<TT>[Image]</TT>' section with arbitrary content and then have the
354 MD5 checksum automatically added by <B>jigdo-file</B>. The section
355 `FORMAT OF .JIGDO FILES' below explains the `<TT>[Image]</TT>'
356 section contents in greater detail.</P></DD>
357 <DT><CODE>--no-image-section</CODE></DT>
359 <P>Do <SPAN><I>not</I></SPAN> include an `<TT>[Image]</TT>' section
360 in the `<TT>.jigdo</TT>' file. You need to add one yourself if you
361 use this option. However, doing that is not easy (you also need to
362 add a `<TT>Template-MD5Sum</TT>' line with the correct checksum, or
363 <B>jigdo</B> will complain), so use of this option is
364 discouraged.</P></DD>
365 <DT><CODE>--servers-section</CODE></DT>
367 <P><SPAN><I>This is the default.</I></SPAN> Causes <B>jigdo-file</B
368 > to add a `<TT>[Servers]</TT>' section to the `<TT>.jigdo</TT>'
369 file. This default section uses `file:' URIs, which allows for
370 immediate reassembly of the image from the local filesystem, and is
371 also useful if you want to edit the file manually and replace the
372 `file:' URIs with other URIs.</P></DD>
373 <DT><CODE>--no-servers-section</CODE></DT>
375 <P>Do <SPAN><I>not</I></SPAN> add a `<TT>[Servers]</TT>' section at
376 the end of the `<TT>.jigdo</TT>' file. Useful e.g. if you are going
377 to append the section with a script.</P></DD>
378 <DT><CODE>--match-exec=<TT><I>SHELLCOMMAND</I></TT></CODE></DT>
380 <P>Whenever a file is found in the image, execute the supplied
381 command string by passing it to a shell. <B>jigdo-file</B> sets up
382 a number of environment variables with information about the file
383 match. For example, if the file `<TT>/path//a/b/file</TT>' was
384 found in the image and `Label:a/b/file' is going to be written to
385 the `<TT>.jigdo</TT>' file:
387 <P><CODE>LABEL</CODE>="<TT>Label</TT>" - Name of the label for the
388 file. The example assumes that `<CODE>--label</CODE> <TT
389 >Label=/path</TT>' was specified by you. In the absence of such an
390 option, <CODE>LABEL</CODE> will be set but empty.</P></LI><LI>
391 <P><CODE>LABELPATH</CODE>="<TT>/path/</TT>" - The path
392 corresponding to the label, or in other words, the prefix of the
393 matched file's path that will <SPAN><I>not</I></SPAN> appear in
394 the output `<TT>.jigdo</TT>' file. Is set even without any `<CODE
395 >--label</CODE>' option present. Ends with a slash.</P></LI><LI>
396 <P><CODE>MATCHPATH</CODE>="<TT>a/b/</TT>" - The rest of the path,
397 without the leafname of the matched file. Is either empty or ends
398 with a slash.</P></LI><LI>
399 <P><CODE>LEAF</CODE>="<TT>file</TT>" - The leafname of the matched
401 <P><CODE>MD5SUM</CODE>="<TT>lNVdUSqbo2yqm33webrhnw</TT>" - The
402 md5sum of the matched file, in Base64-like format.</P></LI><LI>
403 <P><CODE>FILE</CODE>="<TT>/path//a/b/file</TT>" - For convenience,
404 the complete path of the file. The variable is always set to <TT
405 >$LABELPATH$MATCHPATH$LEAF</TT>.</P></LI></UL> </P>
406 <P>Please be careful to correctly quote the string passed to this
407 option, otherwise your supplied command will not work with
408 filenames that contain spaces. As an example, to create a backup of
409 hard links to the matched files, use the following option: <TT
410 >--match-exec='mkdir -p "${LABEL:-.}/$MATCHPATH" && ln -f
411 "$FILE" "${LABEL:-.}/$MATCHPATH$LEAF"'</TT> </P>
412 <P>By default, no command is executed. Use --match-exec="" to remove
413 a command string which was set with an earlier use of this
415 <DT><CODE>--greedy-matching</CODE></DT>
417 <P><SPAN><I>This is the default.</I></SPAN> Imagine that your image
418 contains a <TT>.tar</TT> file which in turn contains another file
419 <TT>x</TT>, and that you provide both the <TT>.tar</TT> and the
420 files inside it on the command line. When <B>jigdo-file</B> scans
421 the image, it encounters the beginning of the <TT>.tar</TT> file,
422 and then the file <TT>x</TT>.</P>
423 <P>At this point, a decision must be made: Should the smaller file
424 <TT>x</TT> be recorded as matched, or should it be ignored in
425 favour of the larger (and thus better) match of the <TT>.tar</TT>
426 file? Unfortunately, at this point it is not clear whether there
427 will actually be a full match of the <TT>.tar</TT>, so by default,
428 the program prefers the small match.</P></DD>
429 <DT><CODE>--no-greedy-matching</CODE></DT>
431 <P>In the case where a large partial match is present and a shorter
432 match has been confirmed, ignore the small match. (See the option
433 above.)</P></DD></DL></DIV></DIV>
434 <DIV><A NAME="MAKE-IMAGE"></A>
435 <H3><B>make-image</B>, <B>mi</B></H3>
436 <P>Reads `<TT>.template</TT>' and <TT><I>FILES</I></TT>, creates <TT
437 ><I>image</I></TT> (or `<TT>imagename.tmp</TT>'). Provides a
438 rudimentary way of reassembling images - <B>jigdo</B> is usually
439 better suited for this task. However, in contrast to <B>jigdo</B>, no
440 `<TT>.jigdo</TT>' file is required.</P>
441 <P>If the image is to be written to a file (and not to standard
442 output), it is possible to create the image in several steps, with
443 several invocations of `<B>jigdo-file make-image</B>', as follows: You
444 first invoke <B>jigdo-file</B>, specifying as many files as are
445 available at this time. The program scans the files, and those that
446 are contained in the image are copied to a temporary file, whose name
447 is formed by appending `<TT>.tmp</TT>' to the image filename.</P>
448 <P>For all further files which could be parts of the image, you repeat
449 this process. As soon as all parts are present, the temporary file
450 will be truncated slightly (to delete some administrative data that <B
451 >jigdo-file</B> appends at the end) and renamed to the final image
452 name. The possibility of reassembling the image in several steps is
453 especially useful for gathering files from removable media, e.g.
454 several older CDs.</P>
455 <P>Scripts using <B>make-image</B> can detect whether image creation is
456 complete by checking the exit status: 0 signals successful creation,
457 whereas 1 means that more files need to be supplied. Other errors
458 result in an exit status of 2 (`recoverable', e.g. file not found) or
459 3 (non-recoverable, e.g. write error).</P>
463 <DT><CODE>--check-files</CODE></DT>
465 <P><SPAN><I>This is the default.</I></SPAN> Whenever any part is
466 copied to the image, re-check its checksum against the checksum
467 stored in the template. It is recommended that you leave this
468 switched on, even if it slows down image creation a bit.</P></DD>
469 <DT><CODE>--no-check-files</CODE></DT>
471 <P>Do not check files' checksums when copying them to the image.
472 This can be safely used when no cache file is used (which means
473 that files will be written to the image immediately after being
474 scanned) or the whole image is checked later with the <B>verify</B
475 > command.</P></DD></DL></DIV></DIV>
476 <DIV><A NAME="PRINT-MISSING"></A>
477 <H3><B>print-missing</B>, <B>pm</B></H3>
478 <P>Reads `<TT>.jigdo</TT>', `<TT>.template</TT>' and (if present) `<TT
479 >imagename.tmp</TT>', outputs a list of URIs still needed to
480 completely reassemble the image.</P>
481 <P>Together with the <B>make-image</B> command, this provides most of
482 the functionality of <B>jigdo</B> on the command line.</P>
483 <P>For each part that is not yet present in the temporary image file,
484 the file checksum is looked up in the `<TT>[Parts]</TT>' section of
485 the jigdo file. Any label in the corresponding entry is then expanded
486 according to the label definitions in the `<TT>[Servers]</TT>' section
487 and printed on standard output. <B>jigdo</B> allows you to specify
488 several alternative locations for each label in this section, but <B
489 >print-missing</B> will only output the first one for each missing
491 <P>If the checksum cannot be found in the `<TT>[Parts]</TT>' section
492 (this Should Not Happen unless you deleted that section), a lookup is
493 instead made for `MD5Sum:<TT><I><checksum></I></TT>', just like
494 with <B>jigdo</B>. (Thus, if you want to get rid of the `<TT
495 >[Parts]</TT>' section, you can do so if you rename each part to its
500 <DT><CODE>--uri <TT><I>Label=http://some.server.org/</I></TT></CODE
503 <P>Override the entries in the `<TT>.jigdo</TT>' file for any label
504 with a URI of your choice. With the example above, a `<TT
505 >[Parts]</TT>' entry of `Label:some/filename' will cause the line
506 `http://some.server.org/some/filename' to be printed.</P>
507 <P>The supplied value is not quoted by the program; if it contains
508 characters such as space or any of the characters <TT>#"'\</TT>
509 then you must quote it. (Under Unix, you may need to quote the
510 value twice to also protect it from the shell, e.g. <TT>\\\\</TT>
511 or <TT>'\\'</TT> to get a single backslash in the URI.)</P></DD
513 <DIV><A NAME="PRINT-MISSING-ALL"></A>
514 <H3><B>print-missing-all</B>, <B>pma</B></H3>
515 <P>Just like <B>print-missing</B>, this command outputs a list of URIs
516 still needed to completely reassemble the image. However, <SPAN><I
517 >all</I></SPAN> alternative download locations are printed instead of
518 just one. In the output, the URIs for a file are separated from other
519 files' URIs with blank lines. The <CODE>--uri</CODE> option has the
520 same effect as for <B>print-missing</B>.</P></DIV>
521 <DIV><A NAME="VERIFY"></A>
522 <H3><B>verify</B>, <B>ver</B></H3>
523 <P>Reads <TT><I>image</I></TT> (presumably generated with <B
524 >make-image</B>) and `<TT>.template</TT>', checks for correct checksum
526 <P>The template data does not only contain checksums of the individual
527 parts, but also of the image as a whole. <B>make-image</B> already
528 performs a number of internal checks, but if you like, you can
529 additionally check the image with this command.</P></DIV>
530 <DIV><A NAME="SCAN"></A>
531 <H3><B>scan</B>, <B>sc</B></H3>
532 <P>Reads all the <TT><I>FILES</I></TT> and enters them into the cache,
533 unless they are already cached. The <CODE>--cache</CODE> option must
534 be present for this command.</P>
538 <DT><CODE>--no-scan-whole-file</CODE></DT>
540 <P><SPAN><I>This is the default.</I></SPAN> This only causes the
541 first <CODE>--md5-block-size</CODE> bytes of each file to be read.
542 If the cache is used later by <B>jigdo-file make-image</B>, the
543 rest of the file will be read once these first bytes are recognized
544 in the input image.</P></DD>
545 <DT><CODE>--scan-whole-file</CODE></DT>
547 <P>Immediately read the entire file contents and store them in the
548 cache.</P></DD></DL></DIV></DIV>
549 <DIV><A NAME="MD5SUM"></A>
550 <H3><B>md5sum</B>, <B>md5</B></H3>
551 <P>Reads all the <TT><I>FILES</I></TT> and prints out MD5 checksums of
552 their contents. This command is quite similar to <SPAN><SPAN
553 >md5sum</SPAN>(1)</SPAN>, except that the checksum is output in the
554 Base64-like encoding which is also used elsewhere by <B>jigdo-file</B
556 <P>The <TT><I>FILES</I></TT> arguments are processed in the same way as
557 with the other commands, which means that recursion automatically
558 takes place for any arguments that are directories, and that symbolic
559 links are not listed except when the file(s) they point to are not
560 reachable directly.</P>
561 <P>In the checksum list printed on standard output, only the part of
562 the filename following any `<TT>//</TT>' (or `<TT>\.\</TT>' on
563 Windows) is printed. Any <CODE>--cache</CODE> will be used for
564 querying files' MD5 checksums and/or writing the checksums of scanned
566 <DIV><A NAME="LIST-TEMPLATE"></A>
567 <H3><B>list-template</B>, <B>ls</B></H3>
568 <P>Reads a `<TT>.template</TT>' file and outputs low-level information
569 about the image and all parts contained in it, including offset,
570 length and checksum.</P>
571 <P>You can also use this command with temporary image files (by
572 specifying something like <CODE>--template=imagename.tmp</CODE>) - in
573 that case, the output also distinguishes between parts that have been
574 written to the image and parts that haven't.</P>
575 <P>The exact output format may change incompatibly between different
576 jigdo releases. The following different types of lines can be output.
577 `have-file' only occurs for `<TT>.tmp</TT>' files, indicating a file
578 that has already been successfully written to the temporary file:</P><PRE>in-template <TT><I
579 >offset-in-image length</I
583 >offset-in-image length file-md5sum filestart-rsyncsum</I
587 >offset-in-image length file-md5sum filestart-rsyncsum</I
591 >image-length image-md5sum rsyncsum-size</I
594 <DIV><A NAME="DETAILS"></A>
596 <P>Jigsaw Download was created with the format of ISO9660 CD images in
597 mind - however, the following also applies to many other filesystem
598 formats, as well as to `tar' archives and uncompressed `zip' archives.
599 A CD image contains both information for organizing the filesystem
600 (header with disc name etc., ISO9660 directory data, data of extensions
601 such as Joliet or RockRidge, zero padding) and the files contained on
602 the CD. An important property that jigdo relies on is that each file is
603 stored in one contiguous section of the image; it is not split into two
605 <P>When <B>jigdo-file</B> is given a number of files that might be
606 contained in an image, it detects whether any of the files are present
607 using a `rolling checksum' inspired by the one used by <SPAN><SPAN
608 >rsync</SPAN>(1)</SPAN>. The resulting data is written to the `<TT
609 >.template</TT>' file: If a section of the image could not be matched
610 (e.g. it was directory information), the data is compressed and written
611 directly to the template. However, if a matching file was found, its
612 data is omitted from the template. Instead, only a reference (an MD5
613 checksum of the file) is inserted in the template.</P>
614 <P>Note that the template data only contains binary data, it does not
615 contain any filenames or URIs, since it cannot be easily edited in case
616 any of these values need to be changed. All that information is stored
617 in the `<TT>.jigdo</TT>' file, a text file to which you can add URLs
618 for your server(s). The jigdo file provides a mapping for each MD5
619 checksum to one or more alternative download locations for the
620 corresponding part.</P>
621 <P>Apart from the mapping of MD5 sums to URIs, the jigdo file also
622 contains an URI pointing to a download location for the template file.
623 This way, the <B>jigdo</B> download tool only needs to be given one URI
624 (that of the `<TT>.jigdo</TT>' file) to be able to download and
625 reassemble the complete image.</P></DIV>
626 <DIV><A NAME="JIGDO-FORMAT"></A>
627 <H2>FORMAT OF .JIGDO FILES</H2>
628 <P>The overall format of `<TT>.jigdo</TT>' files follows that of `<TT
629 >.ini</TT>' files, as also used by the Gnome and KDE projects for some
630 data. The file is organized into sections, each of which is preceded by
631 a line reading `<TT>[Sectionname]</TT>'. Within each section, lines
632 have the form `Label=Value'. Such lines are also called `entries'
633 below. All `<TT>.jigdo</TT>' files use UTF-8 as their character
635 <P>Comments are introduced with the `<TT>#</TT>' character and extend to
636 the end of the line. Whitespace is ignored at line start and end as
637 well as to the left and right of section names and the `<TT>=</TT>' in
638 entries. Furthermore, the jigdo utilities split up the text of the
639 entry value (i.e. the part after the `<TT>=</TT>') into
640 whitespace-separated words, much like the Unix shell. Single <TT
641 >''</TT> and double <TT>""</TT> quotes can be used to prevent that e.g.
642 URIs containing whitespace are split apart. Similarly, characters with
643 special meaning (the characters <TT>'"#\</TT> and space/tab) must be
644 quoted with <TT>\</TT> to appear in the value. As with the shell, there
645 is a difference between <TT>' '</TT> and <TT>" "</TT>: Within
646 <TT>' '</TT>, the characters <TT>"#\</TT> and whitespace lose
647 their special meaning and become ordinary characters, whereas within
648 <TT>" "</TT>, only the characters <TT>'#</TT> and whitespace lose
649 their special meaning - in other words, backslash escapes still work
650 inside <TT>" "</TT>, but not <TT>' '</TT>.</P>
651 <P>`<TT>.jigdo</TT>' files can optionally be compressed with <SPAN
652 ><SPAN>gzip</SPAN>(1)</SPAN>. <B>jigdo-file</B> always outputs
653 uncompressed files, which you can compress yourself. <B>jigdo-lite</B>
654 supports single uncompressed and compressed files.</P>
655 <P>(Behaviour which may change in the future and which should not be
656 relied upon: <B>jigdo</B> additionally supports any number of
657 concatenated plaintext and gzipped parts in the files - for example,
658 you can compress a `<TT>.jigdo</TT>' file and then add a couple of
659 lines of uncompressed data to the end.)</P>
660 <P>In all cases, the `<TT>.gz</TT>' extension should be removed from the
661 filename - the tools will determine automatically from the file
662 contents whether a file is compressed or not.</P>
663 <P>Below is a description of the individual section names used by
665 <DIV><A NAME="JIGDO-SECTION"></A>
666 <H3>Jigdo section</H3><PRE>[Jigdo]
668 Generator=jigdo-file/1.0.0</PRE>
669 <P>Information about the version of the jigdo file format used, and the
670 program that generated it. There should be one such section per `<TT
671 >.jigdo</TT>' file.</P></DIV>
672 <DIV><A NAME="IMAGE-SECTION"></A>
673 <H3>Image section</H3><PRE>[Image]
675 >"filename for saving on user's disc"</I
679 >"URI where to fetch template file"</I
682 Template-MD5Sum=OQ8riqT1BuyzsrT9964A7g
684 >single-line description of the image (200 characters max.)</I
688 >long description (5000 characters max.)</I
691 <P>The value for the `Template' entry can be either an URL (absolute or
692 relative to the URL of the jigdo file) or a string of the form `<TT
693 ><I>Label</I></TT>:<TT><I>pathname</I></TT>' (<SPAN><I
694 >UNIMPLEMENTED</I></SPAN>), as described below.</P>
695 <P>The `Template-MD5Sum' entry is added by <B>jigdo-file</B> and
696 specifies the MD5 checksum of the generated `<TT>.template</TT>' file.
697 It is used by <B>jigdo</B> to detect cases where the downloaded
698 template data is corrupted or belongs to a different image.</P>
699 <P>Unlike other entry values, the values of the `<TT>ShortInfo</TT>'
700 and `<TT>Info</TT>' entries are <SPAN><I>not</I></SPAN> split up into
701 words, instead all quoting is preserved.</P>
702 <P>The value of the `<TT>Info</TT>' entry is special in that <SPAN
703 ><SPAN>jigdo</SPAN>(1)</SPAN> can optionally parse XML markup it
704 contains. If the markup has errors such as unbalanced/unsupported
705 tags, the string is displayed literally, without XML parsing.
706 Supported tags are <TT><b></b></TT> (bold), <TT
707 ><i></i></TT> (italic), <TT><tt></tt></TT>
708 (typewriter font), <TT><u></u></TT> (underline), <TT
709 ><big></big></TT> (larger font), <TT
710 ><small></small></TT> (smaller font) and <TT
711 ><br/></TT> (linebreak). Supported entities include <TT
712 >&lt;</TT> (`<'), <TT>&gt;</TT> (`>') and <TT
713 >&amp;</TT> (`&'). Note that the whole `<TT>Info</TT>' entry
714 must be on one line in the jigdo file.</P>
715 <P>This section may occur multiple times, but all except the first one
716 will be ignored. This is useful e.g. when creating a `<TT>.jigdo</TT
717 >' file for a DVD image when you already have `<TT>.jigdo</TT>' files
718 for CDs with the same content: You can simply `<TT>[Include]</TT>'
719 (see below) the CDs' jigdo files at the end of the DVD jigdo file,
720 after its `<TT>[Image]</TT>' section.</P></DIV>
721 <DIV><A NAME="PARTS-SECTION"></A>
722 <H3>Parts section</H3><PRE>[Parts]
723 xJNkjrq8NYMraeGavUpllw=LabelA:part0
724 GoTResP2EC6Lb_2wTsqOoQ=LabelA:part1
725 kyfebwu6clbYqqWUdFIyaw=LabelB:some/path/part2
726 -J9UAimo0Bqg9c0oOXI1mQ=http://some.where.com/part3</PRE>
727 <P>All lines in the section, which provides the mapping from MD5
728 checksums to URIs, have the same format: On the left side of the `<TT
729 >=</TT>' the checksum (encoded with a Base64-like encoding) is given,
730 and on the right a string corresponding to the part with this
731 checksum; either a complete URI or a string of the form `<TT><I
732 >Label</I></TT>:<TT><I>pathname</I></TT>', which is expanded into one
733 or more URIs by looking up the definition(s) for the <TT><I>Label</I
734 ></TT> in the `<TT>[Servers]</TT>' section.</P>
735 <P>In case a particular MD5 checksum cannot be found in any `<TT
736 >[Parts]</TT>' section by <B>jigdo</B>, the program will perform a
737 lookup for `<TT>MD5Sum:</TT><TT><I><checksum></I></TT>', e.g.
738 for `<TT>MD5Sum:xJNkjrq8NYMraeGavUpllw</TT>' if you deleted the line
739 for `part0' above.</P>
740 <P>A checksum appearing multiple times in this section indicates
741 alternative download locations for the part.</P>
742 <P>There may be any number of `<TT>[Parts]</TT>' sections in the file;
743 they are all considered when looking up MD5 checksums.</P>
744 <P><B>jigdo-file</B> always puts the `<TT>[Parts]</TT>' section at the
745 end of the file, and it even rearranges any file specified with <CODE
746 >--merge</CODE> to have only one such section at the end. This is done
747 to allow <B>jigdo</B> to display the information from the `<TT
748 >[Image]</TT>' section while the rest of that file is still being
749 downloaded.</P></DIV>
750 <DIV><A NAME="SERVERS-SECTION"></A>
751 <H3>Servers section</H3><PRE>[Servers]
752 LabelA=http://myserver.org/
753 LabelA=ftp://mirror.myserver.org/
754 LabelB=LabelC:subdirectory/
755 LabelC=http://some.where.com/jigdo/</PRE>
756 <P>All lines in the section, which provides the mapping from server
757 labels to server locations, have the same format: On the left side of
758 the `<TT>=</TT>' the label name is given, and on the right the value
759 to expand the label name to.</P>
760 <P>A label name appearing multiple times in this section indicates
761 alternative download locations for the parts that use the label in the
762 `<TT>[Parts]</TT>' section. This notation makes it very easy to add
763 mirrors to the jigdo file.</P>
764 <P>As shown by the example above, the label values may themselves
765 reference other labels. In this case, the entry
766 `LabelB:some/path/part2' in the `<TT>[Parts]</TT>' section will expand
767 to `http://some.where.com/jigdo/subdirectory/some/path/part2'. Loops
768 in the label definitions result in undefined behaviour and must be
770 <P>There may be any number of `<TT>[Servers]</TT>' sections in the
771 file; they are all considered when looking up labels. Either of `<TT
772 >[Parts]</TT>' or `<TT>[Servers]</TT>', but not both, can be omitted
773 from the jigdo file.</P></DIV>
774 <DIV><A NAME="COMMENT-SECTION"></A>
775 <H3>Comment section</H3><PRE>[Comment]
776 Any text, except that lines must not begin with `['.</PRE>
777 <P>All text following a `<TT>[Comment]</TT>' or `<TT>[comment]</TT>'
778 line is ignored, up to the next line with a section label.</P></DIV>
779 <DIV><A NAME="INCLUDE"></A>
780 <H3>Include directive</H3><PRE>[Include http://some.url/file.jigdo]</PRE
782 <P>Lines of this form cause the content of the specified jigdo file to
783 be downloaded and parsed just like the main jigdo file. The effect
784 will be the same as copying the included file's contents into the file
785 which contains the include directive. (Exception: Any relative URLs
786 are always resolved using the URL of the `<TT>.jigdo</TT>' file that
787 contains that relative URL.)</P>
788 <P>The URL argument can be an absolute or relative URL. Relative URLs
789 are assumed to be relative to the URL of the jigdo file which contains
790 the include directive. Includes can be nested, but it is an error to
791 create a loop of include directives. It is <SPAN><I>not</I></SPAN>
792 possible to use URLs of the form `<TT><I>Label</I></TT>:<TT><I
793 >pathname</I></TT>'.</P>
794 <P>The URL cannot be quoted with "". Any `<TT>]</TT>' characters in the
795 argument must be escaped as `<TT>%5D</TT>', and any spaces as `<TT
797 <P>Include directives are only supported by <B>jigdo</B>, they are
798 ignored by <B>jigdo-lite</B>.</P>
799 <P>An include directive terminates any previous section, but it does
800 not start a new one. In other words, a new section must always be
801 started after the include line, <B>jigdo</B> does not allow normal
802 entries to appear below the `<TT>[Include]</TT>'.</P></DIV></DIV>
803 <DIV><A NAME="CACHE-FILES"></A>
805 <P>Any file specified with the <CODE>--cache</CODE> option is used to
806 store information about the <TT><I>FILES</I></TT> presented to <B
807 >jigdo-file</B>. When querying the cache, a file is considered
808 unchanged (and the cached data is used) only if filename, file size and
809 last modification time (mtime) match exactly. For the filename match,
810 not the entire file name is used, but only the part following any `<TT
811 >//</TT>', so that any changes to the part before the `<TT>//</TT>'
812 will not invalidate the cache.</P>
813 <P>Old cache entries are removed from the cache if they have not been
814 read from or written to for the amount of time specified with <CODE
815 >--cache-expiry</CODE>. Entries are <SPAN><I>not</I></SPAN> immediately
816 removed from the cache if the file they refer to no longer exists -
817 this makes it possible to cache information about files on removable
819 <P>Cache expiry only takes place <SPAN><I>after</I></SPAN> <B
820 >jigdo-file</B> has done its main work - if any old entries are
821 accessed before expiry takes place, they will be kept. For example, if
822 the program is run using the default expiry time of 30 days, but
823 accesses a cache file with entries generated 2 months ago, then entries
824 in that cache <SPAN><I>will</I></SPAN> be considered, and only those
825 cache entries that were not needed during the program run will be
827 <P>Due to a peculiarity of the underlying database library (libdb3),
828 cache files never shrink, they only grow. If a large number of entries
829 was expired from your cache file and you want it to shrink, you can
830 either just delete it (of course then everything will have to be
831 regenerated) or use the utilities accompanying libdb3 to dump and
832 restore the database, with a command like `<B>db3_dump <TT><I
833 >old-cache.db</I></TT> | db3_load <TT><I>new-cache.db</I></TT></B>'.
834 <SPAN><SPAN>For Debian, these programs are supplied in the package
835 `libdb3-util'.</SPAN></SPAN></P>
836 <P>If a different <CODE>--md5-block-size</CODE> is specified, the entire
837 file needs to be re-read to update its cache entry. If a different
838 <CODE>--min-length</CODE> is specified, only the first `md5-block-size'
839 bytes of the file need to be re-read.</P></DIV>
840 <DIV><A NAME="EXAMPLES"></A>
842 <DIV><A NAME="EX-CDIMAGE"></A>
843 <H3>Preparing your CD image for distribution</H3>
844 <P>You have created a CD image `<TT>image.iso</TT>' from some of the
845 files stored in the directory `<TT>/home/ftp</TT>' on your harddisc,
846 which is also available online as `ftp://mysite.org'. As you don't
847 want to waste space by effectively hosting the same data twice (once
848 as files on the FTP server, once inside the image), and you are fed up
849 with users' downloads aborting after 200MB and their restarting the
850 download dozens of times, you decide to use jigdo. How do you prepare
851 the image for download?</P>
852 <P>In fact, only one command is necessary: <A NAME="AEN799"></A
854 <P><B>jigdo-file make-template --image=image.iso
855 --jigdo=/home/ftp/image.jigdo --template=/home/ftp/image.template
856 /home/ftp// --label Mysite=/home/ftp --uri
857 Mysite=ftp://mysite.org/</B></P></BLOCKQUOTE> </P>
858 <P>People can now point <B>jigdo</B> at `ftp://mysite.org/image.jigdo'
859 to download your image. The template file needs to be accessible as
860 `ftp://mysite.org/image.template'.</P>
861 <P>Note that nothing prevents you from doing the same for an FTP server
862 that isn't administrated by you - in that case, you only need to host
863 the `<TT>.jigdo</TT>' and `<TT>.template</TT>' files on your own
864 server/homepage.</P></DIV>
865 <DIV><A NAME="EX-LARGEFILE"></A>
866 <H3>Preparing an arbitrary large file for distribution</H3>
867 <P>We assume that you have a large file that is not a filesystem, e.g.
868 `<TT>movie.mpeg</TT>'. Because of space problems, you want to
869 distribute the data on two servers.</P>
870 <P>In this case, the parts of the image need to be generated
871 artificially with the <B>split</B> command. For example, to create
872 chunks of 4MB each, use `<B>split -b 4m movie.mpeg part</B>'. Copy the
873 resulting files `<TT>part<TT><I>XX</I></TT></TT>' into two directories
874 `<TT>1</TT>' and `<TT>2</TT>' that you create, according to how you
875 want the files distributed between the servers. Next, create the jigdo
876 and template files with `<B>jigdo-file make-template
877 --image=movie.mpeg 1// 2//</B>'. You will need to edit the `<TT
878 >.jigdo</TT>' file and provide the right URIs for the two servers that
879 you are going to upload the `<TT>part<TT><I>XX</I></TT></TT>' files
881 <DIV><A NAME="EX-CUSTOMIZE"></A>
882 <H3>Customized versions of images</H3>
883 <P>Because it is possible to assign a different URI for each part of an
884 image if necessary, jigdo is very flexible. Only one example is the
885 possibility of customized versions of images: Suppose that someone is
886 distributing a CD image, and that you want to make a few small changes
887 to it and redistribute your own version. You download the `<TT
888 >official.iso</TT>' CD image with <B>jigdo</B> (passing it the URL of
889 `<TT>official.jigdo</TT>'), write it to CD-R, make your changes (say,
890 adding files from the `<TT>myfiles</TT>' directory on your harddisc)
891 and produce your own version, `<TT>myversion.iso</TT>'. Next, you
892 instruct <B>jigdo-file</B> to create the jigdo and template files for
893 your modified image, using the command <A NAME="AEN831"></A
895 <P><B>jigdo-file make-template --image=myversion.iso /mnt/cdrom/
896 myfiles// --label My=myfiles/ --uri My=http://my.homepage.net/
897 --merge=official.jigdo</B></P></BLOCKQUOTE> while `<TT
898 >official.iso</TT>' is mounted under `<TT>/mnt/cdrom</TT>'. By using
899 <CODE>--merge</CODE>, you have told <B>jigdo-file</B> to take the
900 contents of `<TT>official.jigdo</TT>', add to it a new `<TT
901 >[Image]</TT>' section for `<TT>myversion.iso</TT>' and write the
902 resulting jigdo file to `<TT>myversion.jigdo</TT>' - so now `<TT
903 >myversion.jigdo</TT>' offers two images for download, the original
904 version and your modified version. (If you do not want it to offer the
905 official version, edit it and remove the `<TT>[Image]</TT>' section
906 that lists `<TT>official.iso</TT>'.)</P>
907 <P>Now you can upload the `<TT>.jigdo</TT>' file, the `<TT
908 >.template</TT>' file and also the files in `<TT>myfiles</TT>' to
909 `http://my.homepage.net/'. Thus, for people to download your modified
910 image, you do <SPAN><I>not</I></SPAN> need to upload the complete
911 image contents to your web space, but only the changes you made!</P>
912 <P>(In case you only made very few changes, you could also omit the
913 `myfiles' parameter in the command above, then all your changes end up
914 in the new template file.)</P></DIV>
915 <DIV><A NAME="EX-COMBINE"></A>
916 <H3>Combining many jigdo-managed images into one</H3>
917 <P>It is also no problem to combine data from several sources that use
918 jigdo. For example, if of five different and unrelated servers each
919 one distributes a different CD image via jigdo, you can create a
920 customized DVD image that contains the data from all these CDs. When
921 people use <B>jigdo</B> to download your image, the individual files
922 on the DVD are fetched from the same sources as the original CDs.</P>
923 <P>Consequently, even though you will be distributing a 3.2GB file via
924 your web space, the actual amount of data that is stored on your
925 server will only be in the order of several MBs.</P></DIV></DIV>
926 <DIV><A NAME="BUGS"></A>
928 <P>For certain contents of one of the input files, most notably a
929 sequence of zero bytes longer than <CODE>--min-length</CODE> at the
930 start of the file and an area of zeros preceding the file data in the
931 image, <B>jigdo-file make-template</B> may fail to find the file in the
932 image. Unfortunately, this restriction cannot be avoided because the
933 program could become very slow otherwise. If you use the <CODE
934 >--debug</CODE> option, all instances of <B>jigdo-file</B> discarding
935 possible matches are indicated by lines containing the word `<TT
937 <P>In fact, not only all-zeroes files trigger this behaviour, but also
938 files which contain at their start a long sequence of short identical
939 strings. For example, both a file containing only `<TT>a</TT>'
940 characters and one containing `<TT>abcabcabcabc</TT>...' are
941 problematic.</P></DIV>
942 <DIV><A NAME="SEEALSO"></A>
944 <P> <SPAN><SPAN>jigdo</SPAN>(1)</SPAN> (NOT YET IMPLEMENTED), <SPAN
945 ><SPAN>jigdo-lite</SPAN>(1)</SPAN>, <SPAN><SPAN>jigdo-mirror</SPAN
946 >(1)</SPAN>, <SPAN><SPAN>split</SPAN>(1)</SPAN> (or `<B>info split</B
947 >'), <SPAN><SPAN>find</SPAN>(1)</SPAN> (or `<B>info find</B>'), <SPAN
948 ><SPAN>mkisofs</SPAN>(1)</SPAN>, <SPAN><SPAN>md5sum</SPAN>(1)</SPAN>
950 <DIV><A NAME="AUTHOR"></A>
952 <P><A HREF="http://atterer.org/jigdo/" TARGET="_top">Jigsaw Download</A
953 > was written by Richard Atterer <CODE><<A HREF="mailto:jigdo
954 atterer.org">jigdo atterer.org</A>></CODE>, to make downloading of
955 CD ROM images for the Debian Linux distribution more convenient.</P