document the pkg:any specialcasing in FindPkg as well to make it clear

[apt.git] / doc / offline.sgml

<!-- -*- mode: sgml; mode: fold -*- -->
<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
<book>
<title>Using APT Offline</title>

<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
<version>$Id: offline.sgml,v 1.8 2003/02/12 15:06:41 doogie Exp $</version>

<abstract>
This document describes how to use APT in a non-networked environment, 
specifically a 'sneaker-net' approach for performing upgrades.
</abstract>

<copyright>
Copyright &copy; Jason Gunthorpe, 1999.
<p>
"APT" and this document are free software; you can redistribute them and/or
modify them under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

<p>
For more details, on Debian GNU/Linux systems, see the file
/usr/share/common-licenses/GPL for the full license.
</copyright>

<toc sect>

<chapt>Introduction
<!-- Overview		                                               {{{ -->
<!-- ===================================================================== -->
<sect>Overview

<p>
Normally APT requires direct access to a Debian archive, either from a local
media or through a network. Another common complaint is that a Debian machine
is on a slow link, such as a modem and another machine has a very fast 
connection but they are physically distant.

<p>
The solution to this is to use large removable media such as a Zip disc or a 
SuperDisk disc. These discs are not large enough to store the entire Debian
archive but can easily fit a subset large enough for most users. The idea
is to use APT to generate a list of packages that are required and then fetch
them onto the disc using another machine with good connectivity. It is 
even possible to use another Debian machine with APT or to use a completely 
different OS and a download tool like wget. Let <em>remote host</em> mean the
machine downloading the packages, and <em>target host</em> the one with bad or
no connection.

<p>
This is achieved by creatively manipulating the APT configuration file. The
essential premise to tell APT to look on a disc for it's archive files. Note
that the disc should be formated with a filesystem that can handle long file
names such as ext2, fat32 or vfat.

</sect>
                                                                  <!-- }}} -->

<chapt>Using APT on both machines
<!-- Overview		                                               {{{ -->
<!-- ===================================================================== -->
<sect>Overview

<p>
APT being available on both machines gives the simplest configuration. The 
basic idea is to place a copy of the status file on the disc and use the 
remote machine to fetch the latest package files and decide which packages to 
download. The disk directory structure should look like:

<example>
  /disc/
    archives/
       partial/
    lists/
       partial/
    status
    sources.list
    apt.conf
</example>

</sect>
                                                                  <!-- }}} -->
<!-- The configuartion file                                            {{{ -->
<!-- ===================================================================== -->
<sect>The configuration file

<p>
The configuration file should tell APT to store its files on the disc and
to use the configuration files on the disc as well. The sources.list should
contain the proper sites that you wish to use from the remote machine, and
the status file should be a copy of <em>/var/lib/dpkg/status</em> from the
<em>target host</em>. Please note, if you are using a local archive you must use
copy URIs, the syntax is identical to file URIs.

<p>
<em>apt.conf</em> must contain the necessary information to make APT use the 
disc:

<example>
 APT
 {
   /* This is not necessary if the two machines are the same arch, it tells
      the remote APT what architecture the target machine is */
   Architecture "i386";
   
   Get::Download-Only "true";
 };
 
 Dir
 {
   /* Use the disc for state information and redirect the status file from
      the /var/lib/dpkg default */
   State "/disc/";
   State::status "status";

   // Binary caches will be stored locally
   Cache::archives "/disc/archives/";
   Cache "/tmp/";
   
   // Location of the source list.
   Etc "/disc/";
 }; 
</example>

More details can be seen by examining the apt.conf man page and the sample
configuration file in <em>/usr/share/doc/apt/examples/apt.conf</em>.

<p>
On the target machine the first thing to do is mount the disc and copy 
<em>/var/lib/dpkg/status</em> to it. You will also need to create the directories
outlined in the Overview, <em>archives/partial/</em> and <em>lists/partial/</em>.
Then take the disc to the remote machine and configure the sources.list. 
On the remote machine execute the following:

<example>
 # export APT_CONFIG="/disc/apt.conf"
 # apt-get update
 [ APT fetches the package files ]
 # apt-get dist-upgrade
 [ APT fetches all the packages needed to upgrade the target machine ]
</example>

The dist-upgrade command can be replaced with any other standard APT commands,
particularly dselect-upgrade. You can even use an APT front end such as 
<em>dselect</em>. However this presents a problem in communicating your 
selections back to the local computer.

<p>
Now the disc contains all of the index files and archives needed to upgrade
the target machine. Take the disc back and run:

<example>
  # export APT_CONFIG="/disc/apt.conf"
  # apt-get check
  [ APT generates a local copy of the cache files ]
  # apt-get --no-d -o dir::state::status=/var/lib/dpkg/status dist-upgrade
  [ Or any other APT command ]
</example>

<p> 
It is necessary for proper function to re-specify the status file to be the 
local one. This is very important!

<p>
If you are using dselect you can do the very risky operation of copying 
disc/status to /var/lib/dpkg/status so that any selections you made on the
remote machine are updated. I highly recommend that people only make selections
on the local machine - but this may not always be possible. DO NOT copy
the status file if dpkg or APT have been run in the mean time!!

</sect>
                                                                  <!-- }}} -->

<chapt>Using APT and wget
<!-- Overview		                                               {{{ -->
<!-- ===================================================================== -->
<sect>Overview

<p>
<em>wget</em> is a popular and portable download tool that can run on nearly
any machine. Unlike the method above this requires that the Debian machine
already has a list of available packages.

<p>
The basic idea is to create a disc that has only the archive files downloaded
from the remote site. This is done by using the --print-uris option to apt-get
and then preparing a wget script to actually fetch the packages.

</sect>
                                                                  <!-- }}} -->
<!-- Operation		                                               {{{ -->
<!-- ===================================================================== -->
<sect>Operation

<p>
Unlike the previous technique no special configuration files are required. We
merely use the standard APT commands to generate the file list.

<example>
 # apt-get dist-upgrade 
 [ Press no when prompted, make sure you are happy with the actions ]
 # apt-get -qq --print-uris dist-upgrade > uris
 # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script
</example>

Any command other than dist-upgrade could be used here, including 
dselect-upgrade.

<p>
The /disc/wget-script file will now contain a list of wget commands to execute 
in order to fetch the necessary archives. This script should be run with the
current directory as the disc's mount point so as to save the output on the 
disc.

<p>
The remote machine would do something like

<example>
  # cd /disc
  # sh -x ./wget-script
  [ wait.. ]
</example>

Once the archives are downloaded and the disc returned to the Debian machine
installation can proceed using,

<example>
  # apt-get -o dir::cache::archives="/disc/" dist-upgrade
</example>

Which will use the already fetched archives on the disc.

</sect>
                                                                  <!-- }}} -->
</book>