1 <?xml version=
"1.0" encoding=
"utf-8" standalone=
"no"?>
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % aptent SYSTEM
"apt.ent"> %aptent;
5 <!ENTITY % aptverbatiment SYSTEM
"apt-verbatim.ent"> %aptverbatiment;
6 <!ENTITY % aptvendor SYSTEM
"apt-vendor.ent"> %aptvendor;
12 &apt-author.jgunthorpe;
16 <!-- The last update date -->
17 <date>2016-
07-
08T00:
00:
00Z
</date>
21 <refentrytitle>apt-ftparchive
</refentrytitle>
22 <manvolnum>1</manvolnum>
23 <refmiscinfo class=
"manual">APT
</refmiscinfo>
26 <!-- Man page title -->
28 <refname>apt-ftparchive
</refname>
29 <refpurpose>Utility to generate index files
</refpurpose>
32 &synopsis-command-apt-ftparchive;
34 <refsect1><title>Description
</title>
35 <para><command>apt-ftparchive
</command> is the command line tool that generates the index
36 files that APT uses to access a distribution source. The index files should
37 be generated on the origin site based on the content of that site.
</para>
39 <para><command>apt-ftparchive
</command> is a superset of the &dpkg-scanpackages; program,
40 incorporating its entire functionality via the
<literal>packages
</literal> command.
41 It also contains a contents file generator,
<literal>contents
</literal>, and an
42 elaborate means to 'script' the generation process for a complete
45 <para>Internally
<command>apt-ftparchive
</command> can make use of binary databases to
46 cache the contents of a .deb file and it does not rely on any external
47 programs aside from
&gzip;. When doing a full generate it automatically
48 performs file-change checks and builds the desired compressed output files.
</para>
50 <para>Unless the
<option>-h
</option>, or
<option>--help
</option> option is given,
51 one of the commands below must be present.
</para>
54 <varlistentry><term><option>packages
</option></term>
56 The packages command generates a package file from a directory tree. It
57 takes the given directory and recursively searches it for .deb files,
58 emitting a package record to stdout for each. This command is
59 approximately equivalent to &dpkg-scanpackages;.
</para>
61 <para>The option
<option>--db
</option> can be used to specify a binary caching DB.
</para></listitem>
64 <varlistentry><term><option>sources
</option></term>
66 The
<literal>sources
</literal> command generates a source index file from a directory tree.
67 It takes the given directory and recursively searches it for .dsc files,
68 emitting a source record to stdout for each. This command is approximately
69 equivalent to &dpkg-scansources;.
</para>
71 If an override file is specified then a source override file will be
72 looked for with an extension of .src. The --source-override option can be
73 used to change the source override file that will be used.
</para></listitem>
76 <varlistentry><term><option>contents
</option></term>
78 The
<literal>contents
</literal> command generates a contents file from a directory tree. It
79 takes the given directory and recursively searches it for .deb files,
80 and reads the file list from each file. It then sorts and writes to stdout
81 the list of files matched to packages. Directories are not written to
82 the output. If multiple packages own the same file then each package is
83 separated by a comma in the output.
</para>
85 The option
<option>--db
</option> can be used to specify a binary caching DB.
</para></listitem>
88 <varlistentry><term><option>release
</option></term>
90 The
<literal>release
</literal> command generates a Release file from a
91 directory tree. It recursively searches the given directory for
92 uncompressed and compressed
<filename>Packages
</filename>,
93 <filename>Sources
</filename>,
<filename>Contents
</filename>,
94 <filename>Components
</filename> and
<filename>icons
</filename> files as
95 well as
<filename>Release
</filename>,
<filename>Index
</filename> and
96 <filename>md5sum.txt
</filename> files by default
97 (
<literal>APT::FTPArchive::Release::Default-Patterns
</literal>).
98 Additional filename patterns can be added by listing them in
99 <literal>APT::FTPArchive::Release::Patterns
</literal>. It then writes to
100 stdout a
<filename>Release
</filename> file containing (by default) an MD5,
101 SHA1, SHA256 and SHA512 digest for each file.
</para>
103 Values for the additional metadata fields in the Release file are
104 taken from the corresponding variables under
105 <literal>APT::FTPArchive::Release
</literal>,
106 e.g.
<literal>APT::FTPArchive::Release::Origin
</literal>. The supported fields
107 are
<literal>Origin
</literal>,
<literal>Label
</literal>,
<literal>Suite
</literal>,
108 <literal>Version
</literal>,
<literal>Codename
</literal>,
<literal>Date
</literal>,
109 <literal>Valid-Until
</literal>,
<literal>Signed-By
</literal>,
<literal>Architectures
</literal>,
110 <literal>Components
</literal> and
<literal>Description
</literal>.
</para></listitem>
114 <varlistentry><term><option>generate
</option></term>
116 The
<literal>generate
</literal> command is designed to be runnable from a cron script and
117 builds indexes according to the given config file. The config language
118 provides a flexible means of specifying which index files are built from
119 which directories, as well as providing a simple means of maintaining the
120 required settings.
</para></listitem>
123 <varlistentry><term><option>clean
</option></term>
125 The
<literal>clean
</literal> command tidies the databases used by the given
126 configuration file by removing any records that are no longer necessary.
</para></listitem>
131 <refsect1><title>The Generate Configuration
</title>
133 The
<literal>generate
</literal> command uses a configuration file to describe the
134 archives that are going to be generated. It follows the typical ISC
135 configuration format as seen in ISC tools like bind
8 and dhcpd.
136 &apt-conf; contains a description of the syntax. Note that the generate
137 configuration is parsed in sectional manner, but &apt-conf; is parsed in a
138 tree manner. This only effects how the scope tag is handled.
</para>
141 The generate configuration has four separate sections, each described below.
</para>
143 <refsect2><title><literal>Dir
</literal> Section
</title>
145 The
<literal>Dir
</literal> section defines the standard directories needed to
146 locate the files required during the generation process. These
147 directories are prepended certain relative paths defined in later
148 sections to produce a complete an absolute path.
</para>
150 <varlistentry><term><option>ArchiveDir
</option></term>
152 Specifies the root of the FTP archive, in a standard
153 Debian configuration this is the directory that contains the
154 <filename>ls-LR
</filename> and dist nodes.
</para></listitem>
157 <varlistentry><term><option>OverrideDir
</option></term>
159 Specifies the location of the override files.
</para></listitem>
162 <varlistentry><term><option>CacheDir
</option></term>
164 Specifies the location of the cache files.
</para></listitem>
167 <varlistentry><term><option>FileListDir
</option></term>
169 Specifies the location of the file list files,
170 if the
<literal>FileList
</literal> setting is used below.
</para></listitem>
175 <refsect2><title><literal>Default
</literal> Section
</title>
177 The
<literal>Default
</literal> section specifies default values, and settings
178 that control the operation of the generator. Other sections may override
179 these defaults with a per-section setting.
</para>
181 <varlistentry><term><option>Packages::Compress
</option></term>
183 Sets the default compression schemes to use
184 for the package index files. It is a string that contains a space
185 separated list of at least one of the compressors configured via the
186 <option>APT::Compressor
</option> configuration scope.
187 The default for all compression schemes is '. gzip'.
</para></listitem>
190 <varlistentry><term><option>Packages::Extensions
</option></term>
192 Sets the default list of file extensions that are package files.
193 This defaults to '.deb'.
</para></listitem>
196 <varlistentry><term><option>Sources::Compress
</option></term>
198 This is similar to
<literal>Packages::Compress
</literal>
199 except that it controls the compression for the Sources files.
</para></listitem>
202 <varlistentry><term><option>Sources::Extensions
</option></term>
204 Sets the default list of file extensions that are source files.
205 This defaults to '.dsc'.
</para></listitem>
208 <varlistentry><term><option>Contents::Compress
</option></term>
210 This is similar to
<literal>Packages::Compress
</literal>
211 except that it controls the compression for the Contents files.
</para></listitem>
214 <varlistentry><term><option>Translation::Compress
</option></term>
216 This is similar to
<literal>Packages::Compress
</literal>
217 except that it controls the compression for the Translation-en master file.
</para></listitem>
220 <varlistentry><term><option>DeLinkLimit
</option></term>
222 Specifies the number of kilobytes to delink (and
223 replace with hard links) per run. This is used in conjunction with the
224 per-section
<literal>External-Links
</literal> setting.
</para></listitem>
227 <varlistentry><term><option>FileMode
</option></term>
229 Specifies the mode of all created index files. It
230 defaults to
0644. All index files are set to this mode with no regard
231 to the umask.
</para></listitem>
234 <varlistentry><term><option>LongDescription
</option></term>
236 Specifies whether long descriptions should be included in the
<filename>Packages
</filename> file or split
237 out into a master
<filename>Translation-en
</filename> file.
</para></listitem>
242 <refsect2><title><literal>TreeDefault
</literal> Section
</title>
244 Sets defaults specific to
<literal>Tree
</literal> sections. All of these
245 variables are substitution variables and have the strings $(DIST),
246 $(SECTION) and $(ARCH) replaced with their respective values.
</para>
249 <varlistentry><term><option>MaxContentsChange
</option></term>
251 Sets the number of kilobytes of contents
252 files that are generated each day. The contents files are round-robined
253 so that over several days they will all be rebuilt.
</para></listitem>
256 <varlistentry><term><option>ContentsAge
</option></term>
258 Controls the number of days a contents file is allowed
259 to be checked without changing. If this limit is passed the mtime of the
260 contents file is updated. This case can occur if the package file is
261 changed in such a way that does not result in a new contents file
262 [override edit for instance]. A hold off is allowed in hopes that new
263 .debs will be installed, requiring a new file anyhow. The default is
10,
264 the units are in days.
</para></listitem>
267 <varlistentry><term><option>Directory
</option></term>
269 Sets the top of the .deb directory tree. Defaults to
270 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/
</filename></para></listitem>
273 <varlistentry><term><option>SrcDirectory
</option></term>
275 Sets the top of the source package directory tree. Defaults to
276 <filename>$(DIST)/$(SECTION)/source/
</filename></para></listitem>
279 <varlistentry><term><option>Packages
</option></term>
281 Sets the output Packages file. Defaults to
282 <filename>$(DIST)/$(SECTION)/binary-$(ARCH)/Packages
</filename></para></listitem>
285 <varlistentry><term><option>Sources
</option></term>
287 Sets the output Sources file. Defaults to
288 <filename>$(DIST)/$(SECTION)/source/Sources
</filename></para></listitem>
291 <varlistentry><term><option>Translation
</option></term>
293 Sets the output Translation-en master file with the long descriptions if they
294 should be not included in the Packages file. Defaults to
295 <filename>$(DIST)/$(SECTION)/i18n/Translation-en
</filename></para></listitem>
298 <varlistentry><term><option>InternalPrefix
</option></term>
300 Sets the path prefix that causes a symlink to be
301 considered an internal link instead of an external link. Defaults to
302 <filename>$(DIST)/$(SECTION)/
</filename></para></listitem>
305 <varlistentry><term><option>Contents
</option></term>
307 Sets the output Contents file. Defaults to
308 <filename>$(DIST)/$(SECTION)/Contents-$(ARCH)
</filename>. If this setting causes multiple
309 Packages files to map onto a single Contents file (as is the default)
310 then
<command>apt-ftparchive
</command> will integrate those package files
311 together automatically.
</para></listitem>
314 <varlistentry><term><option>Contents::Header
</option></term>
316 Sets header file to prepend to the contents output.
</para></listitem>
319 <varlistentry><term><option>BinCacheDB
</option></term>
321 Sets the binary cache database to use for this
322 section. Multiple sections can share the same database.
</para></listitem>
325 <varlistentry><term><option>FileList
</option></term>
327 Specifies that instead of walking the directory tree,
328 <command>apt-ftparchive
</command> should read the list of files from the given
329 file. Relative files names are prefixed with the archive directory.
</para></listitem>
332 <varlistentry><term><option>SourceFileList
</option></term>
334 Specifies that instead of walking the directory tree,
335 <command>apt-ftparchive
</command> should read the list of files from the given
336 file. Relative files names are prefixed with the archive directory.
337 This is used when processing source indexes.
</para></listitem>
342 <refsect2><title><literal>Tree
</literal> Section
</title>
344 The
<literal>Tree
</literal> section defines a standard Debian file tree which
345 consists of a base directory, then multiple sections in that base
346 directory and finally multiple Architectures in each section. The exact
347 pathing used is defined by the
<literal>Directory
</literal> substitution variable.
</para>
349 The
<literal>Tree
</literal> section takes a scope tag which sets the
350 <literal>$(DIST)
</literal> variable and defines the root of the tree
351 (the path is prefixed by
<literal>ArchiveDir
</literal>).
352 Typically this is a setting such as
<filename>dists/&debian-stable-codename;
</filename>.
</para>
354 All of the settings defined in the
<literal>TreeDefault
</literal> section can be
355 used in a
<literal>Tree
</literal> section as well as three new variables.
</para>
357 When processing a
<literal>Tree
</literal> section
<command>apt-ftparchive
</command>
358 performs an operation similar to:
361 for j in Architectures do
362 Generate for DIST=scope SECTION=i ARCH=j
363 </programlisting></para>
366 <varlistentry><term><option>Sections
</option></term>
368 This is a space separated list of sections which appear
369 under the distribution; typically this is something like
370 <literal>main contrib non-free
</literal></para></listitem>
373 <varlistentry><term><option>Architectures
</option></term>
375 This is a space separated list of all the architectures that appear under
376 search section. The special architecture 'source' is used to indicate
377 that this tree has a source archive. The architecture 'all' signals that
378 architecture specific files like
<filename>Packages
</filename> should not
379 include information about architecture
<literal>all
</literal> packages in
380 all files as they will be available in a dedicated file.
384 <varlistentry><term><option>LongDescription
</option></term>
386 Specifies whether long descriptions should be included in the
<filename>Packages
</filename> file or split
387 out into a master
<filename>Translation-en
</filename> file.
</para></listitem>
390 <varlistentry><term><option>BinOverride
</option></term>
392 Sets the binary override file. The override file
393 contains section, priority and maintainer address information.
</para></listitem>
396 <varlistentry><term><option>SrcOverride
</option></term>
398 Sets the source override file. The override file
399 contains section information.
</para></listitem>
402 <varlistentry><term><option>ExtraOverride
</option></term>
404 Sets the binary extra override file.
</para></listitem>
407 <varlistentry><term><option>SrcExtraOverride
</option></term>
409 Sets the source extra override file.
</para></listitem>
414 <refsect2><title><literal>BinDirectory
</literal> Section
</title>
416 The
<literal>bindirectory
</literal> section defines a binary directory tree
417 with no special structure. The scope tag specifies the location of
418 the binary directory and the settings are similar to the
<literal>Tree
</literal>
419 section with no substitution variables or
420 <literal>Section
</literal><literal>Architecture
</literal> settings.
</para>
422 <varlistentry><term><option>Packages
</option></term>
424 Sets the Packages file output.
</para></listitem>
427 <varlistentry><term><option>Sources
</option></term>
429 Sets the Sources file output. At least one of
430 <literal>Packages
</literal> or
<literal>Sources
</literal> is required.
</para></listitem>
433 <varlistentry><term><option>Contents
</option></term>
435 Sets the Contents file output (optional).
</para></listitem>
438 <varlistentry><term><option>BinOverride
</option></term>
440 Sets the binary override file.
</para></listitem>
443 <varlistentry><term><option>SrcOverride
</option></term>
445 Sets the source override file.
</para></listitem>
448 <varlistentry><term><option>ExtraOverride
</option></term>
450 Sets the binary extra override file.
</para></listitem>
453 <varlistentry><term><option>SrcExtraOverride
</option></term>
455 Sets the source extra override file.
</para></listitem>
458 <varlistentry><term><option>BinCacheDB
</option></term>
460 Sets the cache DB.
</para></listitem>
463 <varlistentry><term><option>PathPrefix
</option></term>
465 Appends a path to all the output paths.
</para></listitem>
468 <varlistentry><term><option>FileList
</option></term><term><option>SourceFileList
</option></term>
470 Specifies the file list file.
</para></listitem>
477 <refsect1><title>The Binary Override File
</title>
478 <para>The binary override file is fully compatible with &dpkg-scanpackages;. It
479 contains four fields separated by spaces. The first field is the package name,
480 the second is the priority to force that package to, the third is
481 the section to force that package to and the final field is the maintainer
482 permutation field.
</para>
483 <para>The general form of the maintainer field is:
484 <literallayout>old [// oldn]* =
> new
</literallayout>
486 <literallayout>new
</literallayout>
487 The first form allows a double-slash separated list of old email addresses
488 to be specified. If any of those are found then new is substituted for the
489 maintainer field. The second form unconditionally substitutes the
490 maintainer field.
</para>
494 <refsect1><title>The Source Override File
</title>
496 The source override file is fully compatible with &dpkg-scansources;. It
497 contains two fields separated by spaces. The first field is the source
498 package name, the second is the section to assign it.
</para>
501 <refsect1><title>The Extra Override File
</title>
503 The extra override file allows any arbitrary tag to be added or replaced
504 in the output. It has three columns, the first is the package, the second is
505 the tag and the remainder of the line is the new value.
</para>
508 <refsect1><title>options
</title>
513 <term><option>--md5
</option></term>
514 <term><option>--sha1
</option></term>
515 <term><option>--sha256
</option></term>
516 <term><option>--sha512
</option></term>
518 Generate the given checksum. These options default to on, when turned off the generated
519 index files will not have the checksum fields where possible.
520 Configuration Items:
<literal>APT::FTPArchive::
<replaceable>Checksum
</replaceable></literal> and
521 <literal>APT::FTPArchive::
<replaceable>Index
</replaceable>::
<replaceable>Checksum
</replaceable></literal> where
522 <literal><replaceable>Index
</replaceable></literal> can be
<literal>Packages
</literal>,
<literal>Sources
</literal> or
523 <literal>Release
</literal> and
<literal><replaceable>Checksum
</replaceable></literal> can be
<literal>MD5
</literal>,
524 <literal>SHA1
</literal>,
<literal>SHA256
</literal> or
<literal>SHA512
</literal>.
</para></listitem>
527 <varlistentry><term><option>-d
</option></term><term><option>--db
</option></term>
529 Use a binary caching DB. This has no effect on the generate command.
530 Configuration Item:
<literal>APT::FTPArchive::DB
</literal>.
</para></listitem>
533 <varlistentry><term><option>-q
</option></term><term><option>--quiet
</option></term>
535 Quiet; produces output suitable for logging, omitting progress indicators.
536 More q's will produce more quiet up to a maximum of
2. You can also use
537 <option>-q=#
</option> to set the quiet level, overriding the configuration file.
538 Configuration Item:
<literal>quiet
</literal>.
</para></listitem>
541 <varlistentry><term><option>--delink
</option></term>
543 Perform Delinking. If the
<literal>External-Links
</literal> setting is used then
544 this option actually enables delinking of the files. It defaults to on and
545 can be turned off with
<option>--no-delink
</option>.
546 Configuration Item:
<literal>APT::FTPArchive::DeLinkAct
</literal>.
</para></listitem>
549 <varlistentry><term><option>--contents
</option></term>
551 Perform contents generation. When this option is set and package indexes
552 are being generated with a cache DB then the file listing will also be
553 extracted and stored in the DB for later use. When using the generate
554 command this option also allows the creation of any Contents files. The
556 Configuration Item:
<literal>APT::FTPArchive::Contents
</literal>.
</para></listitem>
559 <varlistentry><term><option>-s
</option></term><term><option>--source-override
</option></term>
561 Select the source override file to use with the
<literal>sources
</literal> command.
562 Configuration Item:
<literal>APT::FTPArchive::SourceOverride
</literal>.
</para></listitem>
565 <varlistentry><term><option>--readonly
</option></term>
567 Make the caching databases read only.
568 Configuration Item:
<literal>APT::FTPArchive::ReadOnlyDB
</literal>.
</para></listitem>
571 <varlistentry><term><option>-a
</option></term><term><option>--arch
</option></term>
572 <listitem><para>Accept in the
<literal>packages
</literal> and
<literal>contents
</literal>
573 commands only package files matching
<literal>*_arch.deb
</literal> or
574 <literal>*_all.deb
</literal> instead of all package files in the given path.
575 Configuration Item:
<literal>APT::FTPArchive::Architecture
</literal>.
</para></listitem>
578 <varlistentry><term><option>APT::FTPArchive::AlwaysStat
</option></term>
580 &apt-ftparchive; caches as much as possible of metadata in a cachedb. If packages
581 are recompiled and/or republished with the same version again, this will lead to problems
582 as the now outdated cached metadata like size and checksums will be used. With this option
583 enabled this will no longer happen as it will be checked if the file was changed.
584 Note that this option is set to "
<literal>false
</literal>" by default as it is not recommend
585 to upload multiply versions/builds of a package with the same versionnumber, so in theory
586 nobody will have these problems and therefore all these extra checks are useless.
590 <varlistentry><term><option>APT::FTPArchive::LongDescription</option></term>
592 This configuration option defaults to "<literal>true
</literal>" and should only be set to
593 <literal>"false
"</literal> if the Archive generated with &apt-ftparchive; also provides
594 <filename>Translation</filename> files. Note that the <filename>Translation-en</filename>
595 master file can only be created in the generate command.
604 <refsect1><title>Examples</title>
606 <para>To create a compressed Packages file for a directory containing
607 binary packages (.deb):
610 <command>apt-ftparchive</command> packages <replaceable>directory</replaceable> | <command>gzip</command> > <filename>Packages.gz</filename>
611 </programlisting></para>
615 <refsect1><title>See Also</title>
616 <para>&apt-conf;</para>
619 <refsect1><title>Diagnostics</title>
620 <para><command>apt-ftparchive</command> returns zero on normal operation, decimal 100 on error.</para>