doc/offline.dbk

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
   5 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
   6 <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
   7 ]>
   8
   9 <book lang="en">
  10
  11 <title>Using APT Offline</title>
  12
  13 <bookinfo>
  14
  15 <authorgroup>
  16   <author>
  17     <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
  18   </author>
  19 </authorgroup>
  20
  21 <releaseinfo>Version &apt-product-version;</releaseinfo>
  22
  23 <abstract>
  24 <para>
  25 This document describes how to use APT in a non-networked environment,
  26 specifically a 'sneaker-net' approach for performing upgrades.
  27 </para>
  28 </abstract>
  29
  30 <copyright><year>1999</year><holder>Jason Gunthorpe</holder></copyright>
  31
  32 <legalnotice>
  33 <title>License Notice</title>
  34 <para>
  35 "APT" and this document are free software; you can redistribute them and/or
  36 modify them under the terms of the GNU General Public License as published by
  37 the Free Software Foundation; either version 2 of the License, or (at your
  38 option) any later version.
  39 </para>
  40 <para>
  41 For more details, on Debian systems, see the file
  42 /usr/share/common-licenses/GPL for the full license.
  43 </para>
  44 </legalnotice>
  45
  46 </bookinfo>
  47
  48 <chapter id="ch1"><title>Introduction</title>
  49
  50 <section id="s1.1"><title>Overview</title>
  51 <para>
  52 Normally APT requires direct access to a Debian archive, either from a local
  53 media or through a network. Another common complaint is that a Debian machine
  54 is on a slow link, such as a modem and another machine has a very fast
  55 connection but they are physically distant.
  56 </para>
  57 <para>
  58 The solution to this is to use large removable media such as a Zip disc or a
  59 SuperDisk disc. These discs are not large enough to store the entire Debian
  60 archive but can easily fit a subset large enough for most users. The idea is
  61 to use APT to generate a list of packages that are required and then fetch them
  62 onto the disc using another machine with good connectivity. It is even
  63 possible to use another Debian machine with APT or to use a completely
  64 different OS and a download tool like wget. Let <emphasis>remote
  65 host</emphasis> mean the machine downloading the packages, and <emphasis>target
  66 host</emphasis> the one with bad or no connection.
  67 </para>
  68 <para>
  69 This is achieved by creatively manipulating the APT configuration file. The
  70 essential premise to tell APT to look on a disc for it's archive files. Note
  71 that the disc should be formatted with a filesystem that can handle long file
  72 names such as ext2, fat32 or vfat.
  73 </para>
  74 </section>
  75
  76 </chapter>
  77
  78 <chapter id="ch2"><title>Using APT on both machines</title>
  79
  80 <section id="s2.1"><title>Overview</title>
  81 <para>
  82 APT being available on both machines gives the simplest configuration. The
  83 basic idea is to place a copy of the status file on the disc and use the remote
  84 machine to fetch the latest package files and decide which packages to
  85 download. The disk directory structure should look like:
  86 </para>
  87 <screen>
  88   /disc/
  89     archives/
  90        partial/
  91     lists/
  92        partial/
  93     status
  94     sources.list
  95     apt.conf
  96 </screen>
  97 </section>
  98
  99 <section id="s2.2"><title>The configuration file</title>
 100 <para>
 101 The configuration file should tell APT to store its files on the disc and to
 102 use the configuration files on the disc as well. The sources.list should
 103 contain the proper sites that you wish to use from the remote machine, and the
 104 status file should be a copy of <emphasis>/var/lib/dpkg/status</emphasis> from
 105 the <emphasis>target host</emphasis>. Please note, if you are using a local
 106 archive you must use copy URIs, the syntax is identical to file URIs.
 107 </para>
 108 <para>
 109 <emphasis>apt.conf</emphasis> must contain the necessary information to make
 110 APT use the disc:
 111 </para>
 112 <screen>
 113  APT
 114  {
 115    /* This is not necessary if the two machines are the same arch, it tells
 116       the remote APT what architecture the target machine is */
 117    Architecture "i386";
 118
 119    Get::Download-Only "true";
 120  };
 121
 122  Dir
 123  {
 124    /* Use the disc for state information and redirect the status file from
 125       the /var/lib/dpkg default */
 126    State "/disc/";
 127    State::status "status";
 128
 129    // Binary caches will be stored locally
 130    Cache::archives "/disc/archives/";
 131    Cache "/tmp/";
 132
 133    // Location of the source list.
 134    Etc "/disc/";
 135  };
 136 </screen>
 137 <para>
 138 More details can be seen by examining the apt.conf man page and the sample
 139 configuration file in
 140 <emphasis>/usr/share/doc/apt/examples/apt.conf</emphasis>.
 141 </para>
 142 <para>
 143 On the target machine the first thing to do is mount the disc and copy
 144 <emphasis>/var/lib/dpkg/status</emphasis> to it. You will also need
 145 to create the directories outlined in the Overview,
 146 <emphasis>archives/partial/</emphasis> and
 147 <emphasis>lists/partial/</emphasis>. Then take the disc to the
 148 remote machine and configure the sources.list. On the remote
 149 machine execute the following:
 150 </para>
 151 <screen>
 152  # export APT_CONFIG="/disc/apt.conf"
 153  # apt-get update
 154  [ APT fetches the package files ]
 155  # apt-get dist-upgrade
 156  [ APT fetches all the packages needed to upgrade the target machine ]
 157 </screen>
 158 <para>
 159 The dist-upgrade command can be replaced with any other standard APT commands,
 160 particularly dselect-upgrade. You can even use an APT front end such as
 161 <emphasis>dselect</emphasis>. However this presents a problem in communicating
 162 your selections back to the local computer.
 163 </para>
 164 <para>
 165 Now the disc contains all of the index files and archives needed to upgrade the
 166 target machine. Take the disc back and run:
 167 </para>
 168 <screen>
 169   # export APT_CONFIG="/disc/apt.conf"
 170   # apt-get check
 171   [ APT generates a local copy of the cache files ]
 172   # apt-get --no-d -o dir::state::status=/var/lib/dpkg/status dist-upgrade
 173   [ Or any other APT command ]
 174 </screen>
 175 <para>
 176 It is necessary for proper function to re-specify the status file to be the
 177 local one. This is very important!
 178 </para>
 179 <para>
 180 If you are using dselect you can do the very risky operation of copying
 181 disc/status to /var/lib/dpkg/status so that any selections you made on the
 182 remote machine are updated. I highly recommend that people only make
 183 selections on the local machine - but this may not always be possible. DO NOT
 184 copy the status file if dpkg or APT have been run in the mean time!!
 185 </para>
 186 </section>
 187
 188 </chapter>
 189
 190 <chapter id="ch3"><title>Using APT and wget</title>
 191
 192 <section id="s3.1"><title>Overview</title>
 193 <para>
 194 <emphasis>wget</emphasis> is a popular and portable download tool that can run
 195 on nearly any machine. Unlike the method above this requires that the Debian
 196 machine already has a list of available packages.
 197 </para>
 198 <para>
 199 The basic idea is to create a disc that has only the archive files downloaded
 200 from the remote site. This is done by using the --print-uris option to apt-get
 201 and then preparing a wget script to actually fetch the packages.
 202 </para>
 203 </section>
 204
 205 <section id="s3.2"><title>Operation</title>
 206 <para>
 207 Unlike the previous technique no special configuration files are required. We
 208 merely use the standard APT commands to generate the file list.
 209 </para>
 210 <screen>
 211  # apt-get dist-upgrade
 212  [ Press no when prompted, make sure you are happy with the actions ]
 213  # apt-get -qq --print-uris dist-upgrade &gt; uris
 214  # awk '{print "wget -O " $2 " " $1}' &lt; uris &gt; /disc/wget-script
 215 </screen>
 216 <para>
 217 Any command other than dist-upgrade could be used here, including
 218 dselect-upgrade.
 219 </para>
 220 <para>
 221 The /disc/wget-script file will now contain a list of wget commands to execute
 222 in order to fetch the necessary archives. This script should be run with the
 223 current directory as the disc's mount point so as to save the output on the
 224 disc.
 225 </para>
 226 <para>
 227 The remote machine would do something like
 228 </para>
 229 <screen>
 230   # cd /disc
 231   # sh -x ./wget-script
 232   [ wait.. ]
 233 </screen>
 234 <para>
 235 Once the archives are downloaded and the disc returned to the Debian machine
 236 installation can proceed using,
 237 </para>
 238 <screen>
 239   # apt-get -o dir::cache::archives="/disc/" dist-upgrade
 240 </screen>
 241 <para>
 242 Which will use the already fetched archives on the disc.
 243 </para>
 244 </section>
 245
 246 </chapter>
 247
 248 </book>