1APT-FTPARCHIVE(1)                     APT                    APT-FTPARCHIVE(1)
2
3
4

NAME

6       apt-ftparchive - Utility to generate index files
7

SYNOPSIS

9       apt-ftparchive [-dsq] [--md5] [--delink] [--readonly] [--contents]
10                      [--arch architecture] [-o=config_string]
11                      [-c=config_file]
12                      {packages path [override-file [pathprefix]]  |
13                      sources path [override-file [pathprefix]]  |
14                      contents path  | release path  |
15                      generate config_file section...  | clean config_file  |
16                      {-v | --version} | {-h | --help}}
17

DESCRIPTION

19       apt-ftparchive is the command line tool that generates the index files
20       that APT uses to access a distribution source. The index files should
21       be generated on the origin site based on the content of that site.
22
23       apt-ftparchive is a superset of the dpkg-scanpackages(1) program,
24       incorporating its entire functionality via the packages command. It
25       also contains a contents file generator, contents, and an elaborate
26       means to 'script' the generation process for a complete archive.
27
28       Internally apt-ftparchive can make use of binary databases to cache the
29       contents of a .deb file and it does not rely on any external programs
30       aside from gzip(1). When doing a full generate it automatically
31       performs file-change checks and builds the desired compressed output
32       files.
33
34       Unless the -h, or --help option is given, one of the commands below
35       must be present.
36
37       packages
38           The packages command generates a package file from a directory
39           tree. It takes the given directory and recursively searches it for
40           .deb files, emitting a package record to stdout for each. This
41           command is approximately equivalent to dpkg-scanpackages(1).
42
43           The option --db can be used to specify a binary caching DB.
44
45       sources
46           The sources command generates a source index file from a directory
47           tree. It takes the given directory and recursively searches it for
48           .dsc files, emitting a source record to stdout for each. This
49           command is approximately equivalent to dpkg-scansources(1).
50
51           If an override file is specified then a source override file will
52           be looked for with an extension of .src. The --source-override
53           option can be used to change the source override file that will be
54           used.
55
56       contents
57           The contents command generates a contents file from a directory
58           tree. It takes the given directory and recursively searches it for
59           .deb files, and reads the file list from each file. It then sorts
60           and writes to stdout the list of files matched to packages.
61           Directories are not written to the output. If multiple packages own
62           the same file then each package is separated by a comma in the
63           output.
64
65           The option --db can be used to specify a binary caching DB.
66
67       release
68           The release command generates a Release file from a directory tree.
69           It recursively searches the given directory for uncompressed and
70           compressed Packages, Sources, Contents, Components and icons files
71           as well as Release, Index and md5sum.txt files by default
72           (APT::FTPArchive::Release::Default-Patterns). Additional filename
73           patterns can be added by listing them in
74           APT::FTPArchive::Release::Patterns. It then writes to stdout a
75           Release file containing (by default) an MD5, SHA1, SHA256 and
76           SHA512 digest for each file.
77
78           Values for the additional metadata fields in the Release file are
79           taken from the corresponding variables under
80           APT::FTPArchive::Release, e.g.  APT::FTPArchive::Release::Origin.
81           The supported fields are Origin, Label, Suite, Version, Codename,
82           Date, NotAutomatic, ButAutomaticUpgrades, Acquire-By-Hash,
83           Valid-Until, Signed-By, Architectures, Components and Description.
84
85       generate
86           The generate command is designed to be runnable from a cron script
87           and builds indexes according to the given config file. The config
88           language provides a flexible means of specifying which index files
89           are built from which directories, as well as providing a simple
90           means of maintaining the required settings.
91
92       clean
93           The clean command tidies the databases used by the given
94           configuration file by removing any records that are no longer
95           necessary.
96

THE GENERATE CONFIGURATION

