make setup in travis.yml a bit more verbose
[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 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. Let <em>remote host</em> mean the
48 machine downloading the packages, and <em>target host</em> the one with bad or
49 no connection.
50
51 <p>
52 This is achieved by creatively manipulating the APT configuration file. The
53 essential premise to tell APT to look on a disc for it's archive files. Note
54 that the disc should be formated with a filesystem that can handle long file
55 names such as ext2, fat32 or vfat.
56
57 </sect>
58 <!-- }}} -->
59
60 <chapt>Using APT on both machines
61 <!-- Overview {{{ -->
62 <!-- ===================================================================== -->
63 <sect>Overview
64
65 <p>
66 APT being available on both machines gives the simplest configuration. The
67 basic idea is to place a copy of the status file on the disc and use the
68 remote machine to fetch the latest package files and decide which packages to
69 download. The disk directory structure should look like:
70
71 <example>
72 /disc/
73 archives/
74 partial/
75 lists/
76 partial/
77 status
78 sources.list
79 apt.conf
80 </example>
81
82 </sect>
83 <!-- }}} -->
84 <!-- The configuartion file {{{ -->
85 <!-- ===================================================================== -->
86 <sect>The configuration file
87
88 <p>
89 The configuration file should tell APT to store its files on the disc and
90 to use the configuration files on the disc as well. The sources.list should
91 contain the proper sites that you wish to use from the remote machine, and
92 the status file should be a copy of <em>/var/lib/dpkg/status</em> from the
93 <em>target host</em>. Please note, if you are using a local archive you must use
94 copy URIs, the syntax is identical to file URIs.
95
96 <p>
97 <em>apt.conf</em> must contain the necessary information to make APT use the
98 disc:
99
100 <example>
101 APT
102 {
103 /* This is not necessary if the two machines are the same arch, it tells
104 the remote APT what architecture the target machine is */
105 Architecture "i386";
106
107 Get::Download-Only "true";
108 };
109
110 Dir
111 {
112 /* Use the disc for state information and redirect the status file from
113 the /var/lib/dpkg default */
114 State "/disc/";
115 State::status "status";
116
117 // Binary caches will be stored locally
118 Cache::archives "/disc/archives/";
119 Cache "/tmp/";
120
121 // Location of the source list.
122 Etc "/disc/";
123 };
124 </example>
125
126 More details can be seen by examining the apt.conf man page and the sample
127 configuration file in <em>/usr/share/doc/apt/examples/apt.conf</em>.
128
129 <p>
130 On the target machine the first thing to do is mount the disc and copy
131 <em>/var/lib/dpkg/status</em> to it. You will also need to create the directories
132 outlined in the Overview, <em>archives/partial/</em> and <em>lists/partial/</em>.
133 Then take the disc to the remote machine and configure the sources.list.
134 On the remote machine execute the following:
135
136 <example>
137 # export APT_CONFIG="/disc/apt.conf"
138 # apt-get update
139 [ APT fetches the package files ]
140 # apt-get dist-upgrade
141 [ APT fetches all the packages needed to upgrade the target machine ]
142 </example>
143
144 The dist-upgrade command can be replaced with any other standard APT commands,
145 particularly dselect-upgrade. You can even use an APT front end such as
146 <em>dselect</em>. However this presents a problem in communicating your
147 selections back to the local computer.
148
149 <p>
150 Now the disc contains all of the index files and archives needed to upgrade
151 the target machine. Take the disc back and run:
152
153 <example>
154 # export APT_CONFIG="/disc/apt.conf"
155 # apt-get check
156 [ APT generates a local copy of the cache files ]
157 # apt-get --no-d -o dir::state::status=/var/lib/dpkg/status dist-upgrade
158 [ Or any other APT command ]
159 </example>
160
161 <p>
162 It is necessary for proper function to re-specify the status file to be the
163 local one. This is very important!
164
165 <p>
166 If you are using dselect you can do the very risky operation of copying
167 disc/status to /var/lib/dpkg/status so that any selections you made on the
168 remote machine are updated. I highly recommend that people only make selections
169 on the local machine - but this may not always be possible. DO NOT copy
170 the status file if dpkg or APT have been run in the mean time!!
171
172 </sect>
173 <!-- }}} -->
174
175 <chapt>Using APT and wget
176 <!-- Overview {{{ -->
177 <!-- ===================================================================== -->
178 <sect>Overview
179
180 <p>
181 <em>wget</em> is a popular and portable download tool that can run on nearly
182 any machine. Unlike the method above this requires that the Debian machine
183 already has a list of available packages.
184
185 <p>
186 The basic idea is to create a disc that has only the archive files downloaded
187 from the remote site. This is done by using the --print-uris option to apt-get
188 and then preparing a wget script to actually fetch the packages.
189
190 </sect>
191 <!-- }}} -->
192 <!-- Operation {{{ -->
193 <!-- ===================================================================== -->
194 <sect>Operation
195
196 <p>
197 Unlike the previous technique no special configuration files are required. We
198 merely use the standard APT commands to generate the file list.
199
200 <example>
201 # apt-get dist-upgrade
202 [ Press no when prompted, make sure you are happy with the actions ]
203 # apt-get -qq --print-uris dist-upgrade > uris
204 # awk '{print "wget -O " $2 " " $1}' < uris > /disc/wget-script
205 </example>
206
207 Any command other than dist-upgrade could be used here, including
208 dselect-upgrade.
209
210 <p>
211 The /disc/wget-script file will now contain a list of wget commands to execute
212 in order to fetch the necessary archives. This script should be run with the
213 current directory as the disc's mount point so as to save the output on the
214 disc.
215
216 <p>
217 The remote machine would do something like
218
219 <example>
220 # cd /disc
221 # sh -x ./wget-script
222 [ wait.. ]
223 </example>
224
225 Once the archives are downloaded and the disc returned to the Debian machine
226 installation can proceed using,
227
228 <example>
229 # apt-get -o dir::cache::archives="/disc/" dist-upgrade
230 </example>
231
232 Which will use the already fetched archives on the disc.
233
234 </sect>
235 <!-- }}} -->
236 </book>