doc: Convert from DebianDoc SGML to DocBook XML

1 files changed, 247 insertions, 0 deletions

diff --git a/doc/offline.dbk b/doc/offline.dbk
new file mode 100644
index 000000000..7163f8bd5
--- /dev/null
+++ b/doc/offline.dbk
@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+]>
+
+<book lang="en">
+
+<title>Using APT Offline</title>
+
+<bookinfo>
+
+<authorgroup>
+  <author>
+    <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
+  </author>
+</authorgroup>
+
+<releaseinfo>Version &apt-product-version;</releaseinfo>
+
+<abstract>
+<para>
+This document describes how to use APT in a non-networked environment,
+specifically a 'sneaker-net' approach for performing upgrades.
+</para>
+</abstract>
+
+<copyright><year>1999</year><holder>Jason Gunthorpe</holder></copyright>
+
+<legalnotice>
+<title>License Notice</title>
+<para>
+"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.
+</para>
+<para>
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<chapter id="ch1"><title>Introduction</title>
+
+<section id="s1.1"><title>Overview</title>
+<para>
+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.
+</para>
+<para>
+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 <emphasis>remote
+host</emphasis> mean the machine downloading the packages, and <emphasis>target
+host</emphasis> the one with bad or no connection.
+</para>
+<para>
+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.
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch2"><title>Using APT on both machines</title>
+
+<section id="s2.1"><title>Overview</title>
+<para>
+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:
+</para>
+<screen>
+  /disc/
+    archives/
+       partial/
+    lists/
+       partial/
+    status
+    sources.list
+    apt.conf
+</screen>
+</section>
+
+<section id="s2.2"><title>The configuration file</title>
+<para>
+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 <emphasis>/var/lib/dpkg/status</emphasis> from
+the <emphasis>target host</emphasis>. Please note, if you are using a local
+archive you must use copy URIs, the syntax is identical to file URIs.
+</para>
+<para>
+<emphasis>apt.conf</emphasis> must contain the necessary information to make
+APT use the disc:
+</para>
+<screen>
+ 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/";
+ };
+</screen>
+<para>
+More details can be seen by examining the apt.conf man page and the sample
+configuration file in
+<emphasis>/usr/share/doc/apt/examples/apt.conf</emphasis>.
+</para>
+<para>
+On the target machine the first thing to do is mount the disc and copy
+<emphasis>/var/lib/dpkg/status</emphasis> to it. You will also need
+to create the directories outlined in the Overview,
+<emphasis>archives/partial/</emphasis> and
+<emphasis>lists/partial/</emphasis>. Then take the disc to the
+remote machine and configure the sources.list. On the remote
+machine execute the following:
+</para>
+<screen>
+ # 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 ]
+</screen>
+<para>
+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
+<emphasis>dselect</emphasis>. However this presents a problem in communicating
+your selections back to the local computer.
+</para>
+<para>
+Now the disc contains all of the index files and archives needed to upgrade the
+target machine. Take the disc back and run:
+</para>
+<screen>
+  # 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 ]
+</screen>
+<para>
+It is necessary for proper function to re-specify the status file to be the
+local one. This is very important!
+</para>
+<para>
+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!!
+</para>
+</section>
+
+</chapter>
+
+<chapter id="ch3"><title>Using APT and wget</title>
+
+<section id="s3.1"><title>Overview</title>
+<para>
+<emphasis>wget</emphasis> 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.
+</para>
+<para>
+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.
+</para>
+</section>
+
+<section id="s3.2"><title>Operation</title>
+<para>
+Unlike the previous technique no special configuration files are required. We
+merely use the standard APT commands to generate the file list.
+</para>
+<screen>
+ # apt-get dist-upgrade
+ [ Press no when prompted, make sure you are happy with the actions ]
+ # apt-get -qq --print-uris dist-upgrade &gt; uris
+ # awk '{print "wget -O " $2 " " $1}' &lt; uris &gt; /disc/wget-script
+</screen>
+<para>
+Any command other than dist-upgrade could be used here, including
+dselect-upgrade.
+</para>
+<para>
+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.
+</para>
+<para>
+The remote machine would do something like
+</para>
+<screen>
+  # cd /disc
+  # sh -x ./wget-script
+  [ wait.. ]
+</screen>
+<para>
+Once the archives are downloaded and the disc returned to the Debian machine
+installation can proceed using,
+</para>
+<screen>
+  # apt-get -o dir::cache::archives="/disc/" dist-upgrade
+</screen>
+<para>
+Which will use the already fetched archives on the disc.
+</para>
+</section>
+
+</chapter>
+
+</book>