98       The generate command uses a configuration file to describe the archives
99       that are going to be generated. It follows the typical ISC
100       configuration format as seen in ISC tools like bind 8 and dhcpd.
101       apt.conf(5) contains a description of the syntax. Note that the
102       generate configuration is parsed in sectional manner, but apt.conf(5)
103       is parsed in a tree manner. This only effects how the scope tag is
104       handled.
105
106       The generate configuration has four separate sections, each described
107       below.
108
109   Dir Section
110       The Dir section defines the standard directories needed to locate the
111       files required during the generation process. These directories are
112       prepended certain relative paths defined in later sections to produce a
113       complete an absolute path.
114
115       ArchiveDir
116           Specifies the root of the FTP archive, in a standard Debian
117           configuration this is the directory that contains the ls-LR and
118           dist nodes.
119
120       OverrideDir
121           Specifies the location of the override files.
122
123       CacheDir
124           Specifies the location of the cache files.
125
126       FileListDir
127           Specifies the location of the file list files, if the FileList
128           setting is used below.
129
130   Default Section
131       The Default section specifies default values, and settings that control
132       the operation of the generator. Other sections may override these
133       defaults with a per-section setting.
134
135       Packages::Compress
136           Sets the default compression schemes to use for the package index
137           files. It is a string that contains a space separated list of at
138           least one of the compressors configured via the APT::Compressor
139           configuration scope. The default for all compression schemes is '.
140           gzip'.
141
142       Packages::Extensions
143           Sets the default list of file extensions that are package files.
144           This defaults to '.deb'.
145
146       Sources::Compress
147           This is similar to Packages::Compress except that it controls the
148           compression for the Sources files.
149
150       Sources::Extensions
151           Sets the default list of file extensions that are source files.
152           This defaults to '.dsc'.
153
154       Contents::Compress
155           This is similar to Packages::Compress except that it controls the
156           compression for the Contents files.
157
158       Translation::Compress
159           This is similar to Packages::Compress except that it controls the
160           compression for the Translation-en master file.
161
162       DeLinkLimit
163           Specifies the number of kilobytes to delink (and replace with hard
164           links) per run. This is used in conjunction with the per-section
165           External-Links setting.
166
167       FileMode
168           Specifies the mode of all created index files. It defaults to 0644.
169           All index files are set to this mode with no regard to the umask.
170
171       LongDescription
172           Specifies whether long descriptions should be included in the
173           Packages file or split out into a master Translation-en file.
174
175   TreeDefault Section
176       Sets defaults specific to Tree sections. All of these variables are
177       substitution variables and have the strings $(DIST), $(SECTION) and
178       $(ARCH) replaced with their respective values.
179
180       MaxContentsChange
181           Sets the number of kilobytes of contents files that are generated
182           each day. The contents files are round-robined so that over several
183           days they will all be rebuilt.
184
185       ContentsAge
186           Controls the number of days a contents file is allowed to be
187           checked without changing. If this limit is passed the mtime of the
188           contents file is updated. This case can occur if the package file
189           is changed in such a way that does not result in a new contents
190           file [override edit for instance]. A hold off is allowed in hopes
191           that new .debs will be installed, requiring a new file anyhow. The
192           default is 10, the units are in days.
193
194       Directory
195           Sets the top of the .deb directory tree. Defaults to
196           $(DIST)/$(SECTION)/binary-$(ARCH)/
197
198       SrcDirectory
199           Sets the top of the source package directory tree. Defaults to
200           $(DIST)/$(SECTION)/source/
201
202       Packages
203           Sets the output Packages file. Defaults to
204           $(DIST)/$(SECTION)/binary-$(ARCH)/Packages
205
206       Sources
207           Sets the output Sources file. Defaults to
208           $(DIST)/$(SECTION)/source/Sources
209
210       Translation
211           Sets the output Translation-en master file with the long
212           descriptions if they should be not included in the Packages file.
213           Defaults to $(DIST)/$(SECTION)/i18n/Translation-en
214
215       InternalPrefix
216           Sets the path prefix that causes a symlink to be considered an
217           internal link instead of an external link. Defaults to
218           $(DIST)/$(SECTION)/
219
220       Contents
221           Sets the output Contents file. Defaults to
222           $(DIST)/$(SECTION)/Contents-$(ARCH). If this setting causes
223           multiple Packages files to map onto a single Contents file (as is
224           the default) then apt-ftparchive will integrate those package files
225           together automatically.
226
227       Contents::Header
228           Sets header file to prepend to the contents output.
229
230       BinCacheDB
231           Sets the binary cache database to use for this section. Multiple
232           sections can share the same database.
233
234       FileList
235           Specifies that instead of walking the directory tree,
236           apt-ftparchive should read the list of files from the given file.
237           Relative files names are prefixed with the archive directory.
238
239       SourceFileList
240           Specifies that instead of walking the directory tree,
241           apt-ftparchive should read the list of files from the given file.
242           Relative files names are prefixed with the archive directory. This
243           is used when processing source indexes.
244
245   Tree Section
246       The Tree section defines a standard Debian file tree which consists of
247       a base directory, then multiple sections in that base directory and
248       finally multiple Architectures in each section. The exact pathing used
249       is defined by the Directory substitution variable.
250
251       The Tree section takes a scope tag which sets the $(DIST) variable and
252       defines the root of the tree (the path is prefixed by ArchiveDir).
253       Typically this is a setting such as dists/bookworm.
254
255       All of the settings defined in the TreeDefault section can be used in a
256       Tree section as well as three new variables.
257
258       When processing a Tree section apt-ftparchive performs an operation
259       similar to:
260
261           for i in Sections do
262              for j in Architectures do
263                 Generate for DIST=scope SECTION=i ARCH=j
264
265
266
267       Sections
268           This is a space separated list of sections which appear under the
269           distribution; typically this is something like main contrib
270           non-free non-free-firmware
271
272       Architectures
273           This is a space separated list of all the architectures that appear
274           under search section. The special architecture 'source' is used to
275           indicate that this tree has a source archive. The architecture
276           'all' signals that architecture specific files like Packages should
277           not include information about architecture all packages in all
278           files as they will be available in a dedicated file.
279
280       LongDescription
281           Specifies whether long descriptions should be included in the
282           Packages file or split out into a master Translation-en file.
283
284       BinOverride
285           Sets the binary override file. The override file contains section,
286           priority and maintainer address information.
287
288       SrcOverride
289           Sets the source override file. The override file contains section
290           information.
291
292       ExtraOverride
293           Sets the binary extra override file.
294
295       SrcExtraOverride
296           Sets the source extra override file.
297
298   BinDirectory Section
299       The bindirectory section defines a binary directory tree with no
300       special structure. The scope tag specifies the location of the binary
301       directory and the settings are similar to the Tree section with no
302       substitution variables or SectionArchitecture settings.
303
304       Packages
305           Sets the Packages file output.
306
307       Sources
308           Sets the Sources file output. At least one of Packages or Sources
309           is required.
310
311       Contents
312           Sets the Contents file output (optional).
313
314       BinOverride
315           Sets the binary override file.
316
317       SrcOverride
318           Sets the source override file.
319
320       ExtraOverride
321           Sets the binary extra override file.
322
323       SrcExtraOverride
324           Sets the source extra override file.
325
326       BinCacheDB
327           Sets the cache DB.
328
329       PathPrefix
330           Appends a path to all the output paths.
331
332       FileList, SourceFileList
333           Specifies the file list file.
334

