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