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