THE BINARY OVERRIDE FILE

336       The binary override file is fully compatible with dpkg-scanpackages(1).
337       It contains four fields separated by spaces. The first field is the
338       package name, the second is the priority to force that package to, the
339       third is the section to force that package to and the final field is
340       the maintainer permutation field.
341
342       The general form of the maintainer field is:
343
344           old [// oldn]* => new
345
346       or simply,
347
348           new
349
350       The first form allows a double-slash separated list of old email
351       addresses to be specified. If any of those are found then new is
352       substituted for the maintainer field. The second form unconditionally
353       substitutes the maintainer field.
354

THE SOURCE OVERRIDE FILE

356       The source override file is fully compatible with dpkg-scansources(1).
357       It contains two fields separated by spaces. The first field is the
358       source package name, the second is the section to assign it.
359

THE EXTRA OVERRIDE FILE

361       The extra override file allows any arbitrary tag to be added or
362       replaced in the output. It has three columns, the first is the package,
363       the second is the tag and the remainder of the line is the new value.
364

OPTIONS

366       All command line options may be set using the configuration file, the
367       descriptions indicate the configuration option to set. For boolean
368       options you can override the config file by using something like
369       -f-,--no-f, -f=no or several other variations.
370
371       --md5, --sha1, --sha256, --sha512
372           Generate the given checksum. These options default to on, when
373           turned off the generated index files will not have the checksum
374           fields where possible. Configuration Items:
375           APT::FTPArchive::Checksum and APT::FTPArchive::Index::Checksum
376           where Index can be Packages, Sources or Release and Checksum can be
377           MD5, SHA1, SHA256 or SHA512.
378
379       -d, --db
380           Use a binary caching DB. This has no effect on the generate
381           command. Configuration Item: APT::FTPArchive::DB.
382
383       -q, --quiet
384           Quiet; produces output suitable for logging, omitting progress
385           indicators. More q's will produce more quiet up to a maximum of 2.
386           You can also use -q=# to set the quiet level, overriding the
387           configuration file. Configuration Item: quiet.
388
389       --delink
390           Perform Delinking. If the External-Links setting is used then this
391           option actually enables delinking of the files. It defaults to on
392           and can be turned off with --no-delink. Configuration Item:
393           APT::FTPArchive::DeLinkAct.
394
395       --contents
396           Perform contents generation. When this option is set and package
397           indexes are being generated with a cache DB then the file listing
398           will also be extracted and stored in the DB for later use. When
399           using the generate command this option also allows the creation of
400           any Contents files. The default is on. Configuration Item:
401           APT::FTPArchive::Contents.
402
403       -s, --source-override
404           Select the source override file to use with the sources command.
405           Configuration Item: APT::FTPArchive::SourceOverride.
406
407       --readonly
408           Make the caching databases read only. Configuration Item:
409           APT::FTPArchive::ReadOnlyDB.
410
411       -a, --arch
412           Accept in the packages and contents commands only package files
413           matching *_arch.deb or *_all.deb instead of all package files in
414           the given path. Configuration Item: APT::FTPArchive::Architecture.
415
416       APT::FTPArchive::AlwaysStat
417           apt-ftparchive(1) caches as much as possible of metadata in a
418           cachedb. If packages are recompiled and/or republished with the
419           same version again, this will lead to problems as the now outdated
420           cached metadata like size and checksums will be used. With this
421           option enabled this will no longer happen as it will be checked if
422           the file was changed. Note that this option is set to "false" by
423           default as it is not recommend to upload multiple versions/builds
424           of a package with the same version number, so in theory nobody will
425           have these problems and therefore all these extra checks are
426           useless.
427
428       APT::FTPArchive::LongDescription
429           This configuration option defaults to "true" and should only be set
430           to "false" if the Archive generated with apt-ftparchive(1) also
431           provides Translation files. Note that the Translation-en master
432           file can only be created in the generate command.
433
434       -h, --help
435           Show a short usage summary.
436
437       -v, --version
438           Show the program version.
439
440       -c, --config-file
441           Configuration File; Specify a configuration file to use. The
442           program will read the default configuration file and then this
443           configuration file. If configuration settings need to be set before
444           the default configuration files are parsed specify a file with the
445           APT_CONFIG environment variable. See apt.conf(5) for syntax
446           information.
447
448       -o, --option
449           Set a Configuration Option; This will set an arbitrary
450           configuration option. The syntax is -o Foo::Bar=bar.  -o and
451           --option can be used multiple times to set different options.
452

EXAMPLES

454       To create a compressed Packages file for a directory containing binary
455       packages (.deb):
456
457           apt-ftparchive packages directory | gzip > Packages.gz
458

SEE ALSO

460       apt.conf(5)
461

DIAGNOSTICS

463       apt-ftparchive returns zero on normal operation, decimal 100 on error.
464

BUGS

466       APT bug page[1]. If you wish to report a bug in APT, please see
467       /usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command.
468

AUTHORS

470       Jason Gunthorpe
471
472       APT team
473

NOTES

475        1. APT bug page
476           http://bugs.debian.org/src:apt
477
478
479
480APT 2.7.6                       29 January 2023              APT-FTPARCHIVE(1)
Impressum