man/dpkg-deb.pod

   1 # dpkg manual page - dpkg-deb(1)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 1999 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2006 Frank Lichtenheld <djpig@debian.org>
   6 # Copyright © 2007-2015 Guillem Jover <guillem@debian.org>
   7 #
   8 # This is free software; you can redistribute it and/or modify
   9 # it under the terms of the GNU General Public License as published by
  10 # the Free Software Foundation; either version 2 of the License, or
  11 # (at your option) any later version.
  12 #
  13 # This is distributed in the hope that it will be useful,
  14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 # GNU General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  20
  21 =encoding utf8
  22
  23 =head1 NAME
  24
  25 dpkg-deb - Debian package archive (.deb) manipulation tool
  26
  27 =head1 SYNOPSIS
  28
  29 B<dpkg-deb>
  30 [I<option>...] I<command>
  31
  32 =head1 DESCRIPTION
  33
  34 B<dpkg-deb>
  35 packs, unpacks and provides information about Debian archives.
  36
  37 Use
  38 B<dpkg>
  39 to install and remove packages from your system.
  40
  41 You can also invoke
  42 B<dpkg-deb>
  43 by calling
  44 B<dpkg>
  45 with whatever options you want to pass to
  46 B<dpkg-deb>.
  47 B<dpkg>
  48 will spot that you wanted
  49 B<dpkg-deb>
  50 and run it for you.
  51
  52 For most commands taking an input archive argument, the archive can be
  53 read from standard input if the archive name is given as a single minus
  54 character («B<->»); otherwise lack of support will be documented in
  55 their respective command description.
  56
  57 =head1 COMMANDS
  58
  59 =over
  60
  61 =item B<-b>, B<--build> I<binary-directory> [I<archive>|I<directory>]
  62
  63 Creates a debian archive from the filesystem tree stored in
  64 I<binary-directory>.
  65 I<binary-directory>
  66 must have a
  67 B<DEBIAN>
  68 subdirectory, which contains the control information files such
  69 as the control file itself.
  70 This directory will
  71 I<not>
  72 appear in the binary package's filesystem archive, but instead
  73 the files in it will be put in the binary package's control
  74 information area.
  75
  76 Unless you specify
  77 B<--nocheck>, B<dpkg-deb>
  78 will read
  79 B<DEBIAN/control>
  80 and parse it.
  81 It will check the file for syntax errors and other problems,
  82 and display the name of the binary package being built.
  83 B<dpkg-deb>
  84 will also check the permissions of the maintainer scripts and other
  85 files found in the
  86 B<DEBIAN>
  87 control information directory.
  88
  89 If no
  90 I<archive>
  91 is specified then
  92 B<dpkg-deb>
  93 will write the package into the file
  94 I<binary-directory>B<.deb>.
  95
  96 If the archive to be created already exists it will be overwritten.
  97
  98 If the second argument is a directory then
  99 B<dpkg-deb>
 100 will write to the file
 101 I<directory>B</>I<package>B<_>I<version>B<_>I<arch>B<.deb.>
 102 When a target directory is specified, rather than a file, the
 103 B<--nocheck>
 104 option may not be used (since
 105 B<dpkg-deb>
 106 needs to read and parse the package control file to determine which
 107 filename to use).
 108
 109 =item B<-I>, B<--info> I<archive> [I<control-file-name>...]
 110
 111 Provides information about a binary package archive.
 112
 113 If no
 114 I<control-file-name>s
 115 are specified then it will print a summary of the contents of the
 116 package as well as its control file.
 117
 118 If any
 119 I<control-file-name>s
 120 are specified then
 121 B<dpkg-deb>
 122 will print them in the order they were specified; if any of the
 123 components weren't present it will print an error message to stderr
 124 about each one and exit with status 2.
 125
 126 =item B<-W>, B<--show> I<archive>
 127
 128 Provides information about a binary package archive in the format
 129 specified by the
 130 B<--showformat>
 131 argument.
 132 The default format displays the package's name and version
 133 on one line, separated by a tabulator.
 134
 135 =item B<-f>, B<--field> I<archive> [I<control-field-name>...]
 136
 137 Extracts control file information from a binary package archive.
 138
 139 If no
 140 I<control-field-name>s
 141 are specified then it will print the whole control file.
 142
 143 If any are specified then
 144 B<dpkg-deb>
 145 will print their contents, in the order in which they appear in the
 146 control file.
 147 If more than one
 148 I<control-field-name>
 149 is specified then
 150 B<dpkg-deb>
 151 will precede each with its field name (and a colon and space).
 152
 153 No errors are reported for fields requested but not found.
 154
 155 =item B<-c>, B<--contents> I<archive>
 156
 157 Lists the contents of the filesystem tree archive portion of the
 158 package archive.
 159 It is currently produced in the format generated by
 160 B<tar>'s
 161 verbose listing.
 162
 163 =item B<-x>, B<--extract> I<archive> I<directory>
 164
 165 Extracts the filesystem tree from a package archive into the specified
 166 directory.
 167
 168 Note that extracting a package to the root directory will
 169 I<not>
 170 result in a correct installation!
 171 Use
 172 B<dpkg>
 173 to install packages.
 174
 175 I<directory>
 176 (but not its parents) will be created if necessary, and its permissions
 177 modified to match the contents of the package.
 178
 179 =item B<-X>, B<--vextract> I<archive> I<directory>
 180
 181 Is like
 182 B<--extract> (B<-x>)
 183 with
 184 B<--verbose> (B<-v>)
 185 which prints a listing of the files extracted as it goes.
 186
 187 =item B<-R>, B<--raw-extract> I<archive> I<directory>
 188
 189 Extracts the filesystem tree from a package archive into a specified
 190 directory, and the control information files into a
 191 B<DEBIAN>
 192 subdirectory of the specified directory (since dpkg 1.16.1).
 193
 194 The target directory (but not its parents) will be created if necessary.
 195
 196 The input archive is not (currently) processed sequentially, so reading
 197 it from standard input («B<->») is B<not> supported.
 198
 199 =item B<--ctrl-tarfile> I<archive>
 200
 201 Extracts the control data from a binary package and sends it to standard
 202 output in
 203 B<tar>
 204 format (since dpkg 1.17.14).
 205 Together with
 206 L<tar(1)>
 207 this can be used to extract a particular control file from a package archive.
 208 The input archive will always be processed sequentially.
 209
 210 =item B<--fsys-tarfile> I<archive>
 211
 212 Extracts the filesystem tree data from a binary package and sends it
 213 to standard output in
 214 B<tar>
 215 format.
 216 Together with
 217 L<tar(1)>
 218 this can be used to extract a particular file from a package archive.
 219 The input archive will always be processed sequentially.
 220
 221 =item B<-e>, B<--control> I<archive> [I<directory>]
 222
 223 Extracts the control information files from a package archive into the
 224 specified directory.
 225
 226 If no directory is specified then a subdirectory
 227 B<DEBIAN>
 228 in the current directory is used.
 229
 230 The target directory (but not its parents) will be created if
 231 necessary.
 232
 233 =item B<-?>, B<--help>
 234
 235 Show the usage message and exit.
 236
 237 =item B<--version>
 238
 239 Show the version and exit.
 240
 241 =back
 242
 243 =head1 OPTIONS
 244
 245 =over
 246
 247 =item B<--showformat=>I<format>
 248
 249 This option is used to specify the format of the output B<--show>
 250 will produce.
 251 The format is a string that will be output for each package
 252 listed.
 253
 254 The string may reference any status field using the
 255 “${I<field-name>}” form, a list of the valid fields can be easily
 256 produced using
 257 B<-I>
 258 on the same package.
 259 A complete explanation of the formatting options
 260 (including escape sequences and field tabbing) can be found in the
 261 explanation of the B<--showformat> option in
 262 L<dpkg-query(1)>.
 263
 264 The default for this field is “${Package}\t${Version}\n”.
 265
 266 =item B<-z>I<compress-level>
 267
 268 Specify which compression level to use on the compressor backend, when
 269 building a package (default is 9 for gzip, 6 for xz, 3 for zstd).
 270 The accepted values are compressor specific.
 271 For gzip, from 0-9 with 0 being mapped to compressor none.
 272 For xz from 0-9.
 273 For zstd from 0-22, with levels from 20 to 22 enabling its ultra mode.
 274 Before dpkg 1.16.2 level 0 was equivalent to compressor none for all
 275 compressors.
 276
 277 =item B<-S>I<compress-strategy>
 278
 279 Specify which compression strategy to use on the compressor backend, when
 280 building a package (since dpkg 1.16.2).
 281 Allowed values are B<none> (since
 282 dpkg 1.16.4), B<filtered>, B<huffman>, B<rle> and B<fixed> for
 283 gzip (since dpkg 1.17.0) and B<extreme> for xz.
 284
 285 =item B<-Z>I<compress-type>
 286
 287 Specify which compression type to use when building a package.
 288 Allowed values are B<gzip>, B<xz> (since dpkg 1.15.6),
 289 B<zstd> (since dpkg 1.21.18)
 290 and B<none> (default is B<%DEB_DEFAULT_COMPRESSOR%>).
 291
 292 =item B<--[no-]uniform-compression>
 293
 294 Specify that the same compression parameters should be used for all archive
 295 members (i.e. B<control.tar> and B<data.tar>; since dpkg 1.17.6).
 296 Otherwise only the
 297 B<data.tar> member will use those parameters.
 298 The only supported
 299 compression types allowed to be uniformly used are B<none>, B<gzip>,
 300 B<xz> and B<zstd>.
 301 The B<--no-uniform-compression> option disables uniform compression
 302 (since dpkg 1.19.0).
 303 Uniform compression is the default (since dpkg 1.19.0).
 304
 305 =item B<--threads-max=>I<threads>
 306
 307 Sets the maximum number of threads allowed for compressors that support
 308 multi-threaded operations (since dpkg 1.21.9).
 309
 310 =item B<--root-owner-group>
 311
 312 Set the owner and group for each entry in the filesystem tree data to
 313 root with id 0 (since dpkg 1.19.0).
 314
 315 B<Note>: This option can be useful for rootless builds (see
 316 I<rootless-builds.txt>), but should B<not> be used when the
 317 entries have an owner or group that is not root.
 318 Support for these will be added later in the form of a meta manifest.
 319
 320 =item B<--deb-format=>I<format>
 321
 322 Set the archive format version used when building (since dpkg 1.17.0).
 323 Allowed values are B<2.0> for the new format, and B<0.939000>
 324 for the old one (default is B<2.0>).
 325
 326 The old archive format is less easily parsed by non-Debian tools and is
 327 now obsolete; its only use is when building packages to be parsed by
 328 versions of dpkg older than 0.93.76 (September 1995), which was released
 329 as i386 a.out only.
 330
 331 =item B<--nocheck>
 332
 333 Inhibits
 334 B<dpkg-deb --build>'s
 335 usual checks on the proposed contents of an archive.
 336 You can build
 337 any archive you want, no matter how broken, this way.
 338
 339 =item B<-v>, B<--verbose>
 340
 341 Enables verbose output (since dpkg 1.16.1).
 342 This currently only affects B<--extract> making it behave like
 343 B<--vextract>.
 344
 345 =item B<-D>, B<--debug>
 346
 347 Enables debugging output.
 348 This is not very interesting.
 349
 350 =back
 351
 352 =head1 EXIT STATUS
 353
 354 =over
 355
 356 =item B<0>
 357
 358 The requested action was successfully performed.
 359
 360 =item B<2>
 361
 362 Fatal or unrecoverable error due to invalid command-line usage, or
 363 interactions with the system, such as accesses to the database,
 364 memory allocations, etc.
 365
 366 =back
 367
 368 =head1 ENVIRONMENT
 369
 370 =over
 371
 372 =item B<DPKG_DEB_THREADS_MAX>
 373
 374 Sets the maximum number of threads allowed for compressors that support
 375 multi-threaded operations (since dpkg 1.21.9).
 376
 377 The B<--threads-max> option overrides this value.
 378
 379 =item B<DPKG_DEB_COMPRESSOR_TYPE>
 380
 381 Sets the compressor type to use (since dpkg 1.21.10).
 382
 383 The B<-Z> option overrides this value.
 384
 385 =item B<DPKG_DEB_COMPRESSOR_LEVEL>
 386
 387 Sets the compressor level to use (since dpkg 1.21.10).
 388
 389 The B<-z> option overrides this value.
 390
 391 =item B<DPKG_COLORS>
 392
 393 Sets the color mode (since dpkg 1.18.5).
 394 The currently accepted values are: B<auto> (default), B<always> and
 395 B<never>.
 396
 397 =item B<DPKG_NLS>
 398
 399 If set, it will be used to decide whether to activate Native Language Support,
 400 also known as internationalization (or i18n) support (since dpkg 1.22.7).
 401 The accepted values are: B<0> and B<1> (default).
 402
 403 =item B<TMPDIR>
 404
 405 If set, B<dpkg-deb> will use it as the directory in which to create
 406 temporary files and directories.
 407
 408 =item B<SOURCE_DATE_EPOCH>
 409
 410 If set, it will be used as the timestamp (as seconds since the epoch) in
 411 the L<deb(5)>'s L<ar(5)> container and used to clamp the mtime in
 412 the L<tar(5)> file entries.
 413
 414 Since dpkg 1.18.8.
 415
 416 =back
 417
 418 =head1 NOTES
 419
 420 Do not attempt to use just
 421 B<dpkg-deb>
 422 to install software!
 423 You must use
 424 B<dpkg>
 425 proper to ensure that all the files are correctly placed and the
 426 package's scripts run and its status and contents recorded.
 427
 428 =head1 SECURITY
 429
 430 Examining untrusted package archives or extracting them into staging
 431 directories should be considered a security boundary, and any breakage
 432 of that boundary stemming from these operations should be considered a
 433 security vulnerability.
 434 But handling untrusted package archives should not be done lightly,
 435 as the surface area includes any compression library supported,
 436 in addition to the archive formats and control files themselves.
 437 Performing these operations over untrusted data as root is strongly
 438 discouraged.
 439
 440 Building package archives should only be performed over trusted data.
 441
 442 =head1 BUGS
 443
 444 B<dpkg-deb -I>
 445 I<package1>B<.deb>
 446 I<package2>B<.deb>
 447 does the wrong thing.
 448
 449 There is no authentication on
 450 B<.deb>
 451 files; in fact, there isn't even a straightforward checksum.
 452 (Higher level tools like APT support authenticating B<.deb> packages
 453 retrieved from a given repository, and most packages nowadays provide an
 454 md5sum control file generated by debian/rules.
 455 Though this is not directly
 456 supported by the lower level tools.)
 457
 458 =head1 SEE ALSO
 459
 460 F<%PKGDOCDIR%/spec/rootless-builds.txt>,
 461 L<deb(5)>,
 462 L<deb-control(5)>,
 463 L<dpkg(1)>,
 464 L<dselect(1)>.