diff options
Diffstat (limited to '')
| -rw-r--r-- | man/dpkg.pod | 1702 |
1 files changed, 1702 insertions, 0 deletions
diff --git a/man/dpkg.pod b/man/dpkg.pod new file mode 100644 index 0000000..75493cd --- /dev/null +++ b/man/dpkg.pod @@ -0,0 +1,1702 @@ +# dpkg manual page - dpkg(1) +# +# Copyright © 1996 Juho Vuori <javuori@cc.helsinki.fi> +# Copyright © 1999 Jim Van Zandt <jrv@vanzandt.mv.com> +# Copyright © 1999-2003 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2000-2003 Adam Heath <doogie@debian.org> +# Copyright © 2002 Josip Rodin +# Copyright © 2004-2005 Scott James Remnant <keybuk@debian.org> +# Copyright © 2006-2016 Guillem Jover <guillem@debian.org> +# Copyright © 2007-2008 Ian Jackson <ijackson@chiark.greenend.org.uk> +# Copyright © 2008-2011 Raphaël Hertzog <hertzog@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 - package manager for Debian + +=head1 SYNOPSIS + +B<dpkg> +[I<option>...] I<action> + +=head1 WARNING + +This manual is intended for users wishing to understand B<dpkg>'s +command line options and package states in more detail than that +provided by B<dpkg --help>. + +It should I<not> be used by package maintainers wishing to +understand how B<dpkg> will install their packages. +The +descriptions of what B<dpkg> does when installing and removing +packages are particularly inadequate. + +=head1 DESCRIPTION + +B<dpkg> is a medium-level tool to install, build, remove and manage +Debian packages. +The primary and more user-friendly front-end for B<dpkg> +as a CLI (command-line interface) is L<apt(8)> and +as a TUI (terminal user interface) is L<aptitude(8)>. +B<dpkg> itself is +controlled entirely via command line parameters, which consist of exactly +one action and zero or more options. +The action-parameter tells B<dpkg> +what to do and options control the behavior of the action in some way. + +B<dpkg> can also be used as a front-end to L<dpkg-deb(1)> and +L<dpkg-query(1)>. +The list of supported actions can be found later on in the B<ACTIONS> section. +If any such action is encountered B<dpkg> +just runs B<dpkg-deb> or B<dpkg-query> with the parameters given +to it, but no specific options are currently passed to them, to use +any such option the back-ends need to be called directly. + +=head1 INFORMATION ABOUT PACKAGES + +B<dpkg> maintains some usable information about available +packages. +The information is divided in three classes: B<states>, +B<selection states> and B<flags>. +These values are intended to +be changed mainly with B<dselect>. + +=head2 Package states + +=over + +=item B<not-installed> + +The package is not installed on your system. + +=item B<config-files> + +Only the configuration files or the B<postrm> script and the data it needs +to remove of the package exist on the system. + +=item B<half-installed> + +The installation of the package has been started, but not completed for +some reason. + +=item B<unpacked> + +The package is unpacked, but not configured. + +=item B<half-configured> + +The package is unpacked and configuration has been started, but not yet +completed for some reason. + +=item B<triggers-awaited> + +The package awaits trigger processing by another package. + +=item B<triggers-pending> + +The package has been triggered. + +=item B<installed> + +The package is correctly unpacked and configured. + +=back + +=head2 Package selection states + +=over + +=item B<install> + +The package is selected for installation. + +=item B<hold> + +A package marked to be on B<hold> is kept on the same version, that is, +no automatic new installs, upgrades or removals will be performed on them, +unless these actions are requested explicitly, or are permitted to be done +automatically with the B<--force-hold> option. + +=item B<deinstall> + +The package is selected for deinstallation (i.e. we want to remove all +files, except configuration files). + +=item B<purge> + +The package is selected to be purged (i.e. we want to remove everything +from system directories, even configuration files). + +=item B<unknown> + +The package selection is unknown. +A package that is also in a B<not-installed> state, and with an +B<ok> flag will be forgotten in the next database store. + +=back + +=head2 Package flags + +=over + +=item B<ok> + +A package marked B<ok> is in a known state, but might need further +processing. + +=item B<reinstreq> + +A package marked B<reinstreq> is broken and requires +reinstallation. +These packages cannot be removed, unless forced with +option B<--force-remove-reinstreq>. + +=back + +=head1 ACTIONS + +=over + +=item B<-i>, B<--install> I<package-file>... + +Install the package. +If B<--recursive> or B<-R> option is +specified, I<package-file> must refer to a directory instead. + +Installation consists of the following steps: + +=over 4 + +=item B<1.> + +Extract the control files of the new package. + +=item B<2.> + +If another version of the same package was installed before +the new installation, execute I<prerm> script of the old package. + +=item B<3.> + +Run I<preinst> script, if provided by the package. + +=item B<4.> + +Unpack the new files, and at the same time back up the old +files, so that if something goes wrong, they can be restored. + +=item B<5.> + +If another version of the same package was installed before +the new installation, execute the I<postrm> script of the old +package. +Note that this script is executed after the I<preinst> +script of the new package, because new files are written at the same +time old files are removed. + +=item B<6.> + +Configure the package. +See B<--configure> for detailed +information about how this is done. + +=back + +=item B<--unpack> I<package-file>... + +Unpack the package, but don't configure it. +If B<--recursive> or +B<-R> option is specified, I<package-file> must refer to a +directory instead. + +Will process triggers for B<Pre-Depends> unless B<--no-triggers> has +been specified. + +=item B<--configure> I<package>...|B<-a>|B<--pending> + +Configure a package which has been unpacked but not yet configured. +If B<-a> or B<--pending> is given instead of I<package>, +all unpacked but unconfigured packages are configured. + +To reconfigure a package which has already been configured, try the +L<dpkg-reconfigure(8)> command instead (which is part of the B<debconf> +project). + +Configuring consists of the following steps: + +=over 4 + +=item B<1.> + +Unpack the conffiles, and at the same time back up +the old conffiles, so that they can be restored if +something goes wrong. + +=item B<2.> + +Run I<postinst> script, if provided by the package. + +=back + +Will process triggers unless B<--no-triggers> has been specified. + +=item B<--triggers-only> I<package>...|B<-a>|B<--pending> + +Processes only triggers (since dpkg 1.14.17). +All pending triggers will be processed. +If package +names are supplied only those packages' triggers will be processed, exactly +once each where necessary. +Use of this option may leave packages in the improper B<triggers-awaited> +and B<triggers-pending> states. +This +can be fixed later by running: B<dpkg --configure --pending>. + +=item B<-r>, B<--remove> I<package>...|B<-a>|B<--pending> + +Remove an installed package. +This removes everything except conffiles and other data cleaned up by +the I<postrm> script, +which may avoid having to reconfigure the package if it is reinstalled +later (conffiles are configuration files that are listed in the +I<DEBIAN/conffiles> control file). +If there is no I<DEBIAN/conffiles> control file nor I<DEBIAN/postrm> +script, this command is equivalent to calling B<--purge>. +If B<-a> or B<--pending> is given instead of a package name, +then all packages unpacked, but marked to be removed in file +I<%ADMINDIR%/status>, are removed. + +Removing of a package consists of the following steps: + +=over 4 + +=item B<1.> + +Run I<prerm> script. + +=item B<2.> + +Remove the installed files. + +=item B<3.> + +Run I<postrm> script. + +=back + +Will process triggers unless B<--no-triggers> has been specified. + +=item B<-P>, B<--purge> I<package>...|B<-a>|B<--pending> + +Purge an installed or already removed package. +This removes everything, +including conffiles, and anything else cleaned up from I<postrm>. +If B<-a> or B<--pending> is given instead of a package name, +then all packages unpacked or removed, but marked to be purged in file +I<%ADMINDIR%/status>, are purged. + +B<Note>: Some configuration files might be unknown to B<dpkg> because they +are created and handled separately through the configuration scripts. +In +that case, B<dpkg> won't remove them by itself, but the package's +I<postrm> script (which is called by B<dpkg>), has to take care of +their removal during purge. +Of course, this only applies to files in +system directories, not configuration files written to individual users' +home directories. + +Purging of a package consists of the following steps: + +=over 4 + +=item B<1.> + +Remove the package, if not already removed. +See B<--remove> +for detailed information about how this is done. + +=item B<2.> + +Run I<postrm> script. + +=back + +Will process triggers unless B<--no-triggers> has been specified. + +=item B<-V>, B<--verify> [I<package-name>...] + +Verifies the integrity of I<package-name> or all packages if omitted, +by comparing information from the files installed by a package with the +files metadata information stored in the B<dpkg> database +(since dpkg 1.17.2). +The origin +of the files metadata information in the database is the binary packages +themselves. +That metadata gets collected at package unpack time during +the installation process. + +Currently the only functional check performed is an md5sum verification +of the file contents against the stored value in the files database. +It will only get checked +if the database contains the file md5sum. +To check for any missing +metadata in the database, the B<--audit> command can be used. +This is only an integrity check and should not be considered as any +kind of security verification. + +The output format is selectable with the B<--verify-format> +option, which by default uses the B<rpm> format, but that might +change in the future, and as such, programs parsing this command +output should be explicit about the format they expect. + +=item B<-C>, B<--audit> [I<package-name>...] + +Performs database sanity and consistency checks for I<package-name> +or all packages if omitted (per package checks since dpkg 1.17.10). +For example, searches for packages that have been installed only partially +on your system or that have missing, wrong or obsolete control data or +files. +B<dpkg> will suggest what to do with them to get them fixed. + +=item B<--update-avail> [I<Packages-file>] + +=item B<--merge-avail> [I<Packages-file>] + +Update B<dpkg>'s and B<dselect>'s idea of which packages are +available. +With action B<--merge-avail>, +old information is combined with information from I<Packages-file>. +With action +B<--update-avail>, old information is replaced with the information +in the I<Packages-file>. +The I<Packages-file> distributed with Debian is simply named «I<Packages>». +If the I<Packages-file> +argument is missing or named «B<->» then it will be read from +standard input (since dpkg 1.17.7). +B<dpkg> keeps its record of +available packages in I<%ADMINDIR%/available>. + +A simpler one-shot command to retrieve and update the I<available> +file is B<dselect update>. +Note that this file is mostly useless +if you don't use B<dselect> but an APT-based frontend: APT has its +own system to keep track of available packages. + +=item B<-A>, B<--record-avail> I<package-file>... + +Update B<dpkg> and B<dselect>'s idea of which packages are +available with information from the package I<package-file>. +If +B<--recursive> or B<-R> option is specified, I<package-file> +must refer to a directory instead. + +=item B<--forget-old-unavail> + +Now B<obsolete> and a no-op as B<dpkg> will automatically forget +uninstalled unavailable packages (since dpkg 1.15.4), but only those that +do not contain user information such as package selections. + +=item B<--clear-avail> + +Erase the existing information about what packages are available. + +=item B<--get-selections> [I<package-name-pattern>...] + +Get list of package selections, and write it to stdout. +Without a pattern, +non-installed packages (i.e. those which have been previously purged) will +not be shown. + +=item B<--set-selections> + +Set package selections using file read from stdin. +This file should be +in the format “I<package> I<state>”, where state is one of +B<install>, B<hold>, B<deinstall> or B<purge>. +Blank lines +and comment lines beginning with ‘B<#>’ are also permitted. + +The I<available> file needs to be up-to-date for this command to be +useful, otherwise unknown packages will be ignored with a warning. +See +the B<--update-avail> and B<--merge-avail> commands for more +information. + +=item B<--clear-selections> + +Set the requested state of every non-essential package to deinstall +(since dpkg 1.13.18). +This is intended to be used immediately before B<--set-selections>, +to deinstall any packages not in list given to B<--set-selections>. + +=item B<--yet-to-unpack> + +Searches for packages selected for installation, but which for some +reason still haven't been installed. + +B<Note>: This command makes use of both the available file and the package +selections. + +=item B<--predep-package> + +Print a single package which is the target of one or more relevant +pre-dependencies and has itself no unsatisfied pre-dependencies. + +If such a package is present, output it as a Packages file entry, +which can be massaged as appropriate. + +B<Note>: This command makes use of both the available file and the package +selections. + +Returns 0 when a package is printed, 1 when no suitable package is +available and 2 on error. + +=item B<--add-architecture> I<architecture> + +Add I<architecture> to the list of architectures for which packages can +be installed without using B<--force-architecture> (since dpkg 1.16.2). +The architecture +B<dpkg> is built for (i.e. the output of B<--print-architecture>) +is always part of that list. + +=item B<--remove-architecture> I<architecture> + +Remove I<architecture> from the list of architectures for which packages +can be installed without using B<--force-architecture> +(since dpkg 1.16.2). +If the +architecture is currently in use in the database then the operation will +be refused, except if B<--force-architecture> is specified. +The +architecture B<dpkg> is built for (i.e. the output of +B<--print-architecture>) can never be removed from that list. + +=item B<--print-architecture> + +Print architecture of packages B<dpkg> installs (for example, “i386”). + +=item B<--print-foreign-architectures> + +Print a newline-separated list of the extra architectures B<dpkg> is +configured to allow packages to be installed for (since dpkg 1.16.2). + +=item B<--assert-help> + +Give help about the B<--assert->I<feature> options (since dpkg 1.21.0). + +=item B<--assert->I<feature> + +Asserts that B<dpkg> supports the requested feature. +Returns 0 if the feature is fully supported, 1 if the feature is known but +B<dpkg> cannot provide support for it yet, and 2 if the feature is unknown. +The current list of assertable features is: + +=over + +=item B<support-predepends> + +Supports the B<Pre-Depends> field (since dpkg 1.1.0). + +=item B<working-epoch> + +Supports epochs in version strings (since dpkg 1.4.0.7). + +=item B<long-filenames> + +Supports long filenames in L<deb(5)> archives (since dpkg 1.4.1.17). + +=item B<multi-conrep> + +Supports multiple B<Conflicts> and B<Replaces> (since dpkg 1.4.1.19). + +=item B<multi-arch> + +Supports multi-arch fields and semantics (since dpkg 1.16.2). + +=item B<versioned-provides> + +Supports versioned B<Provides> (since dpkg 1.17.11). + +=item B<protected-field> + +Supports the B<Protected> field (since dpkg 1.20.1). + +=back + +=item B<--validate->I<thing> I<string> + +Validate that the I<thing> I<string> has a correct syntax +(since dpkg 1.18.16). +Returns 0 if the I<string> is valid, 1 if the I<string> is invalid but +might be accepted in lax contexts, and 2 if the I<string> is invalid. +The current list of validatable I<thing>s is: + +=over + +=item B<pkgname> + +Validates the given package name (since dpkg 1.18.16). + +=item B<trigname> + +Validates the given trigger name (since dpkg 1.18.16). + +=item B<archname> + +Validates the given architecture name (since dpkg 1.18.16). + +=item B<version> + +Validates the given version (since dpkg 1.18.16). + +=back + +=item B<--compare-versions> I<ver1> I<op> I<ver2> + +Compare version numbers, where I<op> is a binary operator. +B<dpkg> +returns true (B<0>) if the specified condition is satisfied, +and false (B<1>) otherwise. +There are +two groups of operators, which differ in how they treat an empty +I<ver1> or I<ver2>. +These treat an empty version as earlier than any version: +B<lt le eq ne ge gt>. +These treat an empty version as later than any version: +B<lt-nl le-nl ge-nl gt-nl>. +These are provided +only for compatibility with control file syntax: B<E<lt> E<lt>E<lt> E<lt>= = E<gt>= E<gt>E<gt> +E<gt>>. +The B<E<lt>> and B<E<gt>> operators are obsolete and should B<not> +be used, due to confusing semantics. +To illustrate: B<0.1 E<lt> 0.1> +evaluates to true. + +=begin disabled + +=item B<--command-fd> I<n> + +Accept a series of commands on input file descriptor I<n>. + +B<Note>: Additional options set on the command line, and through this +file descriptor, are not reset for subsequent commands executed during the +same run. + +=end disabled + +=item B<-?>, B<--help> + +Display a brief help message. + +=item B<--force-help> + +Give help about the B<--force->I<thing> options. + +=item B<-Dh>, B<--debug=help> + +Give help about debugging options. + +=item B<--version> + +Display B<dpkg> version information. + +When used with B<--robot>, the output will be the program version number +in a dotted numerical format, with no newline. + +=item B<dpkg-deb actions> + +See L<dpkg-deb(1)> for more information about the following actions, +and other actions and options not exposed by the B<dpkg> front-end. + +=over + +=item B<-b>, B<--build> I<directory> [I<archive>|I<directory>] + +Build a deb package. + +=item B<-c>, B<--contents> I<archive> + +List contents of a deb package. + +=item B<-e>, B<--control> I<archive> [I<directory>] + +Extract control-information from a package. + +=item B<-x>, B<--extract> I<archive> I<directory> + +Extract the files contained by package. + +=item B<-X>, B<--vextract> I<archive> I<directory> + +Extract and display the filenames contained by a package. + +=item B<-f>, B<--field> I<archive> [I<control-field>...] + +Display control field(s) of a package. + +=item B<--ctrl-tarfile> I<archive> + +Output the control tar-file contained in a Debian package. + +=item B<--fsys-tarfile> I<archive> + +Output the filesystem tar-file contained by a Debian package. + +=item B<-I>, B<--info> I<archive> [I<control-file>...] + +Show information about a package. + +=back + +=item B<dpkg-query actions> + +See L<dpkg-query(1)> for more information about the following actions, +and other actions and options not exposed by the B<dpkg> front-end. + +=over + +=item B<-l>, B<--list> I<package-name-pattern>... + +List packages matching given pattern. + +=item B<-s>, B<--status> I<package-name>... + +Report status of specified package. + +=item B<-L>, B<--listfiles> I<package-name>... + +List files installed to your system from I<package-name>. + +=item B<-S>, B<--search> I<filename-search-pattern>... + +Search for a filename from installed packages. + +=item B<-p>, B<--print-avail> I<package-name>... + +Display details about I<package-name>, as found in +I<%ADMINDIR%/available>. +Users of APT-based frontends +should use B<apt show> I<package-name> instead. + +=back + +=back + +=head1 OPTIONS + +All options can be specified both on the command line and in the B<dpkg> +configuration file I<%PKGCONFDIR%/dpkg.cfg> or fragment files (with names +matching this shell pattern '[0-9a-zA-Z_-]*') on the configuration +directory I<%PKGCONFDIR%/dpkg.cfg.d/>. +Each line in the configuration +file is either an option (exactly the same as the command line option but +without leading hyphens) or a comment (if it starts with a ‘B<#>’). + +=over + +=item B<--abort-after=>I<number> + +Change after how many errors B<dpkg> will abort. +The default is 50. + +=item B<-B>, B<--auto-deconfigure> + +When a package is removed, there is a possibility that another +installed package depended on the removed package. +Specifying this +option will cause automatic deconfiguration of the package which +depended on the removed package. + +=item B<-D>I<octal>, B<--debug=>I<octal> + +Switch debugging on. +I<octal> is formed by bitwise-ORing desired +values together from the list below (note that these values may change +in future releases). +B<-Dh> or B<--debug=help> display these +debugging values. + + Number Description + 1 Generally helpful progress information + 2 Invocation and status of maintainer scripts + 10 Output for each file processed + 100 Lots of output for each file processed + 20 Output for each configuration file + 200 Lots of output for each configuration file + 40 Dependencies and conflicts + 400 Lots of dependencies/conflicts output + 10000 Trigger activation and processing + 20000 Lots of output regarding triggers + 40000 Silly amounts of output regarding triggers + 1000 Lots of drivel about for example the dpkg/info dir + 2000 Insane amounts of drivel + +=item B<--force->I<things> + +=item B<--no-force->I<things>, B<--refuse->I<things> + +Force or refuse (B<no-force> and B<refuse> mean the same thing) +to do some things. +I<things> is a comma separated list of things specified below. +B<--force-help> displays a message describing them. +Things marked with (*) are forced by default. + +B<Warning>: These options are mostly intended to be used by experts +only. +Using them without fully understanding their effects may break +your whole system. + +=over 2 + +=item B<all>: + +Turns on (or off) all force options. + +=item B<downgrade>(*): + +Install a package, even if newer version of it is already installed. + +B<Warning>: At present B<dpkg> does not do any dependency +checking on downgrades and therefore will not warn you +if the downgrade breaks the dependency of some other +package. +This can have serious side effects, downgrading +essential system components can even make your whole +system unusable. +Use with care. + +=item B<configure-any>: + +Configure also any unpacked but unconfigured packages on which the current +package depends. + +=item B<hold>: + +Allow automatic installs, upgrades or removals of packages even when marked +to be on “hold”. +B<Note>: When these actions are requested explicitly, the “hold” package +selection state always gets ignored. + +=item B<remove-reinstreq>: + +Remove a package, even if it's broken and marked to require +reinstallation. +This may, for example, cause parts of the package to +remain on the system, which will then be forgotten by B<dpkg>. + +=item B<remove-protected>: + +Remove, even if the package is considered protected (since dpkg 1.20.1). +Protected packages contain mostly important system boot infrastructure or +are used for custom system-local meta-packages. +Removing them might cause the whole system to be unable to boot or lose +required functionality to operate, so use with caution. + +=item B<remove-essential>: + +Remove, even if the package is considered essential. +Essential packages contain mostly very basic Unix commands, required for +the packaging system, for the operation of the system in general or during +boot (although the latter should be converted to protected packages instead). +Removing them might cause the whole system to stop working, +so use with caution. + +=item B<depends>: + +Turn all dependency problems into warnings. +This affects the B<Pre-Depends> and B<Depends> fields. + +=item B<depends-version>: + +Don't care about versions when checking dependencies. +This affects the B<Pre-Depends> and B<Depends> fields. + +=item B<breaks>: + +Install, even if this would break another package (since dpkg 1.14.6). +This affects the B<Breaks> field. + +=item B<conflicts>: + +Install, even if it conflicts with another package. +This is dangerous, +for it will usually cause overwriting of some files. +This affects the B<Conflicts> field. + +=item B<confmiss>: + +Always install the missing conffile without prompting. +This is dangerous, +since it means not preserving a change (removing) made to the file. + +=item B<confnew>: + +If a conffile has been modified and the version in the package did change, +always install the new version without prompting, unless the +B<--force-confdef> is also specified, in which case the default +action is preferred. + +=item B<confold>: + +If a conffile has been modified and the version in the package did change, +always keep the old version without prompting, unless the +B<--force-confdef> is also specified, in which case the default +action is preferred. + +=item B<confdef>: + +If a conffile has been modified and the version in the package did change, +always choose the default action without prompting. +If there is no default +action it will stop to ask the user unless B<--force-confnew> or +B<--force-confold> is also given, in which case it will use +that to decide the final action. + +=item B<confask>: + +If a conffile has been modified always offer to replace it with the +version in the package, even if the version in the package did not +change (since dpkg 1.15.8). +If any of B<--force-confnew>, +B<--force-confold>, or B<--force-confdef> is also given, +it will be used to decide the final action. + +=item B<overwrite>: + +Overwrite one package's file with another's file. + +=item B<overwrite-dir>: + +Overwrite one package's directory with another's file. + +=item B<overwrite-diverted>: + +Overwrite a diverted file with an undiverted version. + +=item B<statoverride-add>: + +Overwrite an existing stat override when adding it (since dpkg 1.19.5). + +=item B<statoverride-remove>: + +Ignore a missing stat override when removing it (since dpkg 1.19.5). + +=item B<security-mac>(*): + +Use platform-specific Mandatory Access Controls (MAC) based security when +installing files into the filesystem (since dpkg 1.19.5). +On Linux systems the implementation uses SELinux. + +=item B<unsafe-io>: + +Do not perform safe I/O operations when unpacking (since dpkg 1.15.8.6). +Currently this +implies not performing file system syncs before file renames, which is +known to cause substantial performance degradation on some file systems, +unfortunately the ones that require the safe I/O on the first place due +to their unreliable behaviour causing zero-length files on abrupt +system crashes. + +I<Note>: For ext4, the main offender, consider using instead the +mount option B<nodelalloc>, which will fix both the performance +degradation and the data safety issues, the latter by making the file +system not produce zero-length files on abrupt system crashes with +any software not doing syncs before atomic renames. + +B<Warning>: Using this option might improve performance at the cost of +losing data, use with care. + +=item B<script-chrootless>: + +Run maintainer scripts without L<chroot(2)>ing into B<instdir> even +if the package does not support this mode of operation (since dpkg 1.18.5). + +B<Warning>: This can destroy your host system, use with extreme care. + +=item B<architecture>: + +Process even packages with wrong or no architecture. + +=item B<bad-version>: + +Process even packages with wrong versions (since dpkg 1.16.1). + +=item B<bad-path>: + +B<PATH> is missing important programs, so problems are likely. + +=item B<not-root>: + +Try to (de)install things even when not root. + +=item B<bad-verify>: + +Install a package even if it fails authenticity check. + +=back + +=item B<--ignore-depends>=I<package>,... + +Ignore dependency-checking for specified packages (actually, checking is +performed, but only warnings about conflicts are given, nothing else). +This affects the B<Pre-Depends>, B<Depends> and B<Breaks> fields. + +=item B<--no-act>, B<--dry-run>, B<--simulate> + +Do everything which is supposed to be done, but don't write any +changes. +This is used to see what would happen with the specified +action, without actually modifying anything. + +Be sure to give B<--no-act> before the action-parameter, or you might +end up with undesirable results (e.g. B<dpkg --purge foo --no-act> will +first purge package “foo” and then try to purge package ”--no-act”, even +though you probably expected it to actually do nothing). + +=item B<-R>, B<--recursive> + +Recursively handle all regular files matching pattern B<*.deb> +found at specified directories and all of its subdirectories. +This can +be used with B<-i>, B<-A>, B<--install>, B<--unpack> and +B<--record-avail> actions. + +=item B<-G> + +Don't install a package if a newer version of the same package is already +installed. +This is an alias of B<--refuse-downgrade>. + +=item B<--admindir=>I<dir> + +Set the administrative directory to I<directory>. +This directory contains many files that give information about status of +installed or uninstalled packages, etc. +Defaults to «I<%ADMINDIR%>» if B<DPKG_ADMINDIR> has not been set. + +=item B<--instdir=>I<dir> + +Set the installation directory, which refers to the directory where +packages are to be installed. +B<instdir> is also the directory passed +to L<chroot(2)> before running package's installation scripts, which +means that the scripts see B<instdir> as a root directory. +Defaults to «I</>». + +=item B<--root=>I<dir> + +Set the root directory to B<directory>, which sets the installation +directory to «I<dir>» and the administrative +directory to «I<dir>B<%ADMINDIR%>». + +=item B<-O>, B<--selected-only> + +Only process the packages that are selected for installation. +The +actual marking is done with B<dselect> or by B<dpkg>, when it +handles packages. +For example, when a package is removed, it will +be marked selected for deinstallation. + +=item B<-E>, B<--skip-same-version> + +Don't install the package if the same version and architecture +of the package is already installed. + +Since dpkg 1.21.10, the architecture is also taken into account, +which makes it possible to cross-grade packages or install additional +co-installable instances with the same version, but different architecture. + +=item B<--pre-invoke=>I<command> + +=item B<--post-invoke=>I<command> + +Set an invoke hook I<command> to be run via “%DPKG_DEFAULT_SHELL% -c” before or +after the B<dpkg> run for the I<unpack>, I<configure>, I<install>, +I<triggers-only>, +I<remove> and +I<purge> +actions (since dpkg 1.15.4), and +I<add-architecture> and +I<remove-architecture> +actions (since dpkg 1.17.19). +This +option can be specified multiple times. +The order the options are specified +is preserved, with the ones from the configuration files taking precedence. +The environment variable B<DPKG_HOOK_ACTION> is set for the hooks to the +current B<dpkg> action. + +B<Note>: Front-ends might call B<dpkg> several +times per invocation, which might run the hooks more times than expected. + +=item B<--path-exclude=>I<glob-pattern> + +=item B<--path-include=>I<glob-pattern> + +Set I<glob-pattern> as a path filter, either by excluding or re-including +previously excluded paths matching the specified patterns during install +(since dpkg 1.15.8). + +B<Warning>: Take into account that depending on the excluded paths you +might completely break your system, use with caution. + +The glob patterns use the same wildcards used in the shell, were +‘*’ matches any sequence of characters, including the empty string +and also ‘/’. +For example, «I</usr/*/READ*>» matches +«I</usr/share/doc/package/README>». +As usual, ‘?’ matches any single character (again, including ‘/’). +And ‘[’ +starts a character class, which can contain a list of characters, ranges +and complementations. +See L<glob(7)> for detailed information about +globbing. +B<Note>: The current implementation might re-include more directories +and symlinks than needed, in particular when there is a more specific +re-inclusion, to be on the safe side and avoid possible unpack failures; +future work might fix this. + +This can be used to remove all paths except some particular ones; a typical +case is: + + --path-exclude=/usr/share/doc/* + --path-include=/usr/share/doc/*/copyright + +to remove all documentation files except the copyright files. + +These two options can be specified multiple times, and interleaved with +each other. +Both are processed in the given order, with the last rule that +matches a file name making the decision. + +The filters are applied when unpacking the binary packages, and as such +only have knowledge of the type of object currently being filtered +(e.g. a normal file or a directory) and have not visibility of what +objects will come next. +Because these filters have side effects (in contrast to L<find(1)> +filters), excluding an exact pathname that happens to be a directory object +like I</usr/share/doc> will not have the desired result, and only that +pathname will be excluded (which could be automatically reincluded if the +code sees the need). +Any subsequent files contained within that directory will fail to unpack. + +B<Hint>: make sure the globs are not expanded by your shell. + +=item B<--verify-format> I<format-name> + +Sets the output format for the B<--verify> command (since dpkg 1.17.2). + +The only currently supported output format is B<rpm>, which consists +of a line for every path that failed any check. +These lines have the following format: + +Z<> + B<missing > [B<c>] I<pathname> [B<(>I<error-message>B<)>] + B<??5??????> [B<c>] I<pathname> + +The first 9 characters are used to report the checks result, +either a literal B<missing> when the file is not present or its metadata +cannot be fetched, +or one of the following special characters that report the result for each +check: + +=over + +=item ‘B<?>’ + +Implies the check could not be done (lack of support, file permissions, etc). + +=item ‘B<.>’ + +Implies the check passed. + +=item ‘I<A-Za-z0-9>’ + +Implies a specific check failed. +The following positions and alphanumeric characters are currently supported: + +=over + +=item 1 ‘B<?>’ + +These checks are currently not supported, will always be ‘B<?>’. + +=item 2 ‘B<M>’ + +The file mode check failed (since dpkg 1.21.0). +Because pathname metadata is currently not tracked, this check can only be +partially emulated via a very simple heuristic for pathnames that have a +known digest, which implies they should be regular files, where the check +will fail if the pathname is not a regular file on the filesystem. +This check will currently never succeed as it does not have enough +information available. + +=item 3 ‘B<5>’ + +The digest check failed, which means the file contents have changed. +This is only an integrity check and should not be considered as any +kind of security verification. + +=item 4-9 ‘B<?>’ + +These checks are currently not supported, will always be ‘B<?>’. + +=back + +=back + +The line is followed by a space and an attribute character. +The following attribute character is supported: + +=over + +=item ‘B<c>’ + +The pathname is a conffile. + +=back + +Finally followed by another space and the pathname. + +In case the entry was of the B<missing> type, and the file was not actually +present on the filesystem, then the line is followed by a space and the +error message enclosed within parenthesis. + +=item B<--status-fd> I<n> + +Send machine-readable package status and progress information to file +descriptor I<n>. +This option can be specified multiple times. +The +information is generally one record per line, in one of the following +forms: + +=over + +=item B<status:> I<package>B<:> I<status> + +Package status changed; I<status> is as in the status file. + +=item B<status:> I<package> B<: error :> I<extended-error-message> + +An error occurred. +Any possible newlines in I<extended-error-message> +will be converted to spaces before output. + +=item B<status:> I<file> B<: conffile-prompt : '>I<real-old>B<' '>I<real-new>B<'> I<useredited> I<distedited> + +User is being asked a conffile question. + +=item B<processing:> I<stage>B<:> I<package> + +Sent just before a processing stage starts. +I<stage> is one of +B<upgrade>, B<install> (both sent before unpacking), +B<configure>, B<trigproc>, B<disappear>, B<remove>, B<purge>. + +=back + +=item B<--status-logger>=I<command> + +Send machine-readable package status and progress information to the +shell I<command>'s standard input, to be run via “%DPKG_DEFAULT_SHELL% -c” +(since dpkg 1.16.0). +This option can be specified multiple times. +The output format used is the same as in B<--status-fd>. + +=item B<--log=>I<filename> + +Log status change updates and actions to I<filename>, instead of +the default I<%LOGDIR%/dpkg.log>. +If this option is given multiple times, the last filename is used. +Log messages are of the form: + +=over + +=item YYYY-MM-DD HH:MM:SS B<startup> I<type> I<command> + +For each dpkg invocation where I<type> is B<archives> (with a +I<command> of B<unpack> or B<install>) or B<packages> +(with a I<command> of B<configure>, B<triggers-only>, +B<remove> or B<purge>). + +=item YYYY-MM-DD HH:MM:SS B<status> I<state> I<pkg> I<installed-version> + +For status change updates. + +=item YYYY-MM-DD HH:MM:SS I<action> I<pkg> I<installed-version> I<available-version> + +For actions where I<action> is one of B<install>, B<upgrade>, +B<configure>, B<trigproc>, B<disappear>, B<remove> or B<purge>. + +=item YYYY-MM-DD HH:MM:SS B<conffile> I<filename> I<decision> + +For conffile changes where I<decision> is either B<install> or +B<keep>. + +=back + +=item B<--robot> + +Use a machine-readable output format. +This provides an interface for programs +that need to parse the output of some of the commands that do not otherwise +emit a machine-readable output format. +No localization will be used, and the +output will be modified to make it easier to parse. + +The only currently supported command is B<--version>. + +=item B<--no-pager> + +Disables the use of any pager when showing information (since dpkg 1.19.2). + +=item B<--no-debsig> + +Do not try to verify package signatures. + +=item B<--no-triggers> + +Do not run any triggers in this run (since dpkg 1.14.17), but activations +will still be recorded. +If used with B<--configure> I<package> or +B<--triggers-only> I<package> then the named package postinst +will still be run even if only a triggers run is needed. +Use of this option +may leave packages in the improper B<triggers-awaited> and +B<triggers-pending> states. +This can be fixed later by running: +B<dpkg --configure --pending>. + +=item B<--triggers> + +Cancels a previous B<--no-triggers> (since dpkg 1.14.17). + +=back + +=head1 EXIT STATUS + +=over + +=item B<0> + +The requested action was successfully performed. +Or a check or assertion command returned true. + +=item B<1> + +A check or assertion command returned false. + +=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 + +=head2 External environment + +=over + +=item B<PATH> + +This variable is expected to be defined in the environment and point to +the system paths where several required programs are to be found. +If it's +not set or the programs are not found, B<dpkg> will abort. + +=item B<HOME> + +If set, B<dpkg> will use it as the directory from which to read the user +specific configuration file. + +=item B<TMPDIR> + +If set, B<dpkg> will use it as the directory in which to create +temporary files and directories. + +=item B<SHELL> + +The program B<dpkg> will execute when starting a new interactive shell, +or when spawning a command via a shell. + +=item B<PAGER> + +=item B<DPKG_PAGER> + +The program B<dpkg> will execute when running a pager, +which will be executed with «B<$SHELL -c>», +for example when displaying the conffile differences. +If B<SHELL> is not set, «B<%DPKG_DEFAULT_SHELL%>» will be used instead. +The B<DPKG_PAGER> overrides the B<PAGER> environment variable +(since dpkg 1.19.2). + +=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_DEBUG> + +Sets the debug mask (since dpkg 1.21.10) from an octal value. +The currently accepted flags are described in the B<--debug> option. + +=item B<DPKG_FORCE> + +Sets the force flags (since dpkg 1.19.5). +When this variable is present, no built-in force defaults will be applied. +If the variable is present but empty, all force flags will be disabled. + +=item B<DPKG_ADMINDIR> + +If set and the B<--admindir> or B<--root> options have not been +specified, it will be used as the B<dpkg> administrative directory +(since dpkg 1.20.0). + +=item B<DPKG_FRONTEND_LOCKED> + +Set by a package manager frontend to notify dpkg that it should not acquire +the frontend lock (since dpkg 1.19.1). + +=back + +=head2 Internal environment + +=over + +=item B<LESS> + +Defined by B<dpkg> to “B<-FRSXMQ>”, if not already set, when +spawning a pager (since dpkg 1.19.2). +To change the default behavior, this variable can be preset to some other +value including an empty string, or the B<PAGER> or B<DPKG_PAGER> +variables can be set to disable specific options with «B<-+>», for +example B<DPKG_PAGER="less -+F">. + +=item B<DPKG_ROOT> + +Defined by B<dpkg> on the maintainer script environment to indicate +which installation to act on (since dpkg 1.18.5). +The value is intended to be prepended to any path maintainer scripts +operate on. +During normal operation, this variable is empty. +When installing packages into a different B<instdir>, B<dpkg> +normally invokes maintainer scripts using L<chroot(2)> and leaves +this variable empty, but if B<--force-script-chrootless> is +specified then the L<chroot(2)> call is skipped and B<instdir> +is non-empty. + +=item B<DPKG_ADMINDIR> + +Defined by B<dpkg> on the maintainer script environment to indicate +the B<dpkg> administrative directory to use (since dpkg 1.16.0). +This variable is always set to the current B<--admindir> value. + +=item B<DPKG_FORCE> + +Defined by B<dpkg> on the subprocesses environment to all the currently +enabled force option names separated by commas (since dpkg 1.19.5). + +=item B<DPKG_SHELL_REASON> + +Defined by B<dpkg> on the shell spawned on the conffile prompt to +examine the situation (since dpkg 1.15.6). +Current valid value: B<conffile-prompt>. + +=item B<DPKG_CONFFILE_OLD> + +Defined by B<dpkg> on the shell spawned on the conffile prompt to +examine the situation (since dpkg 1.15.6). +Contains the path to the old conffile. + +=item B<DPKG_CONFFILE_NEW> + +Defined by B<dpkg> on the shell spawned on the conffile prompt to +examine the situation (since dpkg 1.15.6). +Contains the path to the new conffile. + +=item B<DPKG_HOOK_ACTION> + +Defined by B<dpkg> on the shell spawned when executing a hook action +(since dpkg 1.15.4). +Contains the current B<dpkg> action. + +=item B<DPKG_RUNNING_VERSION> + +Defined by B<dpkg> on the maintainer script environment to the +version of the currently running B<dpkg> instance (since dpkg 1.14.17). + +=item B<DPKG_MAINTSCRIPT_PACKAGE> + +Defined by B<dpkg> on the maintainer script environment to the +(non-arch-qualified) package name being handled (since dpkg 1.14.17). + +=item B<DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT> + +Defined by B<dpkg> on the maintainer script environment to the +package reference count, i.e. the number of package instances with +a state greater than B<not-installed> (since dpkg 1.17.2). + +=item B<DPKG_MAINTSCRIPT_ARCH> + +Defined by B<dpkg> on the maintainer script environment to the +architecture the package got built for (since dpkg 1.15.4). + +=item B<DPKG_MAINTSCRIPT_NAME> + +Defined by B<dpkg> on the maintainer script environment to the +name of the script running, one of B<preinst>, B<postinst>, +B<prerm> or B<postrm> (since dpkg 1.15.7). + +=item B<DPKG_MAINTSCRIPT_DEBUG> + +Defined by B<dpkg> on the maintainer script environment to a value +(‘B<0>’ or ‘B<1>’) noting whether debugging has been +requested (with the B<--debug> option) for the maintainer scripts +(since dpkg 1.18.4). + +=back + +=head1 FILES + +=over + +=item I<%PKGCONFDIR%/dpkg.cfg.d/[0-9a-zA-Z_-]*> + +Configuration fragment files (since dpkg 1.15.4). + +=item I<%PKGCONFDIR%/dpkg.cfg> + +Configuration file with default options. + +=item I<%LOGDIR%/dpkg.log> + +Default log file (see I<%PKGCONFDIR%/dpkg.cfg> and option +B<--log>). + +=back + +The other files listed below are in their default directories, see option +B<--admindir> to see how to change locations of these files. + +=over + +=item I<%ADMINDIR%/available> + +List of available packages. + +=item I<%ADMINDIR%/status> + +Statuses of available packages. +This file contains information about +whether a package is marked for removing or not, whether it is +installed or not, etc. +See section L</INFORMATION ABOUT PACKAGES> +for more info. + +The status file is backed up daily in I<%BACKUPSDIR%>. +It can be +useful if it's lost or corrupted due to filesystems troubles. + +=back + +The format and contents of a binary package are described in L<deb(5)>. + +=head2 Filesystem filenames + +During unpacking and configuration B<dpkg> uses various filenames for +backup and rollback purposes. +The following is a simplified explanation of how these filenames get used +during package installation. + +=over + +=item F<*.dpkg-new> + +During unpack, B<dpkg> extracts new filesystem objects into +I<pathname>B<.dpkg-new> +(except for existing directories or symlinks to directories which get skipped), +once that is done and after having performed backups of the old objects, +the objects get renamed to I<pathname>. + +=item F<*.dpkg-tmp> + +During unpack, B<dpkg> makes backups of the old filesystem objects into +I<pathname>B<.dpkg-tmp> after extracting the new objects. +These backups are performed as either a rename for directories +(but only if they switch file type), +a new symlink copy for symlinks, +or a hard link for any other filesystem object, +except for conffiles which get no backups because they are processed +at a later stage. + +In case of needing to rollback, these backups get used to restore the +previous contents of the objects. +These get removed automatically after the installation is complete. + +=item F<*.dpkg-old> + +During configuration, when installing a new version, +B<dpkg> can make a backup of the previous modified conffile into +I<pathname>B<.dpkg-old>. + +=item F<*.dpkg-dist> + +During configuration, when keeping the old version, +B<dpkg> can make a backup of the new unmodified conffile into +I<pathname>B<.dpkg-dist>. + +=back + +=head1 SECURITY + +Any operation that needs write access to the database or the filesystem +is considered a privileged operation that might allow root escalation. +These operations must never be delegated to an untrusted user or be done +on untrusted packages, as that might allow root access to the system. + +Some operations (such as package verification) might need root privileges +to be able to access files on the filesystem that would otherwise be +inaccessible due to restricted permissions, but should otherwise work +normally and produce appropriate messages in those cases. + +Query operations should never require root, and delegating their execution +to unprivileged users via some gain-root command can have security +implications (such as privilege escalation), for example when a pager is +automatically invoked by the tool. + +See also the B<SECURITY> section of the L<dpkg-deb(1)> and L<dpkg-split(1)> +manual pages. + +=head1 BUGS + +B<--no-act> usually gives less information than might be helpful. + +=head1 EXAMPLES + +To list installed packages related to the editor L<vi(1)> (note that +B<dpkg-query> does not load the I<available> file anymore by +default, and the B<dpkg-query> B<--load-avail> option should +be used instead for that): + +=over + + dpkg -l '*vi*' + +=back + +To see the entries in I<%ADMINDIR%/available> of two packages: + +=over + + dpkg --print-avail vim neovim | less + +=back + +To search the listing of packages yourself: + +=over + + dpkg --print-avail | less + +=back + +To remove an installed neovim package: + +=over + + dpkg -r neovim + +=back + +To install a package, you first need to find it in an archive or media disc. +When using an archive based on a pool structure, +knowing the archive area and the name of the package is enough to infer +the pathname: + +=over + + dpkg -i /media/bdrom/pool/main/v/vim/vim_9.0.2018-1_amd64.deb + +=back + +To make a local copy of the package selection states: + +=over + + dpkg --get-selections >myselections + +=back + +You might transfer this file to another computer, and after having updated +the I<available> file there with your package manager frontend of choice +(see L<https://wiki.debian.org/Teams/Dpkg/FAQ#set-selections> for more +details), for example: + +=over + + apt-cache dumpavail | dpkg --merge-avail + +=back + +you can install it with: + +=over + + dpkg --clear-selections + dpkg --set-selections <myselections + +=back + +Note that this will not actually install or remove anything, but just +set the selection state on the requested packages. +You will need some +other application to actually download and install the requested +packages. +For example, run B<apt-get dselect-upgrade>. + +Ordinarily, you will find that L<dselect(1)> provides a more +convenient way to modify the package selection states. + +=head1 ADDITIONAL FUNCTIONALITY + +Additional functionality can be gained by installing any of the +following packages: B<apt>, B<aptitude> and B<debsig-verify>. + +=head1 SEE ALSO + +L<aptitude(8)>, +L<apt(8)>, +L<dselect(1)>, +L<dpkg-deb(1)>, +L<dpkg-query(1)>, +L<deb(5)>, +L<deb-control(5)>, +L<dpkg.cfg(5)>, +and +L<dpkg-reconfigure(8)>. + +=head1 AUTHORS + +See I<%PKGDOCDIR%/THANKS> for the list of people who have +contributed to B<dpkg>. |