LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

new

This commit is contained in:
gferg 2002-07-23 12:53:28 +00:00
parent 4f4242b1ee
commit d145628a90
1 changed files with 917 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

917
LDP/howto/docbook/Debian-Jigdo.sgml Normal file
View File

@ -0,0 +1,917 @@
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>
<artheader>
<title>Debian Jigdo mini-HOWTO</title>
<titleabbrev>DJ-HOWTO</titleabbrev>
<author>
<firstname>Peter</firstname>
<othername role='middle'>Jay</othername>
<surname>Salzman</surname>
<affiliation>
<address><email>p@dirac.org</email></address>
</affiliation>
</author>
<pubdate>v0.99, 2002-07-22</pubdate>
<copyright>
<year>2001</year>
<holder>Peter Jay Salzman</holder>
</copyright>
<legalnotice>
<para><email>p@dirac.org</email> / <systemitem role="url">www.dirac.org/p</systemitem>.</para>
<para>Distributed subject to the GNU General Public License, version 2.</para>
</legalnotice>
<abstract><title>Abstract</title>
<para>Getting Debian ISOs has always been a painful, slow and supremely inefficient process. Jigdo is a new tool for
obtaining Debian ISOs in an easy, fast and very efficient manner. This HOWTO describes why you should use jigdo, a little
bit about how it works and how you use it to get and update Debian ISOs.</para>
<para>Jigdo is a very general tool, and isn't tied specifically to Debian ISOs. The jigdo tools can be used to make any ISO
available for download in the same easy, fast and efficient manner they're used for Debian ISOs. This HOWTO will cover this
as well, but we'll focus primarily on downloading Debian ISOs.</para>
</abstract>
</artheader>
<sect1 id="administrata"><title>Administrata</title>
<sect2 id="acknowledgements"><title>Acknowledgements</title>
<para>Originally, I was going to thank the author of jigdo, <ulink url="mailto:atterer@debian.org">Richard
Atterer</ulink>, simply for writing jigdo. Anyone who has ever tried to use Debian's PIK (or worse, downloaded enitre
Debian ISOs) will know why. However, my thanks needs to go further. This HOWTO started out as some webpages I wrote
about my experience with jigdo. Richard took the time to email me extensive corrections, clarifications and answers to
questions I still had about jigdo. In the process of updating the web pages and their transformation into a
HOWTO, he has read my work many times. Richard is obviously a developer who not only cares
about his work, but cares about the people who use it. Sadly, this is something that is becoming less common in this busy
world we live in. Thanks, Richard, and keep up the excellent work.</para>
</sect2>
<sect2 id="version"><title>Latest Version And Translations</title>
<para>There are no translations yet. If you would like to translate this HOWTO to another language, please contact me
at <email><ulink url="mailto:p@dirac.org">p@dirac.org</ulink></email>.</para>
<para>This HOWTO currently doesn't have a real home in the sense that my other HOWTO, "The Linux Gamers' HOWTO" is
available via cvs at <ulink url="http://sourceforge.net/projects/lgh/">sourceforge.net</ulink> or in various formats from
<ulink url="http://www.linuxdoc.org">linuxdoc.org</ulink>. The latest version is currently available from my website:
<ulink url="http://www.dirac.org/linux/debian/jigdo">http://www.dirac.org/linux/debian/jigdo</ulink>. The Debian Jigdo
HOWTO will be submitted to <ulink url="http://www.linuxdoc.org">linuxdoc.org</ulink> soon. When it is, that will be the
official source for the latest version and this paragraph will be updated.</para>
</sect2>
<sect2 id="authorship"><title>Authorship and Copyright</title>
<para>This document is copyright (c) 2001 Peter Jay Salzman, <email><ulink
url="mailto:p@dirac.org">p@dirac.org</ulink></email>. Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version 1.1, except for the provisions I list in the next
paragraph. I hate HOWTO's that include the license; it's a tree killer. You can read the GNU FDL at <ulink
url="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>.</para>
<para>If you want to create a derivative work or publish this HOWTO for commercial purposes, contact me first. This will
give me a chance to give you the most recent version. I'd also appreciate either a copy of whatever it is you're doing or
a spinach, garlic, mushroom, feta cheese and artichoke heart pizza.</para>
</sect2>
</sect1>
<sect1 id="whyjigdo"><title>Why jigdo?</title>
<sect2><title>How Does One Get A Debian ISO Image Set?</title>
<para>If you want your own set of Debian CDs there are many ways of getting them. One way is to buy them from <ulink
url="http://www.debian.org/CD/vendors/">vendors</ulink> who sell Debian CDs. This has some merit since some of the
vendors donate money back to the Debian project. Your donations help make sure that Debian is around for a long
time.</para>
<para>Another way of getting a set of Debian CDs is to burn your own set. This entails first obtaining an ISO image and
then burning that ISO image to a blank CD. Before jigdo, there were two ways of creating Debian CDs:</para>
<orderedlist>
<listitem><para>Downloading the entire ISO</para>
<listitem><para>Using the pseudo-image kit (PIK)</para>
</orderedlist>
<para>This document is about the new and better way of obtaining Debian ISO images, using a tool called jigdo. In fact,
the PIK is now deprecated. The canonical method of getting Debian ISO images is with jigdo.</para>
</sect2>
<sect2 id="whynotdownloadthewholeisoimage"><title>Why Not Download The Whole ISO Image?</title>
<para>There are mirrors which offer http and ftp downloads of Debian ISOs. The problem is that there are very few mirror
sites, and their bandwidth can't support everyone who wants Debian ISOs. For example, fsn.hu has reportedly saturated
the connection of its provider. The outgoing traffic reaches a few terabytes per month!</para>
<para>In addition, Debian testing and unstable get updated often. Your ISOs will become outdated the same day you
download them unless you find some sneaky way of updating them like mounting the ISO on a loopback device and using rsync
(which is what the PIK does). So if you want up-to-date ISO images, you must download a new set of ISO images every day.
Clearly, this is not the way you want to obtain Debian ISOs!</para>
<para>Even if you want to download the stable ISO images, they still get updated every few months. Downloading the ISO
images will give you up-to-date images for a few months, but every time a new revision of Debian stable is released,
you'll need to go through the painful process of downloading the entire ISO set from scratch. This is not a good use of
your time and the mirror's resources.</para>
<sect2 id="whynotusethewholepik"><title>Why Not Use The Pseudo Image Kit (PIK)?</title>
<para>The PIK addresses the problems of downloading entire ISO images. The downloads are fast, and the PIK uses rsync to
update only those portions of an ISO image that need to be updated, so it's an efficient way of keeping your ISO set
up-to-date. However, there are some hefty problems with the PIK:</para>
<itemizedlist>
<listitem><para>It's difficult to use and not very user friendly.</para></listitem>
<listitem><para>You can't use the PIK to download testing and unstable ISO sets.</para></listitem>
<listitem><para>The PIK relies on rsync which is CPU-intensive for the server. If too many people use PIK with the same
server, it would go up in smoke. Even if the PIK is made more friendly for the user, it's unacceptably unfriendly for
the mirrors.</para></listitem>
<listitem><para>The PIK uses rsync, which is blocked by many of the stricter firewalls. So even if you wanted to use that
nice fast corporate network at work, you might run into problems using the PIK.
<listitem><para>Each image needs to be stored on the server. That was OK in the good old potato days, when the 28 CD
images took "only" 17 GB. Starting with woody, the 96 CDs need 57 GB or so. Now imagine that we also want to offer
DVDs and this figure doubles.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="whatisjigdo"><title>What Is Jigdo?</title>
<para>Jigdo (which stands for "Jigsaw Download") was written by <ulink url="mailto:atterer@debian.org">Richard
Atterer</ulink> and is released under the GNU GPL. It's a tool that allows efficient downloading and updating of an ISO
image. Any ISO image. Jigdo is not Debian specific, however Debian has chosen it to be the prefered method of
downloading ISO images. The jigdo tool comes with two utilities: jigdo-file which prepares an ISO image for download
and jigdo-lite which is used to download ISO images which were prepared by jigdo-file.</para>
<para>Jigdo doesn't create ISO images. It simply prepares them for downloading and also downloads them. The ISO image
needs to be made in advance, and that's usually done with mkisofs or debian-cd.</para>
<para>Jigdo addresses all the problems with the other two methods of obtaining Debian ISO images:</para>
<itemizedlist>
<listitem><para>It's much faster than downloading the entire ISO image.</para></listitem>
<listitem><para>Unlike downloading the entire ISO image, it can take an outdated CD image (or a loop mounted outdated ISO
image), download <emphasis>only</emphasis> the files that have changed since the CD (or ISO image) was created and
create a new updated ISO. Very similar to how you use cvs to update source code.</para></listitem>
<listitem><para>jigdo-lite is much easier to use than the PIK.</para></listitem>
<listitem><para>jigdo-lite uses wget which, by default, uses http to transfer files. The PIK uses rsync. While rsync
may be blocked by some firewalls, the only firewalls that block http are the ones from which you shouldn't be using
jigdo to begin with. You'll almost never run into firewall problems with jigdo-lite.</para></listitem>
</itemizedlist>
<para>Clearly, jigdo is the best method of obtaining Debian ISO images.</para>
</sect2>
</sect1>
<sect1 id="howjigdoworks"><title>How Jigdo Works (optional)</title>
<para>You don't need to know this material to use jigdo, but it may help demystify what jigdo does. If you're not interested
in the details, simply fast forward to <xref linkend="downloadingyourfirstimage">, "How Do I Use Jigdo".</para>
<para>There are two components to jigdo:</para>
<itemizedlist>
<listitem><para>jigdo-file: Prepares an ISO for download (used by the person offering the ISO)</para></listitem>
<listitem><para>jigdo-lite: Downloads the ISO (used by the person downloading the ISO)</para></listitem>
</itemizedlist>
<sect2 id="preparingtheisofordownload"><title>Preparing The ISO For Download</title>
<para>A CD image is a filesystem called iso9660, but for this discussion, we can safely talk about a cd image as being a
big file called an "ISO image" (about 650MB) that contains files at various offsets. For instance, if a CD contains a 567
byte file named README, the ISO image might contain the README file's contents between offsets 20480000 and 20480567. You
can visualize a CD image as:</para>
<screen>
--------------------------------------------------------
ISO Image: |xxxx| file-0 |xx| file-1 |xxx| file-2 |x| file-3 |xxxx|
--------------------------------------------------------
</screen>
<para>The "x" areas of the image contain things like directory information, zero padding, disk name, boot block,
etc.</para>
<para>jigdo-file takes two things as input: the complete CD image (so the ISO already needs to have been made) and a set
of files which may or may not be in the image. Here's a visualization of jigdo-file's input:</para>
<screen>
--------------------------------------------------------
ISO Image: |xxxx| file-0 |xx| file-1 |xxx| file-2 |x| file-3 |xxxx|
--------------------------------------------------------
---------- ---------- ---------- ----------
Loose Files: | file-0 | | file-1 | | file-3 | | file-4 |
---------- ---------- ---------- ----------
</screen>
<para>Through magic, jigdo-file finds out which of the loose files are contained in the ISO image and their offsets within
the ISO file. It outputs two files: a ".template" file and a ".jigdo" file.</para>
</sect2>
<sect2 id="the.templatefile"><title>The .template File</title>
<para>Given an input of an ISO image and a set of files which may or may not be in the ISO image, jigdo-file outputs a
.template file for that ISO image. Here's what the .template file looks like:</para>
<screen>
--------------------------------------------------------
.template: |xxxx| md5-0 |xx| md5-1 |xxx|cccccccc|x| md5-3 |xxxx|
--------------------------------------------------------
</screen>
<para>jigdo-file found that the files <filename>file-0</filename>, <filename>file-1</filename> and
<filename>file-3</filename> were contained in the ISO image. It removed the contents of the these files and replaced them
with each file's md5 checksum.</para>
<para>The "<literal remap="bf">x</literal>" data (directory information, zero padding, etc) within the ISO image is
compressed and written to the .template file. Finally, any files within the ISO image that weren't supplied as loose
files (like <filename>file-2</filename>) are also compressed and written to the .template file. This is shown as
"<literal remap="bf">c</literal>" data in the .template file visualization.</para>
<para>Loose files which were supplied to jigdo-file that aren't found in the ISO image (like <filename>file-4</filename>)
are ignored.</para>
</sect2>
<sect2 id="the.jigdofile"><title>The .jigdo File</title>
<para>Given an input of an ISO image and a set of loose files which may or may not be in the ISO image, jigdo-file outputs
a .jigdo file for that ISO image. The Debian .jigdo files are gzipped, so you need to use zcat or zless to view it.
Here's what the .jigdo file looks like when you gunzip it:</para>
<screen>
md5-0=http://somemirror.org/file-0
md5-1=http://somemirror.org/file-1
md5-2=http://somemirror.org/file-2
md5-3=http://somemirror.org/file-3
</screen>
<para>The .jigdo file simply provides a mapping between the md5sum of a file within the ISO image and the download URL of
that file. There are some other things within the .jigdo file, and if you look through it, you'll see the .jigdo file has
the same format as a ".ini" file. It should be self explanatory, but if you want the nitty-gritty details, see the jigdo
documentation.</para>
<para>The format shown above is not quite what you'd see in a typical .jigdo file, but it's very similar. If you look at
the [Servers] section at the bottom of the .jigdo file, you'll see exactly what the difference is between what I showed
above and an actual .jigdo file.</para>
</sect2>
<sect2 id="downloadingtheimage"><title>Downloading The Image</title>
<para>Once you use jigdo-file to prepare the ISO for downloading, anyone can use jigdo-lite to download the ISO.
jigdo-lite downloads all the files of a Debian ISO using wget, assembles them and forms an ISO on the fly.</para>
</sect2>
</sect1>
<sect1 id="downloadingyourfirstimage"><title>Downloading Your First Image</title>
<para>We'll assume that you're starting from scratch and don't have any Debian ISOs on hand. Once you burn your set of
ISOs, you can later use jigdo-lite to update them. We'll cover updating your ISOs in the next section.</para>
<sect2><title>Install Jigdo</title>
<para>First install the jigdo-file package:</para>
<screen>
# apt-get install jigdo-file
</screen>
<para>Jigdo is under aggressive development. Bug fixes and improvements are constant, so if you're using stable or
testing, download jigdo-file from unstable at <ulink url= "http://packages.debian.org/unstable/utils/jigdo-file.html"
>http://packages.debian.org/unstable/utils/jigdo-file.html</ulink>. As of 19 July 2002 it's at version 0.6.8. This is
the version used for the examples of this HOWTO.</para>
</sect2>
<sect2 id="downloadthe.templateand.jigdofiles"><title>Download The .template And .jigdo Files</title>
<para>For each ISO image you want to download, you'll need two files:</para>
<itemizedlist>
<listitem><para>The .jigdo file for the disk image you want to download.</para></listitem>
<listitem><para>The .template file for the disk image you want to download.</para></listitem>
</itemizedlist>
<para>Example: Woody has 8 images, so you need to download 8 .jigdo files and 8 .template files. They can be
downloaded from <ulink url="http://www.debian.org/CD/jigdo-cd/" >http://www.debian.org/CD/jigdo-cd/</ulink> and are named
<filename>woody-i386-1.iso.jigdo</filename>, <filename>woody-i386-1.iso.template</filename>, <filename>...</filename>,
and <filename>woody-i386-8.iso.template</filename>.</para>
</sect2>
<sect2 id="runjigdo-lite"><title>Run jigdo-lite</title>
<para>Run jigdo-lite and give it the .jigdo file of the image you want to download. Using Woody as an example:</para>
<screen>
% jigdo-lite woody-i386-1.iso.jigdo
</screen>
<para>You'll see something like:</para>
<screen>
-----------------------------------------------------------------
Jigsaw Download "lite"
Copyright 2001-2002 by Richard Atterer &lt;jigdo@atterer.net&gt;
Getting mirror information from /etc/apt/sources.list
-----------------------------------------------------------------
Images offered by `woody-i386-1.iso.jigdo':
1: woody-i386-1.iso
-----------------------------------------------------------------
If you already have a previous version of the CD you are
downloading, jigdo can re-use files on the old CD that are also
present on the new image, and you do not need to download them
again. Mount the old CD ROM and enter the path it is mounted under
(e.g. `/mnt/cdrom'). Alternatively, just press enter if you want
to start the download of any remaining files.
Files to scan:
</screen>
<para>If you forget to pass jigdo-lite a .jigdo file, it will prompt you for one.</para>
<para>If you suspended jigdo-lite with cntrl-z (don't do this; I'll tell you what you'd see) and did an
<command>ls</command>, you'd find a new file in the directory named <filename>woody-i386-1.iso.jigdo.unpacked</filename>.
This file is simply a gunzip'ed version of the .jigdo file.</para>
<para>Right now, jigdo-lite is telling us that if we did have an outdated version of the CD, to give the pathname to the
CD. Since we're assuming that you're starting from scratch and have no Debian ISOs yet, we have nothing to scan (we'll
cover this in detail in <xref linkend="updatingyourimage">). So just press &lt;ENTER&gt;.</para>
</sect2>
<sect2 id="specifyamirror"><title>Specify A Mirror</title>
<para>You'll see:</para>
<screen>
-----------------------------------------------------------------
The jigdo file refers to files stored on Debian mirrors. Please
choose a Debian mirror as follows: Either enter a complete URL
pointing to a mirror (in the form
`ftp://ftp.debian.org/debian/'), or enter any regular expression
for searching through the list of mirrors (try a two-letter
country code such as `de', or a country name like `United
States', or a server name like `sunsite'):
Debian mirror [http://linux.csua.berkeley.edu/debian//]:
</screen>
<para>jigdo-lite is smart enough to use the mirror that you use for your Debian updates by pulling it from
<filename>/etc/apt/sources.list</filename> (you can see that I use <filename>linux.csua.berkeley.edu</filename> for my
updates). If for some reason you wanted to use a different mirror, you would specify a different mirror here. If this is
the mirror you want to use, press &lt;ENTER&gt;. Jigdo-file will then write a <filename>.jigdo-lite</filename> file in
your home directory.</para>
<para>Next, if the .jigdo file you're using references a package which needs to be downloaded from a Non-US server
(software encumbered by US export restrictions), jigdo-lite will prompt you for a Non-US server. The message displayed
(and your response) will be very similar to the mirror dialog described in the previous paragraph. The only difference is
that you need to specify (or accept the default value for) a Non-US server. If the ISO image you're about to download
contains Non-US software, you'll see:
<screen>
-----------------------------------------------------------------
The jigdo file also refers to the Non-US section of the Debian
archive. Please repeat the mirror selection for Non-US. Do not
simply copy the URL you entered above; this does not work because
the path on the servers differs!
Debian non-US mirror [http://linux.csua.berkeley.edu/debian-non-US//]:
</screen>
<para>and jigdo-lite will write your choice to your <filename>$HOME/.jigdo-lite</filename> file. However, if the image
you're about to download doesn't contain Non-US software you won't see this dialog.</para>
<para>Note that you can reset the default mirrors that jigdo uses for your future downloads in
<filename>$HOME/.jigdo-lite</filename> file with the following lines:</para>
<screen>
debianMirror='http://some-mirror-to-use/debian/'
nonusMirror='http://some-other-mirror/debian-non-US/'
</screen>
</sect2>
<sect2 id="downloadingoftheiso"><title>Downloading Of The ISO</title>
<para>After specifying the mirror(s), jigdo-lite will look for the .template file. If it can't find one, it'll download a
.template file from a mirror. After it finds the .template file (or after it downloads one), you'll see:</para>
<screen>
-----------------------------------------------------------------
Merging parts from `file:' URIs, if any...
Found 0 of the 1224 files required by the template
Will not create image or temporary file - try again with different input files
--13:38:08-- http://linux.csua.berkeley.edu/debian/pool/main/b/bind9/
lwresd_9.2.1-2.woody.1_i386.deb => `lwresd_9.2.1-2.woody.1_i386.deb'
Resolving linux.csua.berkeley.edu... done.
Connecting to linux.csua.berkeley.edu[128.32.247.238]:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 157,318 [application/x-debian-package]
30% [==========> ] 47,418 113.22K/s ETA 00:00
...
</screen>
<para>After the .template file was found (or after it was downloaded), jigdo-lite begins pulling packages onto your hard
drive. There will be alot of messages flying across your screen. If this is confusing to you, see <xref
linkend="wgetoptions">. While jigdo-lite is downloading the packages, switch to another console (or open another xterm)
and do an <command>ls</command> in the directory you're running jigdo-lite in. Now there should be 6 files in the
directory:</para>
<itemizedlist>
<listitem><para><filename>jigdo-file-cache.db</filename></para></listitem>
<listitem><para><filename role="directory">tmp/</filename></para></listitem>
<listitem><para><filename>woody-i386-1.iso.jigdo</filename></para></listitem>
<listitem><para><filename>woody-i386-1.iso.jigdo.unpacked</filename></para></listitem>
<listitem><para><filename>woody-i386-1.iso.list</filename></para></listitem>
<listitem><para><filename>woody-i386-1.iso.template</filename></para></listitem>
<listitem><para><filename>woody-i386-1.iso.tmp</filename></para></listitem>
</itemizedlist>
<para><filename>woody-i386-1.iso.tmp</filename> won't appear right away. It's a temporary version of the ISO file that
gets written to every so often.</para>
<para><filename>jigdo-file-cache.db</filename> is a Berekeley DB file containing md5sums of any files read in when you
specify a directory at the <literal>Files to scan:</literal> prompt. It's more fully described in <xref
linkend="jigdo-file-cache">.</para>
<para><filename role="direcotry">tmp/</filename> is a directory containing Debian package files that get downloaded. For
instance, as I write this, it contains:</para>
<screen>
$ ls tmp/
alsa-headers-0.5_0.5.12a-2_all.deb tkdiff_3.08-3_all.deb
alsa-utils-0.4_0.4.1-9.1_i386.deb xfonts-intl-chinese-big_1.2-2.1_all.deb
gnuserv_3.12.4-3_i386.deb xmanpages-ja_4.1.0.20011224-1_all.deb
pilot-link_0.9.5.0-8_i386.deb xscreensaver_3.34-3_i386.deb
smpeg-plaympeg_0.4.4-8_i386.deb
</screen>
<para>Every so often, the directory gets flushed and the files get added to
<filename>woody-i386-1.iso.tmp</filename>.</para>
<para>I have no idea what <filename>woody-i386-2.raw.list</filename> is; file reports it as binary data.</para>
<para>At this point, go play some Quake III because this will take some time (you may want to play on a different machine
because jigdo is very disk intensive when it assembles the ISO file). At some point, the download will finish and you'll
be staring at:</para>
<screen>
FINISHED --13:32:58--
Downloaded: 7,469,872 bytes in 9 files
Found 9 of the 9 files required by the template
Successfully created `woody-i386-3.raw'
-----------------------------------------------------------------
Finished!
The fact that you got this far is a strong indication that `woody-i386-3.raw'
was generated correctly. I will perform an additional, final check,
which you can interrupt safely with Ctrl-C if you do not want to wait.
OK: Checksums match, image is good!
$
</screen>
</sect2>
</sect1>
<!--
<orderedlist>
<listitem><para>If you have an outdated copy of the CD: Mount it and give jigdo-lite the path to your CD. On Debian,
this is most likely <filename role="directory">/cdrom</filename>.</para></listitem>
<listitem><para>If you have an outdated copy of the ISO file: Currently, jigdo-lite can't scan an outdated ISO image
file (it's on the TODO list), but you can employ a trick to use your ISO file. ISO files are actually filesystems, just
like the filesystems on your hard drive, but their contained in a file rather than a partition on your drive. Linux
can mount these files just as if they were filesystems on a partition. Mount the ISO file as a loop device
using <command>mount -o loop /path/to/iso/outdated-iso.iso /mnt</command>. If you look at <filename
role="directory">/mnt</filename>, you'll see the CD image. Then give the directory <filename
role="directory">/mnt</filename> to jigdo-lite and it will scan your outdated ISO file.</para></listitem>
</orderedlist>
-->
<sect1 id="updatingyourimage"><title>Updating Your Image</title>
<para>Presumably, you've read the last section, followed the instructions, burned your newly created ISO files onto CD and are
feeling warm and fuzzy. Sooner or later, some packages will get updated and now you want to donate your old CDs to some
newbie at your local LUG's installfest and burn yourself a set of updated CDs. Since you're well on the way to becoming a
jigdo-guru, we won't go into as much painful detail as we did in the last section.</para>
<para>The first step is to download the .jigdo and .template files, again, for the images you want to update. You may wonder
why you need to download them a second time. The reason is because the updated image you want to download has changed. Files
may have been added or deleted, but even if not, any updated packages or files will have a different checksum from the
checksum listed in the .jigdo and .template files you used when you first downloaded the images.</para>
<para>At this point, you're either holding an outdated Debian CD in your hand or you have the CD's outdated ISO image on your
hard drive. Let's go through the steps of getting an updated ISO file. If you have a CD, put it in your CD drive and mount
it:</para>
<screen>
$ mount /cdrom
</screen>
<para>On the other hand, if you have an ISO file you'd like to update, mount it as a loop device (you may need to be root
to do this). I'll be updating my Woody image, since I noticed that Woody just got a few security updates:</para>
<screen>
# mount -o loop woody-i386-1.iso /mnt
</screen>
<para>Now run jigdo-lite with the .jigdo file as an argument.</para>
<!-- good for 0.6.8-1 -->
<screen>
$ jigdo-lite woody-i386-1.jigdo
-----------------------------------------------------------------
Jigsaw Download "lite"
Copyright 2001-2002 by Richard Atterer &lt;jigdo@atterer.net&gt;
Loading settings from `/home/p/.jigdo-lite'
-----------------------------------------------------------------
Images offered by `woody-i386-1.jigdo':
1: Debian GNU/Linux 3.0 r0 Woody - Official i386 Binary-1 CD (debian-30r0-i386-binary-1.iso)
Further information about `debian-30r0-i386-binary-1.iso':
Generated on Thu, 18 Jul 2002 14:34:12 +0100
-----------------------------------------------------------------
If you already have a previous version of the CD you are
downloading, jigdo can re-use files on the old CD that are also
present on the new image, and you do not need to download them
again. Mount the old CD ROM and enter the path it is mounted under
(e.g. `/mnt/cdrom'). Alternatively, just press enter if you want
to start the download of any remaining files.
You can also enter a single digit from the list below to
select the respective entry for scanning:
1: /mnt
Files to scan:
</screen>
<para>jigdo-lite is asking us to give it the location of your mounted CD (if you're updating a CD) or your loop mounted ISO
file (if you're using the ISO file). I'm using an ISO file loop mounted on <filename role="directory">/mnt</filename>, so
I'll enter <literal>/mnt</literal>. If you're updating a CD, enter the mount directory of your CD, which is most likely
<literal>/cdrom</literal>. In either case, jigdo-lite will scan the directory of your mounted media, determine which files
need updating and re-use the files which don't need updating. You may see something like:</para>
<!-- good for 0.6.8-1 -->
<screen>
Files to scan: /mnt/other
Not downloading .template file - `woody-i386-1.template' already present
jigdo-file: Output file `debian-30r0-i386-binary-1.iso' already exists - delete
it or use --force
jigdo-file failed with code 3 - aborting.
</screen>
<para>What happened? Actually, I wanted to show you this because you'll bump into it sooner or later. I'm updating an ISO
file, but the outdated image file is in the same directory I'm working in. Jigdo-lite wants to generate a file called
<filename>woody-i386-1.iso</filename> but there's already a file by that name in the current directory (the outdated image).
Jigdo-lite doesn't want to destroy that file, so it bails and lets me know that I can either delete that file or use
<literal>--force</literal> to overwrite the file. You could also rename or move the file too, but I guess jigdo-lite
assumes we already know this. &nbsp; :-)</para>
<para>Don't be timid about moving or renaming the image file just because it's loop mounted. The filesystem uses inodes under
the hood, and even if you move or rename the file, the inode stays the same. You won't hurt the filesystem mounted under
<filename role="directory">/mnt</filename>. As for deleting the ISO file, that won't hurt the mounted filesystem either. A
file's inode gets deallocated only when the inode's reference count drops to zero. Mounting the ISO image bumps the reference
count up, so the file really gets deleted only after you <command>rm</command> the file <emphasis>and</emphasis> umount the
loop device. All you people who are updating the CD don't have to worry about any of this. :-)</para>
<para>I'll rename the ISO file to <filename>woody-i386-1.iso.old</filename> and run jigdo-lite again. Let's try again:</para>
<screen>
$ jigdo-lite woody-i386-1.iso.jigdo
-----------------------------------------------------------------
Jigsaw Download "lite"
Copyright 2001-2002 by Richard Atterer &lt;jigdo@atterer.net&gt;
Loading settings from `/home/p/.jigdo-lite'
-----------------------------------------------------------------
Images offered by `woody-i386-1.iso.jigdo':
1: Debian GNU/Linux 3.0 r0 Woody - Official i386 Binary-1 CD
(debian-30r0-i386-binary-1.iso)
Further information about `debian-30r0-i386-binary-1.iso':
Generated on Thu, 18 Jul 2002 14:34:12 +0100
-----------------------------------------------------------------
If you already have a previous version of the image you are
downloading, jigdo can re-use files on the old image that are also
present on the new image, and you do not need to download them
again. Mount the old CD ROM and enter the path it is mounted under
(e.g. `/mnt/cdrom'). Alternatively, just press enter if you want
to start the download of any remaining files.
You can also enter a single digit from the list below to
select the respective entry for scanning:
1: /mnt
Files to scan: /mnt
Not downloading .template file - `woody-i386-1.template' already present
...
Found 1200 of the 1224 files required by the template
...
</screen>
<para>jigdo-lite remembers that I wanted to scan <filename role="directory">/mnt</filename> and tells me I can either type
<literal>1</literal> to scan that directory or type the directory in again. Since I'm a perverse person, I type the name of
the directory again.</para>
<para>The ellipsis represent some text that changes rapidly. The first ellipsis is a dynamic list of what files jigdo-lite is
scanning. The second ellipses deonotes progress in writing <filename>woody-i386-1.iso.tmp</filename>. Once jigdo-lite
finishes scanning the files and writing the temporary ISO file, it prints:</para>
<screen>
Copied input files to temporary file `woody-i386-1.iso.tmp'
- repeat command and supply more files to continue
-----------------------------------------------------------------
If you already have a previous version of the image you are
downloading, jigdo can re-use files on the old image that are also
present on the new image, and you do not need to download them
again. Mount the old CD ROM and enter the path it is mounted under
(e.g. `/mnt/cdrom'). Alternatively, just press enter if you want
to start the download of any remaining files.
You can also enter a single digit from the list below to
select the respective entry for scanning:
1: /mnt
Files to scan:
</screen>
<para>Since you normally don't have another source of files to scan other than your loop mounted ISO file (or your CD), press
&lt;ENTER&gt;. Jigdo-lite will then ask you about which mirrors you want to use, just like it did when you downloaded your
ISO for the first time. You've already answered these questions before, but if you truly don't remember, you might want to
re-read <xref linkend="specifyamirror">.</para>
<para>At this point, you'll see jigdo-lite working its magic. Now wasn't that easy?</para>
</sect1>
<sect1><title>Frequently Asked Questions</title>
<sect2><title>How can I make jigdo use a proxy?</title>
<para>This is described on <ulink url="http://debian.org/CD/jigdo-cd/">http://debian.org/CD/jigdo-cd/</ulink> as well as
the <filename>README</filename> of the jigdo-lite tarball.</para>
</sect2>
<sect2 id="interrupted"><title>What do I do if my jigdo download gets interrupted?</title>
<para>If your download gets interrupted, all you need to do is restart jigdo-lite and hit &lt;ENTER&gt; at all the
question prompts. Jigdo-lite will pick up where it left off.</para>
</sect2>
<sect2><title>My jigdo download won't complete because the .jigdo file is broken. When I download a new, fixed .jigdo file,
do I need to download all the data over again?</title>
<para>You may find that the .jigdo file you downloaded is broken. It's very uncommon, but it does happen from time to
time with moving targets like Debian testing or unstable.</para>
<para>If you find that your .jigdo file is broken, you'll need to download a new .jigdo file (when a fixed one becomes
available), but you <emphasis>won't</emphasis> need to download all the ISO data again.</para>
<para>You can use the same loop mounting trick we use when updating an ISO image. The difference is that there's no
finished .iso file to start with, but the .iso.tmp file is an ISO image too and can be used to finish the download without
having to re-download all the data that was downloaded before the broken .jigdo file caused jigdo-file to halt. Simply
loop mount the .tmp.iso file on <filename role="directory">/tmp</filename> and when you re-run jigdo-lite with the fixed
.jigdo file, tell jigdo-lite to scan <filename role="directory">/tmp</filename>. Don't forget to rename or move the
.tmp.iso file so it doesn't interfere with jigdo-lite which will want to create a new .tmp.iso file.</para>
</sect2>
<sect2><title>Can I use jigdo to download images for DVD?</title>
<para>Absolutely; the process is identical to downloading CD images. The only thing you need to do differently is to
download the .jigdo and .template files for DVDs instead of CDs. You can find the DVD .jigdo and .template files at
<ulink url="http://www.debian.org/CD/jigdo-cd/">http://www.debian.org/CD/jigdo-cd/</ulink>.</para>
</sect2>
<sect2><title>Can I burn the <filename>.iso.tmp</filename> file to CD?</title>
<para>We haven't tried yet, but it should be possible. In a wonderful example of irony, the author of jigdo doesn't have
a CD writer (if you have one to donate, you can contact him at <email><ulink
url="mailto:atterer@debian.org">atterer@debian.org</ulink></email> &nbsp; :-) &nbsp;). You'll prolly find some files are
filled with "0"'s. If someone tries it, please contact me at <email><ulink
url="mailto:p@dirac.org">p@dirac.org</ulink></email> and let me know what happened.</para>
<para>But more importantly, why would you WANT to do this? &nbsp; :-)</para>
</sect2>
<sect2><title>Why doesn't jigdo work? It downloads some packages and deletes them. I know it doesn't write them to the
<filename>iso.tmp</filename> file because the file size doesn't change!</title>
<para>Jigdo works just fine - the .iso.tmp file is created at the beginning with its final size, but filled with zero
bytes. Later, parts of it are overwritten with the downloaded data.</para>
<para>You can tell that jigdo is making progress by looking at the messages "<literal>Found X of the Y files required by
the template</literal>" that are printed from time to time. The second value "<literal>Y</literal>" should decrease.
When it reaches zero, the download is finished.</para>
</sect2>
<sect2><title>I'm having trouble getting jigdo-easy to work</title>
<para>See <xref linkend="jigdo-easy">.</para>
</sect2>
<sect2 id="wgetoptions"><title>Jigdo-lite is too verbose. How can I supress some or all of its messages?</title>
<para>Jigdo-lite uses wget, and wget's output can be quite verbose. If this is unsettling, you can make wget more quiet
by adding <literal>--non-verbose</literal> to the <literal>wgetOpts</literal> switch in your
<filename>~/.jigdo-lite</filename> file. If you want wget to print no messages at all, use <literal>--quiet</literal> in
the <literal>wgetOpts</literal> switch.</para>
</sect2>
</sect1>
<sect1 id="errata"><title>Errata</title>
<sect2 id="jigdo-easy"><title>jigdo-easy</title>
<para>Jigdo-easy, by Anne Bezemer, is a fork-off from jigdo-lite which is portable to a wider range of systems, including
Windows. Unfortunately, it is outdated by now and doesn't work with the latest Debian jigdo files. The author seems to
have become disinterested with jigdo-easy and this project appears to be dead.</para>
<para>You should not use jigdo-easy. However, jigdo-lite has been ported to Windows and can be downloaded from the main
jigdo site (<xref linkend="resources">).</para>
</sect2>
<sect2><title>GUI Interface</title>
<para>A GTK+ interface to jigdo is currently being worked on. It's not fully functional yet, but will be available at
some point. There will be a Linux as well as a Windows GUI client.</para>
</sect2>
<sect2 id="jigdo-file-cache"><title>jigdo-file-cache.db</title>
<para>The cache contains the md5sums of files read when you supply a directory at the <literal>Files to scan:</literal>
prompt. If you have jigdo-file scan the same directory a second time, the scan will be very fast.</para>
<para>This could be useful in the following case: rev0 gets updated to rev1. With the rev1 CD images, some packages may
have been pushed from CD <literal>n</literal> to CD <literal>n+1</literal>, or vice versa. If you had a particularly slow
link (e.g. modem), you'd try to avoid downloading these packages again. For this reason, when downloading the new
version of CD <literal>n</literal>, you'd let jigdo-lite scan the three CDs <literal>n-1</literal>, <literal>n</literal>
and <literal>n+1</literal> (or even all 8 CDs if you want to be 100% sure).</para>
<para>If you have jigdo-lite scan the same CDs over and over again while updating each of the 8 CD images, the cache will
prevent all the data on the CDs from being read multiple times.</para>
<para>The cache is much more important when <emphasis>generating</emphasis> jigdo files, because you don't want jigdo-file
to read in your whole 50GB Debian mirror for every generated jigdo file.</para>
</sect2>
<sect2 id="resources"><title>Resources</title>
<para>This HOWTO is winding down to a close, but I thought I'd leave you with a few links and references to learn more
about the jigdo tools and how they work.</para>
<variablelist>
<varlistentry><term><ulink url="http://atterer.net/jigdo">http://atterer.net/jigdo</ulink></term>
<listitem><para>This is the jigdo home site. You should definitely browse this site; lots of information about ports,
GUI clients and everything under the sun relating to jigdo.</para></listitem>
<varlistentry><term><ulink url="http://cdimage.debian.org/~costar/jigdo"
>http://cdimage.debian.org/~costar/jigdo</ulink></term>
<listitem><para>The Debian page for jigdo-easy. See <xref linkend="jigdo-easy"></para></listitem>
<varlistentry><term><ulink url="http://www.debian.org/CD/jigdo-cd">http://www.debian.org/CD/jigdo-cd</ulink></term>
<listitem><para>The main Debian page for jigdo.</para></listitem>
</variablelist>
</sect2>
</sect1>
</article>
<!--
vim: tw=128
-->
<!-- don't run as root -->