1APT-FTPARCHIVE(1) APT APT-FTPARCHIVE(1)
2
6 apt-ftparchive - Utility to generate index files
7
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
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 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 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 Unless the -h, or --help option is given, one of the commands below
35 must be present.
36 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 The option --db can be used to specify a binary caching DB.
44 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 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 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 The option --db can be used to specify a binary caching DB.
66 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 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 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 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
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 The generate configuration has four separate sections, each described
107 below.
108 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 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 OverrideDir
121 Specifies the location of the override files.
122 CacheDir
124 Specifies the location of the cache files.
125 FileListDir
127 Specifies the location of the file list files, if the FileList
128 setting is used below.
129 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 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 Packages::Extensions
143 Sets the default list of file extensions that are package files.
144 This defaults to '.deb'.
145 Sources::Compress
147 This is similar to Packages::Compress except that it controls the
148 compression for the Sources files.
149 Sources::Extensions
151 Sets the default list of file extensions that are source files.
152 This defaults to '.dsc'.
153 Contents::Compress
155 This is similar to Packages::Compress except that it controls the
156 compression for the Contents files.
157 Translation::Compress
159 This is similar to Packages::Compress except that it controls the
160 compression for the Translation-en master file.
161 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 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 LongDescription
172 Specifies whether long descriptions should be included in the
173 Packages file or split out into a master Translation-en file.
174 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 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 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 Directory
195 Sets the top of the .deb directory tree. Defaults to
196 $(DIST)/$(SECTION)/binary-$(ARCH)/
197 SrcDirectory
199 Sets the top of the source package directory tree. Defaults to
200 $(DIST)/$(SECTION)/source/
201 Packages
203 Sets the output Packages file. Defaults to
204 $(DIST)/$(SECTION)/binary-$(ARCH)/Packages
205 Sources
207 Sets the output Sources file. Defaults to
208 $(DIST)/$(SECTION)/source/Sources
209 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 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 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 Contents::Header
228 Sets header file to prepend to the contents output.
229 BinCacheDB
231 Sets the binary cache database to use for this section. Multiple
232 sections can share the same database.
233 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 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 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 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 All of the settings defined in the TreeDefault section can be used in a
256 Tree section as well as three new variables.
257 When processing a Tree section apt-ftparchive performs an operation
259 similar to:
260 for i in Sections do
262 for j in Architectures do
263 Generate for DIST=scope SECTION=i ARCH=j
264 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 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 LongDescription
281 Specifies whether long descriptions should be included in the
282 Packages file or split out into a master Translation-en file.
283 BinOverride
285 Sets the binary override file. The override file contains section,
286 priority and maintainer address information.
287 SrcOverride
289 Sets the source override file. The override file contains section
290 information.
291 ExtraOverride
293 Sets the binary extra override file.
294 SrcExtraOverride
296 Sets the source extra override file.
297 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 Packages
305 Sets the Packages file output.
306 Sources
308 Sets the Sources file output. At least one of Packages or Sources
309 is required.
310 Contents
312 Sets the Contents file output (optional).
313 BinOverride
315 Sets the binary override file.
316 SrcOverride
318 Sets the source override file.
319 ExtraOverride
321 Sets the binary extra override file.
322 SrcExtraOverride
324 Sets the source extra override file.
325 BinCacheDB
327 Sets the cache DB.
328 PathPrefix
330 Appends a path to all the output paths.
331 FileList, SourceFileList
333 Specifies the file list file.
334
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 The general form of the maintainer field is:
343 old [// oldn]* => new
345 or simply,
347 new
349 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
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
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
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 --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 -d, --db
380 Use a binary caching DB. This has no effect on the generate
381 command. Configuration Item: APT::FTPArchive::DB.
382 -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 --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 --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 -s, --source-override
404 Select the source override file to use with the sources command.
405 Configuration Item: APT::FTPArchive::SourceOverride.
406 --readonly
408 Make the caching databases read only. Configuration Item:
409 APT::FTPArchive::ReadOnlyDB.
410 -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 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 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 -h, --help
435 Show a short usage summary.
436 -v, --version
438 Show the program version.
439 -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 -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
454 To create a compressed Packages file for a directory containing binary
455 packages (.deb):
456 apt-ftparchive packages directory | gzip > Packages.gz
458
460 apt.conf(5)
461
463 apt-ftparchive returns zero on normal operation, decimal 100 on error.
464
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
470 Jason Gunthorpe
471 APT team
473
475 1. APT bug page
476 http://bugs.debian.org/src:apt
477APT 2.7.6 29 January 2023 APT-FTPARCHIVE(1)