488 lines
13 KiB
Text
488 lines
13 KiB
Text
# 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<--no-check>, 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<--no-check>
|
|
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>, B<--compression-level=>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;
|
|
long option since dpkg 1.22.9).
|
|
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>, B<--compression-strategy=>I<compress-strategy>
|
|
|
|
Specify which compression strategy to use on the compressor backend, when
|
|
building a package (since dpkg 1.16.2, long option since dpkg 1.22.9).
|
|
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>, B<--compression=>I<compress-type>
|
|
|
|
Specify which compression type to use when building a package
|
|
(long option since dpkg 1.22.9).
|
|
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<--no-check>
|
|
|
|
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.
|
|
|
|
Option supported since dpkg 1.22.12.
|
|
|
|
=item B<--nocheck>
|
|
|
|
This is an alias for B<--no-check>.
|
|
|
|
=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<DPKG_NLS>
|
|
|
|
If set, it will be used to decide whether to activate Native Language Support,
|
|
also known as internationalization (or i18n) support (since dpkg 1.22.7).
|
|
The accepted values are: B<0> and B<1> (default).
|
|
|
|
=item B<DPKG_PATH_PASSWD>
|
|
|
|
Sets the pathname for the system F<passwd> file.
|
|
This path is relative to the B<--root> directory.
|
|
The default is F</etc/passwd>.
|
|
|
|
Since dpkg 1.22.16.
|
|
|
|
=item B<DPKG_PATH_GROUP>
|
|
|
|
Sets the pathname for the system F<group> file.
|
|
This path is relative to the B<--root> directory.
|
|
The default is F</etc/group>.
|
|
|
|
Since dpkg 1.22.16.
|
|
|
|
=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.
|
|
|
|
Since dpkg 1.18.8.
|
|
|
|
=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)>.
|