english/apt-move/apt-move.8

.\" Copyright (c) 1999 Michael Merten <mikemerten@yahoo.com>
.\" Copyright (c) 2000-2002 Herbert Xu <herbert@debian.org>
.\" May be distributed under the terms of version 2 of the
.\" GNU GPL. See the LICENSE file included with this package.
.\" $Id: apt-move.8,v 1.20 2002/10/23 22:16:34 herbert Exp $
.TH APT\-MOVE 8 "2002 Oct 7th" "APT-MOVE"

.SH NAME
apt\-move \- move cache of Debian packages into a mirror hierarchy.

.SH SYNOPSIS

.B apt\-move
.RB [ \-c
.IR conffile ]
.RB [ \-d
.IR dist ]
.RB [ \-fqt ]
.I command


.SH DESCRIPTION

The
.B apt\-move
script is used to move a collection of Debian package files into a proper
archive hierarchy of the form
.B $LOCALDIR/pool/...
where
.B LOCALDIR
is specified in the configuration file.
It is intended as a tool to help manage the
.BR apt\-get (8)
file cache, but could be configured to work with any collection
of Debian packages.

.PP
Additionally, using the
.I sync
and
.I mirror
commands, you can build your own local mirror of portions of a selected
binary and/or source distribution.

.PP
Running
.B apt\-move
periodically will assist in managing the resulting partial mirror
by (optionally) removing obsolete packages and creating valid local
Packages.gz and Sources.gz.

.SS "Commands"
The following commands are accepted by
.BR apt\-move :

.TP
.B get \fR[ \fIdir \fR]
This generates the master files using Packages and Sources files from the
.BR apt (8)
cache.  The master files are used to keep track of what packages are
available, and where packages should be installed.  If
.I dir
is specified, it will be used in lieu of the
.B LISTSTATE
variable.

.TP
.B getlocal \fR[ \fIdir \fR]
This is an alias of get.  It may be removed in future releases.

.TP
.B move
Moves a collection of packages into the local mirror tree.  Uses existing
master files (see
.IR get )
to repair any mangling done to the package names.  Any packages that aren't
listed in the master files will be left in the file cache directory.

.TP
.B delete
Delete obsolete package files.  Configurable through the
.I DELETE
and
.I MAXDELETE
settings in the
.B /etc/apt\-move.conf
file (see the
.I CONFIGURATION
section below).

.TP
.B packages
Builds new local versions of Packages.gz and Sources.gz files.

.TP
.B fsck
Rebuilds all index files used to make Packages and Sources files and reprocess
all packages in the archive by calling
.B movefile
on them.  Use this if you are upgrading from an old version (<< 4.2) of
.BR apt-move .

.TP
.B update
This is an alias, equivalent to
.RI ' get
.I move
.I delete
.IR packages '.
This is the preferred method for moving package files from your
cache into a local mirror.

.TP
.B local
This is an alias, equivalent to
.RI ' move
.I delete
.IR packages '.

.TP
.B localupdate
This is an alias for update.  It may be removed in future releases.

.TP
.B mirror
This command automatically runs
.IR get ,
then uses
.B /usr/lib/apt-move/fetch
and
.BR apt-get (8)
to download any packages missing from your mirror.  The downloaded files will
be installed into the repository using
.IR move .
Finally, it runs
.I packages
and exits.
See the
.I DIST
and
.I PKGTYPE
settings in
.BR /etc/apt\-move.conf .
Before using this command, you need to set up a
.B $LOCALDIR/.exclude
file containing patterns to exclude
unwanted files from your mirror.  See the
.B SAMPLE.exclude
file for an example.  See also the
.I "Exclude file"
section of
.I NOTES
below.  Note that this command will only mirror packages for the architecture
that you are running on.  It will, however, mirror all source packages.

.TP
.B sync
Similar to the
.I mirror
function, but only gets the packages that are currently installed on
your system.  It uses
.BR dpkg (8)
.I \-\-get\-selections
to find out what files to download.  It will skip any files that
match one of the patterns in the
.B $LOCALDIR/.exclude
file (if it exists).
.B sync
will get the latest versions of the packages, regardless of the
version currently installed on your system (think about it).

