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>, B<--compression-level=>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 long option since dpkg 1.22.9).
 271 The accepted values are compressor specific.
 272 For gzip, from 0-9 with 0 being mapped to compressor none.
 273 For xz from 0-9.
 274 For zstd from 0-22, with levels from 20 to 22 enabling its ultra mode.
 275 Before dpkg 1.16.2 level 0 was equivalent to compressor none for all
 276 compressors.
 277
 278 =item B<-S>, B<--compression-strategy=>I<compress-strategy>
 279
 280 Specify which compression strategy to use on the compressor backend, when
 281 building a package (since dpkg 1.16.2, long option since dpkg 1.22.9).
 282 Allowed values are B<none> (since
 283 dpkg 1.16.4), B<filtered>, B<huffman>, B<rle> and B<fixed> for
 284 gzip (since dpkg 1.17.0) and B<extreme> for xz.
 285
 286 =item B<-Z>, B<--compression=>I<compress-type>
 287
 288 Specify which compression type to use when building a package
 289 (long option since dpkg 1.22.9).
 290 Allowed values are B<gzip>, B<xz> (since dpkg 1.15.6),
 291 B<zstd> (since dpkg 1.21.18)
 292 and B<none> (default is B<%DEB_DEFAULT_COMPRESSOR%>).
 293
 294 =item B<--[no-]uniform-compression>
 295
 296 Specify that the same compression parameters should be used for all archive
 297 members (i.e. B<control.tar> and B<data.tar>; since dpkg 1.17.6).
 298 Otherwise only the
 299 B<data.tar> member will use those parameters.
 300 The only supported
 301 compression types allowed to be uniformly used are B<none>, B<gzip>,
 302 B<xz> and B<zstd>.
 303 The B<--no-uniform-compression> option disables uniform compression
 304 (since dpkg 1.19.0).
 305 Uniform compression is the default (since dpkg 1.19.0).
 306
 307 =item B<--threads-max=>I<threads>
 308
 309 Sets the maximum number of threads allowed for compressors that support
 310 multi-threaded operations (since dpkg 1.21.9).
 311
 312 =item B<--root-owner-group>
 313
 314 Set the owner and group for each entry in the filesystem tree data to
 315 root with id 0 (since dpkg 1.19.0).
 316
 317 B<Note>: This option can be useful for rootless builds (see
 318 I<rootless-builds.txt>), but should B<not> be used when the
 319 entries have an owner or group that is not root.
 320 Support for these will be added later in the form of a meta manifest.
 321
 322 =item B<--deb-format=>I<format>
 323
 324 Set the archive format version used when building (since dpkg 1.17.0).
 325 Allowed values are B<2.0> for the new format, and B<0.939000>
 326 for the old one (default is B<2.0>).
 327
 328 The old archive format is less easily parsed by non-Debian tools and is
 329 now obsolete; its only use is when building packages to be parsed by
 330 versions of dpkg older than 0.93.76 (September 1995), which was released
 331 as i386 a.out only.
 332
 333 =item B<--nocheck>
 334
 335 Inhibits
 336 B<dpkg-deb --build>'s
 337 usual checks on the proposed contents of an archive.
 338 You can build
 339 any archive you want, no matter how broken, this way.
 340
 341 =item B<-v>, B<--verbose>
 342
 343 Enables verbose output (since dpkg 1.16.1).
 344 This currently only affects B<--extract> making it behave like
 345 B<--vextract>.
 346
 347 =item B<-D>, B<--debug>
 348
 349 Enables debugging output.
 350 This is not very interesting.
 351
 352 =back
 353
 354 =head1 EXIT STATUS
 355
 356 =over
 357
 358 =item B<0>
 359
 360 The requested action was successfully performed.
 361
 362 =item B<2>
 363
 364 Fatal or unrecoverable error due to invalid command-line usage, or
 365 interactions with the system, such as accesses to the database,
 366 memory allocations, etc.
 367
 368 =back
 369
 370 =head1 ENVIRONMENT
 371
 372 =over
 373
 374 =item B<DPKG_DEB_THREADS_MAX>
 375
 376 Sets the maximum number of threads allowed for compressors that support
 377 multi-threaded operations (since dpkg 1.21.9).
 378
 379 The B<--threads-max> option overrides this value.
 380
 381 =item B<DPKG_DEB_COMPRESSOR_TYPE>
 382
 383 Sets the compressor type to use (since dpkg 1.21.10).
 384
 385 The B<-Z> option overrides this value.
 386
 387 =item B<DPKG_DEB_COMPRESSOR_LEVEL>
 388
 389 Sets the compressor level to use (since dpkg 1.21.10).
 390
 391 The B<-z> option overrides this value.
 392
 393 =item B<DPKG_COLORS>
 394
 395 Sets the color mode (since dpkg 1.18.5).
 396 The currently accepted values are: B<auto> (default), B<always> and
 397 B<never>.
 398
 399 =item B<DPKG_NLS>
 400
 401 If set, it will be used to decide whether to activate Native Language Support,
 402 also known as internationalization (or i18n) support (since dpkg 1.22.7).
 403 The accepted values are: B<0> and B<1> (default).
 404
 405 =item B<TMPDIR>
 406
 407 If set, B<dpkg-deb> will use it as the directory in which to create
 408 temporary files and directories.
 409
 410 =item B<SOURCE_DATE_EPOCH>
 411
 412 If set, it will be used as the timestamp (as seconds since the epoch) in
 413 the L<deb(5)>'s L<ar(5)> container and used to clamp the mtime in
 414 the L<tar(5)> file entries.
 415
 416 Since dpkg 1.18.8.
 417
 418 =back
 419
 420 =head1 NOTES
 421
 422 Do not attempt to use just
 423 B<dpkg-deb>
 424 to install software!
 425 You must use
 426 B<dpkg>
 427 proper to ensure that all the files are correctly placed and the
 428 package's scripts run and its status and contents recorded.
 429
 430 =head1 SECURITY
 431
 432 Examining untrusted package archives or extracting them into staging
 433 directories should be considered a security boundary, and any breakage
 434 of that boundary stemming from these operations should be considered a
 435 security vulnerability.
 436 But handling untrusted package archives should not be done lightly,
 437 as the surface area includes any compression library supported,
 438 in addition to the archive formats and control files themselves.
 439 Performing these operations over untrusted data as root is strongly
 440 discouraged.
 441
 442 Building package archives should only be performed over trusted data.
 443
 444 =head1 BUGS
 445
 446 B<dpkg-deb -I>
 447 I<package1>B<.deb>
 448 I<package2>B<.deb>
 449 does the wrong thing.
 450
 451 There is no authentication on
 452 B<.deb>
 453 files; in fact, there isn't even a straightforward checksum.
 454 (Higher level tools like APT support authenticating B<.deb> packages
 455 retrieved from a given repository, and most packages nowadays provide an
 456 md5sum control file generated by debian/rules.
 457 Though this is not directly
 458 supported by the lower level tools.)
 459
 460 =head1 SEE ALSO
 461
 462 F<%PKGDOCDIR%/spec/rootless-builds.txt>,
 463 L<deb(5)>,
 464 L<deb-control(5)>,
 465 L<dpkg(1)>,
 466 L<dselect(1)>.