diff options
Diffstat (limited to '')
| -rw-r--r-- | man/dpkg-deb.pod | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/man/dpkg-deb.pod b/man/dpkg-deb.pod new file mode 100644 index 0000000..103d6c0 --- /dev/null +++ b/man/dpkg-deb.pod @@ -0,0 +1,456 @@ +# dpkg manual page - dpkg-deb(1) +# +# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk> +# Copyright © 1999 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2006 Frank Lichtenheld <djpig@debian.org> +# Copyright © 2007-2015 Guillem Jover <guillem@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +dpkg-deb - Debian package archive (.deb) manipulation tool + +=head1 SYNOPSIS + +B<dpkg-deb> +[I<option>...] I<command> + +=head1 DESCRIPTION + +B<dpkg-deb> +packs, unpacks and provides information about Debian archives. + +Use +B<dpkg> +to install and remove packages from your system. + +You can also invoke +B<dpkg-deb> +by calling +B<dpkg> +with whatever options you want to pass to +B<dpkg-deb>. +B<dpkg> +will spot that you wanted +B<dpkg-deb> +and run it for you. + +For most commands taking an input archive argument, the archive can be +read from standard input if the archive name is given as a single minus +character («B<->»); otherwise lack of support will be documented in +their respective command description. + +=head1 COMMANDS + +=over + +=item B<-b>, B<--build> I<binary-directory> [I<archive>|I<directory>] + +Creates a debian archive from the filesystem tree stored in +I<binary-directory>. +I<binary-directory> +must have a +B<DEBIAN> +subdirectory, which contains the control information files such +as the control file itself. +This directory will +I<not> +appear in the binary package's filesystem archive, but instead +the files in it will be put in the binary package's control +information area. + +Unless you specify +B<--nocheck>, B<dpkg-deb> +will read +B<DEBIAN/control> +and parse it. +It will check the file for syntax errors and other problems, +and display the name of the binary package being built. +B<dpkg-deb> +will also check the permissions of the maintainer scripts and other +files found in the +B<DEBIAN> +control information directory. + +If no +I<archive> +is specified then +B<dpkg-deb> +will write the package into the file +I<binary-directory>B<.deb>. + +If the archive to be created already exists it will be overwritten. + +If the second argument is a directory then +B<dpkg-deb> +will write to the file +I<directory>B</>I<package>B<_>I<version>B<_>I<arch>B<.deb.> +When a target directory is specified, rather than a file, the +B<--nocheck> +option may not be used (since +B<dpkg-deb> +needs to read and parse the package control file to determine which +filename to use). + +=item B<-I>, B<--info> I<archive> [I<control-file-name>...] + +Provides information about a binary package archive. + +If no +I<control-file-name>s +are specified then it will print a summary of the contents of the +package as well as its control file. + +If any +I<control-file-name>s +are specified then +B<dpkg-deb> +will print them in the order they were specified; if any of the +components weren't present it will print an error message to stderr +about each one and exit with status 2. + +=item B<-W>, B<--show> I<archive> + +Provides information about a binary package archive in the format +specified by the +B<--showformat> +argument. +The default format displays the package's name and version +on one line, separated by a tabulator. + +=item B<-f>, B<--field> I<archive> [I<control-field-name>...] + +Extracts control file information from a binary package archive. + +If no +I<control-field-name>s +are specified then it will print the whole control file. + +If any are specified then +B<dpkg-deb> +will print their contents, in the order in which they appear in the +control file. +If more than one +I<control-field-name> +is specified then +B<dpkg-deb> +will precede each with its field name (and a colon and space). + +No errors are reported for fields requested but not found. + +=item B<-c>, B<--contents> I<archive> + +Lists the contents of the filesystem tree archive portion of the +package archive. +It is currently produced in the format generated by +B<tar>'s +verbose listing. + +=item B<-x>, B<--extract> I<archive> I<directory> + +Extracts the filesystem tree from a package archive into the specified +directory. + +Note that extracting a package to the root directory will +I<not> +result in a correct installation! +Use +B<dpkg> +to install packages. + +I<directory> +(but not its parents) will be created if necessary, and its permissions +modified to match the contents of the package. + +=item B<-X>, B<--vextract> I<archive> I<directory> + +Is like +B<--extract> (B<-x>) +with +B<--verbose> (B<-v>) +which prints a listing of the files extracted as it goes. + +=item B<-R>, B<--raw-extract> I<archive> I<directory> + +Extracts the filesystem tree from a package archive into a specified +directory, and the control information files into a +B<DEBIAN> +subdirectory of the specified directory (since dpkg 1.16.1). + +The target directory (but not its parents) will be created if necessary. + +The input archive is not (currently) processed sequentially, so reading +it from standard input («B<->») is B<not> supported. + +=item B<--ctrl-tarfile> I<archive> + +Extracts the control data from a binary package and sends it to standard +output in +B<tar> +format (since dpkg 1.17.14). +Together with +L<tar(1)> +this can be used to extract a particular control file from a package archive. +The input archive will always be processed sequentially. + +=item B<--fsys-tarfile> I<archive> + +Extracts the filesystem tree data from a binary package and sends it +to standard output in +B<tar> +format. +Together with +L<tar(1)> +this can be used to extract a particular file from a package archive. +The input archive will always be processed sequentially. + +=item B<-e>, B<--control> I<archive> [I<directory>] + +Extracts the control information files from a package archive into the +specified directory. + +If no directory is specified then a subdirectory +B<DEBIAN> +in the current directory is used. + +The target directory (but not its parents) will be created if +necessary. + +=item B<-?>, B<--help> + +Show the usage message and exit. + +=item B<--version> + +Show the version and exit. + +=back + +=head1 OPTIONS + +=over + +=item B<--showformat=>I<format> + +This option is used to specify the format of the output B<--show> +will produce. +The format is a string that will be output for each package +listed. + +The string may reference any status field using the +“${I<field-name>}” form, a list of the valid fields can be easily +produced using +B<-I> +on the same package. +A complete explanation of the formatting options +(including escape sequences and field tabbing) can be found in the +explanation of the B<--showformat> option in +L<dpkg-query(1)>. + +The default for this field is “${Package}\t${Version}\n”. + +=item B<-z>I<compress-level> + +Specify which compression level to use on the compressor backend, when +building a package (default is 9 for gzip, 6 for xz, 3 for zstd). +The accepted values are compressor specific. +For gzip, from 0-9 with 0 being mapped to compressor none. +For xz from 0-9. +For zstd from 0-22, with levels from 20 to 22 enabling its ultra mode. +Before dpkg 1.16.2 level 0 was equivalent to compressor none for all +compressors. + +=item B<-S>I<compress-strategy> + +Specify which compression strategy to use on the compressor backend, when +building a package (since dpkg 1.16.2). +Allowed values are B<none> (since +dpkg 1.16.4), B<filtered>, B<huffman>, B<rle> and B<fixed> for +gzip (since dpkg 1.17.0) and B<extreme> for xz. + +=item B<-Z>I<compress-type> + +Specify which compression type to use when building a package. +Allowed values are B<gzip>, B<xz> (since dpkg 1.15.6), +B<zstd> (since dpkg 1.21.18) +and B<none> (default is B<%DEB_DEFAULT_COMPRESSOR%>). + +=item B<--[no-]uniform-compression> + +Specify that the same compression parameters should be used for all archive +members (i.e. B<control.tar> and B<data.tar>; since dpkg 1.17.6). +Otherwise only the +B<data.tar> member will use those parameters. +The only supported +compression types allowed to be uniformly used are B<none>, B<gzip>, +B<xz> and B<zstd>. +The B<--no-uniform-compression> option disables uniform compression +(since dpkg 1.19.0). +Uniform compression is the default (since dpkg 1.19.0). + +=item B<--threads-max=>I<threads> + +Sets the maximum number of threads allowed for compressors that support +multi-threaded operations (since dpkg 1.21.9). + +=item B<--root-owner-group> + +Set the owner and group for each entry in the filesystem tree data to +root with id 0 (since dpkg 1.19.0). + +B<Note>: This option can be useful for rootless builds (see +I<rootless-builds.txt>), but should B<not> be used when the +entries have an owner or group that is not root. +Support for these will be added later in the form of a meta manifest. + +=item B<--deb-format=>I<format> + +Set the archive format version used when building (since dpkg 1.17.0). +Allowed values are B<2.0> for the new format, and B<0.939000> +for the old one (default is B<2.0>). + +The old archive format is less easily parsed by non-Debian tools and is +now obsolete; its only use is when building packages to be parsed by +versions of dpkg older than 0.93.76 (September 1995), which was released +as i386 a.out only. + +=item B<--nocheck> + +Inhibits +B<dpkg-deb --build>'s +usual checks on the proposed contents of an archive. +You can build +any archive you want, no matter how broken, this way. + +=item B<-v>, B<--verbose> + +Enables verbose output (since dpkg 1.16.1). +This currently only affects B<--extract> making it behave like +B<--vextract>. + +=item B<-D>, B<--debug> + +Enables debugging output. +This is not very interesting. + +=back + +=head1 EXIT STATUS + +=over + +=item B<0> + +The requested action was successfully performed. + +=item B<2> + +Fatal or unrecoverable error due to invalid command-line usage, or +interactions with the system, such as accesses to the database, +memory allocations, etc. + +=back + +=head1 ENVIRONMENT + +=over + +=item B<DPKG_DEB_THREADS_MAX> + +Sets the maximum number of threads allowed for compressors that support +multi-threaded operations (since dpkg 1.21.9). + +The B<--threads-max> option overrides this value. + +=item B<DPKG_DEB_COMPRESSOR_TYPE> + +Sets the compressor type to use (since dpkg 1.21.10). + +The B<-Z> option overrides this value. + +=item B<DPKG_DEB_COMPRESSOR_LEVEL> + +Sets the compressor level to use (since dpkg 1.21.10). + +The B<-z> option overrides this value. + +=item B<DPKG_COLORS> + +Sets the color mode (since dpkg 1.18.5). +The currently accepted values are: B<auto> (default), B<always> and +B<never>. + +=item B<TMPDIR> + +If set, B<dpkg-deb> will use it as the directory in which to create +temporary files and directories. + +=item B<SOURCE_DATE_EPOCH> + +If set, it will be used as the timestamp (as seconds since the epoch) in +the L<deb(5)>'s L<ar(5)> container and used to clamp the mtime in +the L<tar(5)> file entries. + +=back + +=head1 NOTES + +Do not attempt to use just +B<dpkg-deb> +to install software! +You must use +B<dpkg> +proper to ensure that all the files are correctly placed and the +package's scripts run and its status and contents recorded. + +=head1 SECURITY + +Examining untrusted package archives or extracting them into staging +directories should be considered a security boundary, and any breakage +of that boundary stemming from these operations should be considered a +security vulnerability. +But handling untrusted package archives should not be done lightly, +as the surface area includes any compression library supported, +in addition to the archive formats and control files themselves. +Performing these operations over untrusted data as root is strongly +discouraged. + +Building package archives should only be performed over trusted data. + +=head1 BUGS + +B<dpkg-deb -I> +I<package1>B<.deb> +I<package2>B<.deb> +does the wrong thing. + +There is no authentication on +B<.deb> +files; in fact, there isn't even a straightforward checksum. +(Higher level tools like APT support authenticating B<.deb> packages +retrieved from a given repository, and most packages nowadays provide an +md5sum control file generated by debian/rules. +Though this is not directly +supported by the lower level tools.) + +=head1 SEE ALSO + +F<%PKGDOCDIR%/spec/rootless-builds.txt>, +L<deb(5)>, +L<deb-control(5)>, +L<dpkg(1)>, +L<dselect(1)>. |