.TP
.B exclude
This command is used to test your
.B $LOCALDIR/.exclude
pattern file.  It will
go through the master lists and print any file that matches one
of the patters in
.BR $LOCALDIR/.exclude .
This will show you exactly what
files you have EXCLUDED from your mirror.  The
.B \-t
(test) flag has no affect on this command.  This
uses your existing master files, and does not require an internet
connection.

.TP
.BI movefile \ files...
This command is similar to move.  Instead of moving files from
.IR FILECACHE ,
it will move the files specified on the command line.

.TP
\fBlistbin \fR[ \fBmirror \fR| \fBsync \fR| \fBrepo \fR]
This command prints a list of packages which may serve as the input to
mirrorbin or mirrorsrc.  If the argument is
.B mirror
or
.BR sync ,
it will produce the same lists that the
.B mirror
and
.B sync
commands use.  If the argument is
.BR repo ,
the list produced will contain the packages that are currently in the
apt-move repository.

.TP
.B mirrorbin
This command will fetch the list of packages specified on the standard input,
and place them into the archive in the same way as
.B mirror
does.

.TP
.B mirrorsrc
This commands acts like
.BR mirrorbin ,
except that it fetches source packages instead of binary ones.

.SS Options
The following options are available from the command line:

.TP
\fB\-c \fIconffile
Use
.I conffile
as the configuration file instead of
.BR /etc/apt\-move.conf .

.TP
\fB\-d \fIdist
Use
.I dist
as the default suite instead of the value of
.I DIST
from the configuration file.

.TP
.B \-f
Forces deletion of files even when the percentage of files to
delete exceeds the
.I MAXDELETE
setting.  This is useful if
.B apt\-move
aborts with an error saying that too many files would be deleted, and you
want to delete the files anyway.  (Use with caution.) If you get this error,
using
.B \-ft
will show you the complete list of files, so you can verify them before
you use
.BR \-f.

.TP
.B \-q
Suppresses normal output.  This option is useful when
.B apt\-move
is used in a non-interactive script.

.TP
.B \-t
Makes a 'test run' and reports what WOULD be done for
.B option
but does not modify any of the cache or mirror files.

.SH CONFIGURATION

Before using
.BR apt\-move ,
edit the
.B /etc/apt\-move.conf
file to match your local setup.  Always remember to use the
.I test
parameter after any change in your configuration to make sure it will
work like you want it to.  You may also want to set the
.I DELETE
option to
.I no
to turn off file deletes until everything else is working successfully.

.PP
The following settings are recognized by
.B apt-move
(shown here with their defaults):

.TP
.BR APTSITES= """debian.midco.net non-us.debian.org"""
Set this to the names of sites in your
.B /etc/apt/sources.list
that you wish to mirror.

.TP
.BR ARCHS= """alpha arm hurd-i386 i386 m68k powerpc sparc"""
This is a list of the architectures that you mirror.
As of potato, set to only one of:
.IR alpha ,
.IR arm ,
.IR hurd\-i386 ,
.IR i386 ,
.IR m68k ,
.I powerpc
or
.IR sparc .
Determines the creation of links to binary-all packages, as well as Packages
and Sources files.

.TP
.BR LOCALDIR= /mirrors/debian
This is the full (absolute) path to your debian directory (the top of your
local mirror).

.TP
.BR DIST= stable
This is the suite that will be mirrored by
.BR apt-move .
It must match the
.B Archive
field in the corresponding
.I Release
files.  It is also used as the default suite to hold packages when the
.I Release
files are missing.

.TP
.BR PKGTYPE= binary
Set this to your choice of:
.IR binary ,
.I source
or
.I both
to tell the
.IR mirror ,
.I sync
and
.I movefile
which type(s) of files to get.

.TP
.BR FILECACHE= /var/cache/apt/archives
The directory where your local cache of packages are. The default will work
for the
.BR apt-get (8)
packages, unless you've changed the configuration in
.BR /etc/apt/apt.conf .

.TP
.BR LISTSTATE= /var/lib/apt/lists
The directory to your local cache of Packages files. The default will work
for the
.BR apt-get (8)
packages, unless you've changed the configuration in
.BR /etc/apt/apt.conf .

.TP
.BR DELETE= no
Determines whether obsolete packages (packages not listed in the master file,
or packages that have been superceded in the repository) are to be removed.

.TP
.BR MAXDELETE= 20
Maximum percentage of files
.B apt\-move
is allowed to delete during a normal run.  Anything exceeding this will
produce an error and abort the script.  I added this as a precaution
so that you won't lose your entire mirror when a new distribution is
released.  You can override this (with caution) using the
.I \-f
parameter with
.BR apt\-move .

.TP
.BR COPYONLY= no
If this is set to yes, then
.B move
and
.B movefile
will copy instead of move.  That is, the originals will be left alone.

.TP
.BR PKGCOMP= gzip
This should be set to a list of compression formats that apt-move should
provide when generating Packages and Sources files.  The possible values
are
.BR none ,
.B gzip
and
.BR bzip2 .

.PP
For the
.I sync
and
.I mirror
commands to function correctly, you need to list your
.B apt\-move
repository at the top of
.BR /etc/apt/sources.list
as a
.BR file\ URI .

.SH FILES

.TP
.B /usr/bin/apt\-move
The script.

.TP
.B /etc/apt\-move.conf
Configuration file for the script.

.TP
.B /usr/share/man/man8/apt\-move.8.gz
The manpage.

.TP
.B /tmp/MOVE_*
The temporary files created at runtime.

.TP
.B /usr/lib/apt-move/fetch
Utility to fetch files just like
.IR "apt-get install -d" .
Except that no dependency analysis is done.

.TP
.B .apt-move/*.{binary, source}.local
Put entries of local packages here.  The fields are
``package priority section source version task'' for the binary file, and
``package priority section version'' for the source file.  The
.B version
field may be set to a single dash to refer to the latest version in the
archive.  Blank lines and lines beginning with a hash are ignored.

.SH "SEE ALSO"

.BR dpkg (8),
.BR apt\-get (8)

.SH NOTES
.SS "Exclude file"
The
.I mirror
command uses a file in the
.B $LOCALDIR/
directory called '.exclude' which contains
exclude patterns that are applied against the files to be mirrored.
These patterns were created with the following limitation: they must work
the same with with
.BR grep (1),
after any '*' characters are removed.  Unless you're careful setting this up,
you'll get unexpected results.  Run
.RB "'" apt-move
.B \-t
.BR mirror "'"
first, to make sure you're getting the results you intended.  Another way to
verify your exclude file is the use the
.I exclude
command for
.B apt\-move
to print a list of files your are excluding from your mirror.  See the sample
 .exclude file (SAMPLE.exclude) for an example of an .exclude file.

.SS Mirroring
The
.B apt\-move
.B mirror
and
.B sync
commands
do not test for available disk space.  The current
potato (main binary) distribution is over 1Gb in size.  Add the sources to
that and it can eat up the space on a partition really fast. I would advise you
to put your mirror somewhere other than the root partition.  Set up your
exclude file and run
.B "apt\-move -t mirror"
and examine the result.

.SS "Code names"
Since
.B apt\-move
gets the suite names from
.I Release
files, which usually use the names
.IR stable ,
.I testing
and
.IR unstable ,
the suites in the repository are named accordingly.  You can simulate the
code names by creating symbolic links in the
.I dists
directory.  For example, in order to make
.I testing
equivalent to
.IR sarge ,
you could run
.BR "ln -s testing $LOCALDIR/sarge" .
Alternatively, you could delete the
.I testing
subdirectory and run
.BR "ln -s sarge $LOCALDIR/testing" .
This will cause future executions of the
.I get
operation to use
.I sarge
whenever it sees
.I testing
in the
.I Release
file.

.SH DIAGNOSTICS

.B apt\-move
may exit with one of the following error messages:

.TP
.B "Could not read configuration."
.B apt\-move
could not find the
.B /etc/apt-move.conf
file.  Run the install script.

.TP
.B "Could not create directory."
For some reason, a necessary directory could not be created.

.TP
.B "You failed to select a distribution."
You did not configure a
.I DIST
setting in /etc/apt-move.conf.

.TP
.B "You specified an invalid pacakge type."
You can only use
.IR binary ,
.I source
or
.I both
for the PKGTYPE setting.

.TP
.B "No master files exist!"
You need to run
.B apt-\move
with the
.B get
command at least once in order to create the master files which determine
where packages are to be installed.

.TP
.B "bc calculation returned invalid result"
.B apt\-move
uses the
.BR bc (1)
program to determine when the number of files to delete will exceed the
.I MAXDELETE
setting in
.BR apt\-move.conf .
If you get this error, make sure that
.I MAXDELETE
is set to a number in the range of 1 to 100, without the % sign.  Otherwise
you need to report this as a bug.

.TP
.B "Too many files to delete!"
.B apt\-move
will report this error if the number of files to be deleted exceeds the
.I MAXDELETE
setting in
.BR apt\-move.conf .
You need to study the output to determine if this is normal (in which case
you can override this using the
.I force
parameter), or if its due to some drastic change on the mirror site (like
a new release) or possibly due to a partial download of the master
Packages.gz or Sources.gz file.

.TP
.B "Your current mirror directory is incompatible..."
You have just upgraded from an old version of apt-move.  Update your
configuration, then run
.I apt-move fsck
and finally remove
.BR .apt-move/ancient .

.TP
.B "Could not read Release files."
.B apt\-move
could not read the release files needed to build the master files.  Make sure
you have run
.I apt-get update
and try again.

.TP
.B "Failed to remove original files."
.B apt\-move
could not remove the original copies of files that have just entered the
.B apt\-move
archive.  Make sure that you have permission to delete those files.

.TP
.B "Please remove $LOCALDIR/backup."
You must remove
.B LOCALDIR/backup
before running the
.B fsck
command.

.TP
.B "Unknown DIST setting."
The value of
.I DIST
must match the
.B Archive
field in the
.B Release
file of the distribution that you are trying to mirror.

.SH BUGS

The exclusion system was designed prior to the introduction to the package
pools.  Hence its content still relates to the old structure of the Debian
archive.  This is confusing and it should be replaced with a new exclusion
system.

.SH AUTHOR

Michael Merten <mikemerten@yahoo.com>

Herbert Xu <herbert@debian.org>
1	.\" Copyright (c) 1999 Michael Merten <mikemerten@yahoo.com>
2	.\" Copyright (c) 2000-2002 Herbert Xu <herbert@debian.org>
3	.\" May be distributed under the terms of version 2 of the
4	.\" GNU GPL. See the LICENSE file included with this package.
5	.\" $Id: apt-move.8,v 1.20 2002/10/23 22:16:34 herbert Exp $
6	.TH APT\-MOVE 8 "2002 Oct 7th" "APT-MOVE"
7
8	.SH NAME
9	apt\-move \- move cache of Debian packages into a mirror hierarchy.
10
11	.SH SYNOPSIS
12
13	.B apt\-move
14	.RB [ \-c
15	.IR conffile ]
16	.RB [ \-d
17	.IR dist ]
18	.RB [ \-fqt ]
19	.I command
20
21
22	.SH DESCRIPTION
23
24	The
25	.B apt\-move
26	script is used to move a collection of Debian package files into a proper
27	archive hierarchy of the form
28	.B $LOCALDIR/pool/...
29	where
30	.B LOCALDIR
31	is specified in the configuration file.
32	It is intended as a tool to help manage the
33	.BR apt\-get (8)
34	file cache, but could be configured to work with any collection
35	of Debian packages.
36
37	.PP
38	Additionally, using the
39	.I sync
40	and
41	.I mirror
42	commands, you can build your own local mirror of portions of a selected
43	binary and/or source distribution.
44
45	.PP
46	Running
47	.B apt\-move
48	periodically will assist in managing the resulting partial mirror
49	by (optionally) removing obsolete packages and creating valid local
50	Packages.gz and Sources.gz.
51
52	.SS "Commands"
53	The following commands are accepted by
54	.BR apt\-move :
55
56	.TP
57	.B get \fR[ \fIdir \fR]
58	This generates the master files using Packages and Sources files from the
59	.BR apt (8)
60	cache. The master files are used to keep track of what packages are
61	available, and where packages should be installed. If
62	.I dir
63	is specified, it will be used in lieu of the
64	.B LISTSTATE
65	variable.
66
67	.TP
68	.B getlocal \fR[ \fIdir \fR]
69	This is an alias of get. It may be removed in future releases.
70
71	.TP
72	.B move
73	Moves a collection of packages into the local mirror tree. Uses existing
74	master files (see
75	.IR get )
76	to repair any mangling done to the package names. Any packages that aren't
77	listed in the master files will be left in the file cache directory.
78
79	.TP
80	.B delete
81	Delete obsolete package files. Configurable through the
82	.I DELETE
83	and
84	.I MAXDELETE
85	settings in the
86	.B /etc/apt\-move.conf
87	file (see the
88	.I CONFIGURATION
89	section below).
90
91	.TP
92	.B packages
93	Builds new local versions of Packages.gz and Sources.gz files.
94
95	.TP
96	.B fsck
97	Rebuilds all index files used to make Packages and Sources files and reprocess
98	all packages in the archive by calling
99	.B movefile
100	on them. Use this if you are upgrading from an old version (<< 4.2) of
101	.BR apt-move .
102
103	.TP
104	.B update
105	This is an alias, equivalent to
106	.RI ' get
107	.I move
108	.I delete
109	.IR packages '.
110	This is the preferred method for moving package files from your
111	cache into a local mirror.
112
113	.TP
114	.B local
115	This is an alias, equivalent to
116	.RI ' move
117	.I delete
118	.IR packages '.
119
120	.TP
121	.B localupdate
122	This is an alias for update. It may be removed in future releases.
123
124	.TP
125	.B mirror
126	This command automatically runs
127	.IR get ,
128	then uses
129	.B /usr/lib/apt-move/fetch
130	and
131	.BR apt-get (8)
132	to download any packages missing from your mirror. The downloaded files will
133	be installed into the repository using
134	.IR move .
135	Finally, it runs
136	.I packages
137	and exits.
138	See the
139	.I DIST
140	and
141	.I PKGTYPE
142	settings in
143	.BR /etc/apt\-move.conf .
144	Before using this command, you need to set up a
145	.B $LOCALDIR/.exclude
146	file containing patterns to exclude
147	unwanted files from your mirror. See the
148	.B SAMPLE.exclude
149	file for an example. See also the
150	.I "Exclude file"
151	section of
152	.I NOTES
153	below. Note that this command will only mirror packages for the architecture
154	that you are running on. It will, however, mirror all source packages.
155
156	.TP
157	.B sync
158	Similar to the
159	.I mirror
160	function, but only gets the packages that are currently installed on
161	your system. It uses
162	.BR dpkg (8)
163	.I \-\-get\-selections
164	to find out what files to download. It will skip any files that
165	match one of the patterns in the
166	.B $LOCALDIR/.exclude
167	file (if it exists).
168	.B sync
169	will get the latest versions of the packages, regardless of the
170	version currently installed on your system (think about it).
171
172	.TP
173	.B exclude
174	This command is used to test your
175	.B $LOCALDIR/.exclude
176	pattern file. It will
177	go through the master lists and print any file that matches one
178	of the patters in
179	.BR $LOCALDIR/.exclude .
180	This will show you exactly what
181	files you have EXCLUDED from your mirror. The
182	.B \-t
183	(test) flag has no affect on this command. This
184	uses your existing master files, and does not require an internet
185	connection.
186
187	.TP
188	.BI movefile \ files...
189	This command is similar to move. Instead of moving files from
190	.IR FILECACHE ,
191	it will move the files specified on the command line.
192
193	.TP
194	\fBlistbin \fR[ \fBmirror \fR\| \fBsync \fR\| \fBrepo \fR]
195	This command prints a list of packages which may serve as the input to
196	mirrorbin or mirrorsrc. If the argument is
197	.B mirror
198	or
199	.BR sync ,
200	it will produce the same lists that the
201	.B mirror
202	and
203	.B sync
204	commands use. If the argument is
205	.BR repo ,
206	the list produced will contain the packages that are currently in the
207	apt-move repository.
208
209	.TP
210	.B mirrorbin
211	This command will fetch the list of packages specified on the standard input,
212	and place them into the archive in the same way as
213	.B mirror
214	does.
215
216	.TP
217	.B mirrorsrc
218	This commands acts like
219	.BR mirrorbin ,
220	except that it fetches source packages instead of binary ones.
221
222	.SS Options
223	The following options are available from the command line:
224
225	.TP
226	\fB\-c \fIconffile
227	Use
228	.I conffile
229	as the configuration file instead of
230	.BR /etc/apt\-move.conf .
231
232	.TP
233	\fB\-d \fIdist
234	Use
235	.I dist
236	as the default suite instead of the value of
237	.I DIST
238	from the configuration file.
239
240	.TP
241	.B \-f
242	Forces deletion of files even when the percentage of files to
243	delete exceeds the
244	.I MAXDELETE
245	setting. This is useful if
246	.B apt\-move
247	aborts with an error saying that too many files would be deleted, and you
248	want to delete the files anyway. (Use with caution.) If you get this error,
249	using
250	.B \-ft
251	will show you the complete list of files, so you can verify them before
252	you use
253	.BR \-f.
254
255	.TP
256	.B \-q
257	Suppresses normal output. This option is useful when
258	.B apt\-move
259	is used in a non-interactive script.
260
261	.TP
262	.B \-t
263	Makes a 'test run' and reports what WOULD be done for
264	.B option
265	but does not modify any of the cache or mirror files.
266
267	.SH CONFIGURATION
268
269	Before using
270	.BR apt\-move ,
271	edit the
272	.B /etc/apt\-move.conf
273	file to match your local setup. Always remember to use the
274	.I test
275	parameter after any change in your configuration to make sure it will
276	work like you want it to. You may also want to set the
277	.I DELETE
278	option to
279	.I no
280	to turn off file deletes until everything else is working successfully.
281
282	.PP
283	The following settings are recognized by
284	.B apt-move
285	(shown here with their defaults):
286
287	.TP
288	.BR APTSITES= """debian.midco.net non-us.debian.org"""
289	Set this to the names of sites in your
290	.B /etc/apt/sources.list
291	that you wish to mirror.
292
293	.TP
294	.BR ARCHS= """alpha arm hurd-i386 i386 m68k powerpc sparc"""
295	This is a list of the architectures that you mirror.
296	As of potato, set to only one of:
297	.IR alpha ,
298	.IR arm ,
299	.IR hurd\-i386 ,
300	.IR i386 ,
301	.IR m68k ,
302	.I powerpc
303	or
304	.IR sparc .
305	Determines the creation of links to binary-all packages, as well as Packages
306	and Sources files.
307
308	.TP
309	.BR LOCALDIR= /mirrors/debian
310	This is the full (absolute) path to your debian directory (the top of your
311	local mirror).
312
313	.TP
314	.BR DIST= stable
315	This is the suite that will be mirrored by
316	.BR apt-move .
317	It must match the
318	.B Archive
319	field in the corresponding
320	.I Release
321	files. It is also used as the default suite to hold packages when the
322	.I Release
323	files are missing.
324
325	.TP
326	.BR PKGTYPE= binary
327	Set this to your choice of:
328	.IR binary ,
329	.I source
330	or
331	.I both
332	to tell the
333	.IR mirror ,
334	.I sync
335	and
336	.I movefile
337	which type(s) of files to get.
338
339	.TP
340	.BR FILECACHE= /var/cache/apt/archives
341	The directory where your local cache of packages are. The default will work
342	for the
343	.BR apt-get (8)
344	packages, unless you've changed the configuration in
345	.BR /etc/apt/apt.conf .
346
347	.TP
348	.BR LISTSTATE= /var/lib/apt/lists
349	The directory to your local cache of Packages files. The default will work
350	for the
351	.BR apt-get (8)
352	packages, unless you've changed the configuration in
353	.BR /etc/apt/apt.conf .
354
355	.TP
356	.BR DELETE= no
357	Determines whether obsolete packages (packages not listed in the master file,
358	or packages that have been superceded in the repository) are to be removed.
359
360	.TP
361	.BR MAXDELETE= 20
362	Maximum percentage of files
363	.B apt\-move
364	is allowed to delete during a normal run. Anything exceeding this will
365	produce an error and abort the script. I added this as a precaution
366	so that you won't lose your entire mirror when a new distribution is
367	released. You can override this (with caution) using the
368	.I \-f
369	parameter with
370	.BR apt\-move .
371
372	.TP
373	.BR COPYONLY= no
374	If this is set to yes, then
375	.B move
376	and
377	.B movefile
378	will copy instead of move. That is, the originals will be left alone.
379
380	.TP
381	.BR PKGCOMP= gzip
382	This should be set to a list of compression formats that apt-move should
383	provide when generating Packages and Sources files. The possible values
384	are
385	.BR none ,
386	.B gzip
387	and
388	.BR bzip2 .
389
390	.PP
391	For the
392	.I sync
393	and
394	.I mirror
395	commands to function correctly, you need to list your
396	.B apt\-move
397	repository at the top of
398	.BR /etc/apt/sources.list
399	as a
400	.BR file\ URI .
401
402	.SH FILES
403
404	.TP
405	.B /usr/bin/apt\-move
406	The script.
407
408	.TP
409	.B /etc/apt\-move.conf
410	Configuration file for the script.
411
412	.TP
413	.B /usr/share/man/man8/apt\-move.8.gz
414	The manpage.
415
416	.TP
417	.B /tmp/MOVE_*
418	The temporary files created at runtime.
419
420	.TP
421	.B /usr/lib/apt-move/fetch
422	Utility to fetch files just like
423	.IR "apt-get install -d" .
424	Except that no dependency analysis is done.
425
426	.TP
427	.B .apt-move/*.{binary, source}.local
428	Put entries of local packages here. The fields are
429	``package priority section source version task'' for the binary file, and
430	``package priority section version'' for the source file. The
431	.B version
432	field may be set to a single dash to refer to the latest version in the
433	archive. Blank lines and lines beginning with a hash are ignored.
434
435	.SH "SEE ALSO"
436
437	.BR dpkg (8),
438	.BR apt\-get (8)
439
440	.SH NOTES
441	.SS "Exclude file"
442	The
443	.I mirror
444	command uses a file in the
445	.B $LOCALDIR/
446	directory called '.exclude' which contains
447	exclude patterns that are applied against the files to be mirrored.
448	These patterns were created with the following limitation: they must work
449	the same with with
450	.BR grep (1),
451	after any '*' characters are removed. Unless you're careful setting this up,
452	you'll get unexpected results. Run
453	.RB "'" apt-move
454	.B \-t
455	.BR mirror "'"
456	first, to make sure you're getting the results you intended. Another way to
457	verify your exclude file is the use the
458	.I exclude
459	command for
460	.B apt\-move
461	to print a list of files your are excluding from your mirror. See the sample
462	.exclude file (SAMPLE.exclude) for an example of an .exclude file.
463
464	.SS Mirroring
465	The
466	.B apt\-move
467	.B mirror
468	and
469	.B sync
470	commands
471	do not test for available disk space. The current
472	potato (main binary) distribution is over 1Gb in size. Add the sources to
473	that and it can eat up the space on a partition really fast. I would advise you
474	to put your mirror somewhere other than the root partition. Set up your
475	exclude file and run
476	.B "apt\-move -t mirror"
477	and examine the result.
478
479	.SS "Code names"
480	Since
481	.B apt\-move
482	gets the suite names from
483	.I Release
484	files, which usually use the names
485	.IR stable ,
486	.I testing
487	and
488	.IR unstable ,
489	the suites in the repository are named accordingly. You can simulate the
490	code names by creating symbolic links in the
491	.I dists
492	directory. For example, in order to make
493	.I testing
494	equivalent to
495	.IR sarge ,
496	you could run
497	.BR "ln -s testing $LOCALDIR/sarge" .
498	Alternatively, you could delete the
499	.I testing
500	subdirectory and run
501	.BR "ln -s sarge $LOCALDIR/testing" .
502	This will cause future executions of the
503	.I get
504	operation to use
505	.I sarge
506	whenever it sees
507	.I testing
508	in the
509	.I Release
510	file.
511
512	.SH DIAGNOSTICS
513
514	.B apt\-move
515	may exit with one of the following error messages:
516
517	.TP
518	.B "Could not read configuration."
519	.B apt\-move
520	could not find the
521	.B /etc/apt-move.conf
522	file. Run the install script.
523
524	.TP
525	.B "Could not create directory."
526	For some reason, a necessary directory could not be created.
527
528	.TP
529	.B "You failed to select a distribution."
530	You did not configure a
531	.I DIST
532	setting in /etc/apt-move.conf.
533
534	.TP
535	.B "You specified an invalid pacakge type."
536	You can only use
537	.IR binary ,
538	.I source
539	or
540	.I both
541	for the PKGTYPE setting.
542
543	.TP
544	.B "No master files exist!"
545	You need to run
546	.B apt-\move
547	with the
548	.B get
549	command at least once in order to create the master files which determine
550	where packages are to be installed.
551
552	.TP
553	.B "bc calculation returned invalid result"
554	.B apt\-move
555	uses the
556	.BR bc (1)
557	program to determine when the number of files to delete will exceed the
558	.I MAXDELETE
559	setting in
560	.BR apt\-move.conf .
561	If you get this error, make sure that
562	.I MAXDELETE
563	is set to a number in the range of 1 to 100, without the % sign. Otherwise
564	you need to report this as a bug.
565
566	.TP
567	.B "Too many files to delete!"
568	.B apt\-move
569	will report this error if the number of files to be deleted exceeds the
570	.I MAXDELETE
571	setting in
572	.BR apt\-move.conf .
573	You need to study the output to determine if this is normal (in which case
574	you can override this using the
575	.I force
576	parameter), or if its due to some drastic change on the mirror site (like
577	a new release) or possibly due to a partial download of the master
578	Packages.gz or Sources.gz file.
579
580	.TP
581	.B "Your current mirror directory is incompatible..."
582	You have just upgraded from an old version of apt-move. Update your
583	configuration, then run
584	.I apt-move fsck
585	and finally remove
586	.BR .apt-move/ancient .
587
588	.TP
589	.B "Could not read Release files."
590	.B apt\-move
591	could not read the release files needed to build the master files. Make sure
592	you have run
593	.I apt-get update
594	and try again.
595
596	.TP
597	.B "Failed to remove original files."
598	.B apt\-move
599	could not remove the original copies of files that have just entered the
600	.B apt\-move
601	archive. Make sure that you have permission to delete those files.
602
603	.TP
604	.B "Please remove $LOCALDIR/backup."
605	You must remove
606	.B LOCALDIR/backup
607	before running the
608	.B fsck
609	command.
610
611	.TP
612	.B "Unknown DIST setting."
613	The value of
614	.I DIST
615	must match the
616	.B Archive
617	field in the
618	.B Release
619	file of the distribution that you are trying to mirror.
620
621	.SH BUGS
622
623	The exclusion system was designed prior to the introduction to the package
624	pools. Hence its content still relates to the old structure of the Debian
625	archive. This is confusing and it should be replaced with a new exclusion
626	system.
627
628	.SH AUTHOR
629
630	Michael Merten <mikemerten@yahoo.com>
631
632	Herbert Xu <herbert@debian.org>