.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "dpkg-www 8"
.TH dpkg-www 8 "2023-08-24" "2.65" "Debian Project"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dpkg\-www, dpkg\-www\-installer \- WWW Debian package browser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
https://<hostname>/cgi\-bin/dpkg
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A typical Debian system can have hundreds installed packages and thousands
available for installation. Information about installed and available
packages can usually be obtained with the \fBdpkg\fR(1)
command, but navigating through the package dependencies and the
documentation files can be a very frustrating and time-consuming task.
.PP
With the \fBdpkg-www\fR
\&\s-1CGI\s0 you can instead browse Debian packages info with a web browser,
following package dependencies and locating documentation (man pages,
Info files, READMEs, and so on) with few mouse clicks. If you have
superuser privileges you can even install, upgrade or remove packages
from your web browser.
The output provided by \fBdpkg-www\fR is basically that of \fBdpkg\fR(1)
with the addition of \s-1HREF\s0's for packages dependencies and documentation
files.
.PP
The \s-1CGI\s0 program can take an optional query argument which can be given in
the \s-1URL\s0 or entered in the query field of the \s-1HTML\s0 form. This can be:
.IP "\fIempty\fR" 4
.IX Item "empty"
List concisely all installed packages.
.IP "\fB*\fR (asterisk)" 4
.IX Item "* (asterisk)"
List concisely all installed and available packages.
.IP "\fIlist of packages\fR" 4
.IX Item "list of packages"
List concisely the requested packages.
.IP "\fIwildcard expession\fR" 4
.IX Item "wildcard expession"
List concisely all packages whose name matches the expression, for
example '*image*' will find all packages which contain the string 'image'.
.IP "\fIpackage\fR" 4
.IX Item "package"
List verbosely a package and, if the package is installed, all its files.
If the package is not installed and the web installation is enabled you
can install it by clicking on the 'Install' button. If the package is
installed you can remove it or upgrade to a new version, if available,
by clicking on the respective buttons.
.IP "\fIabsolute pathname\fR" 4
.IX Item "absolute pathname"
List all the packages owners of a file. This can be used for example to find
which package installed a program.
.IP "\fB/\fR\fIregexp\fR" 4
.IX Item "/regexp"
List all the packages owners of a file. The regexp form can be used to find
which packages own a non installed file.
.IP "\fIfield\fR\fB=\fR\fIvalue\fR" 4
.IX Item "field=value"
List all the packages with control field matching value. If the field name is
omitted the value is searched in any control field. The default search is a
case-insensitive fixed substring match but it can be changed with the
\&\fB\s-1GREP_DCTRL_OPTS\s0\fR option in the config file.
This feature works only if the \fBgrep-dctrl\fR(1) package is installed.
.IP "\fB?\fR (question mark)" 4
.IX Item "? (question mark)"
Show a concise help about the \s-1CGI\s0 usage.
.IP "\fIspace\fR (a single space)" 4
.IX Item "space (a single space)"
Print only the input form, for use from window-manager menus.
.SS "Configuration"
.IX Subsection "Configuration"
\&\fBdpkg-www\fR can be configured by the local system administrator via the
optional \fI/etc/dpkg\-www.conf\fR file.
This file is a simple Bourne shell (\fI/bin/sh\fR)
script that defines some or all the following variables
(defaults are used if the file doesn't exist, or doesn't define the variable):
.IP "\fB\s-1CHECK_BUTTONS\s0\fR" 4
.IX Item "CHECK_BUTTONS"
If this option is enabled \fBdpkw-www\fR
will add a small 'install' check-button for each package shown in the package
list. Default is 0 (disabled) because the resulting interface is not very nice.
The use of this option is therefore not recommended.
.IP "\fB\s-1INSTALL_BUTTON\s0\fR" 4
.IX Item "INSTALL_BUTTON"
If this option is set the 'Install' or 'Upgrade' and 'Remove' buttons will
be added to the verbose info of a package. By clicking on these button you
will start the installation of removal the package as described in the section
\&\fBWeb Installation\fR.
Since this option can potentially introduce security holes it is disabled (0)
by default. Use at your own risk.
If the variable is set to \*(L"top\*(R" the button will be located before the file
list, default is the bottom of the page.
.IP "\fB\s-1SHOW_LOCAL_FILES\s0\fR" 4
.IX Item "SHOW_LOCAL_FILES"
If this variable is set, \fBdpkg-www\fR will use file:/ style \s-1URL\s0's to
access html files \*(-- bypassing the \s-1CGI\s0 script. This is faster
on slow machines. Default is not defined, which means use local files
for connection from localhost and https:// \s-1URL\s0's for remote connections.
.IP "\fB\s-1CHECK_PACKAGE_VERSION\s0\fR" 4
.IX Item "CHECK_PACKAGE_VERSION"
If this variable is set, \fBdpkg-www\fR will check if a newer version
of an installed package is available.
On slow machines you may want to set this option to
false since it can considerably slow down the execution.
.IP "\fB\s-1LIST_UNAVAILABLE\s0\fR" 4
.IX Item "LIST_UNAVAILABLE"
This option enables listing also unavailable packages in the packages list.
Disabled by default.
.IP "\fB\s-1LIST_DOCUMENTATION\s0\fR" 4
.IX Item "LIST_DOCUMENTATION"
This option enables the display of references to documents registered with
\&\fBinstall-docs\fR(8)
to the detailed package info, providing a quick path to relevant package
documentation. Unfortunately this feature is not totally reliable because
currently there is no way to find documents registered by a package with
\&\fBinstall-docs\fR(8)
and the search is done with an ugly hack. Hopefully things will change in
woody. This option is enabled (1) by default.
.IP "\fB\s-1FORCE_SSH_PASSWD\s0\fR" 4
.IX Item "FORCE_SSH_PASSWD"
This option forces ssh passwd prompt for package installation on a remote host
even if an ssh agent holds the private key.
.IP "\fB\s-1GREP_DCTRL_OPTS\s0\fR" 4
.IX Item "GREP_DCTRL_OPTS"
These options are passed to \fBgrep-dctrl\fR(1)
when doing a query by field. Default is \*(L"\-i\*(R" for case-insensitive fixed
substring match. See \fBgrep-dctrl\fR(1) for more info.
.IP "\fB\s-1DPKG\s0\fR" 4
.IX Item "DPKG"
Command providing the \fBdpkg\fR(1) query functionalities. This can be
\&\fBdpkg\fR(1) or \fBdlocate\fR(1), or \fBauto\fR.
Default is \fBauto\fR, meaning that the \s-1CGI\s0 will use \fBdlocate\fR(1)
if installed, otherwise revert to \fBdpkg\fR(1)
which should always be available on a Debian system. By specifying this
option you can force the use of one of the two program.
.IP "\fB\s-1MAN\s0\fR" 4
.IX Item "MAN"
Man page to \s-1HTML\s0 translation command. Can be \fBdwww\fR(7), \fBman2html\fR
or \fBauto\fR.
Default is \fBauto\fR, meaning that the \s-1CGI\s0 will use \fBman2thml\fR
if installed, otherwise revert to \fBdwww\fR(7).
By specifying this option you can force the use of one of the two program.
.IP "\fB\s-1DEBIAN_CONTENTS\s0\fR" 4
.IX Item "DEBIAN_CONTENTS"
Optional list of one or more \fIContents\-xxx.gz\fR
files mapping each file available in the Debian system to
the package from which it originates. If available these files are used
to find the owner packages of non installed files. This can be useful for
quickly finding the package to install when a needed command is missing.
.IP "\fB\s-1BGCOLOR\s0\fR" 4
.IX Item "BGCOLOR"
Background color of the \s-1HTML\s0 body.
.IP "\fB\s-1DEBUG\s0\fR" 4
.IX Item "DEBUG"
Internal option used only for debugging. Disabled by default since it is
useless for normal users.
.IP "\fB\s-1DWWW_PATH\s0\fR" 4
.IX Item "DWWW_PATH"
Path on web server to \fBdwww\fR(7) cgi-bin.
.IP "\fB\s-1INFO2WWW_PATH\s0\fR" 4
.IX Item "INFO2WWW_PATH"
Path on web server to \fBinfo2www\fR(1) cgi-bin.
.PP
The following is an example \fI/etc/dpkg\-www.conf\fR file:
.PP
.Vb 2
\&  # Enable install check\-buttons in package list.
\&  CHECK_BUTTONS=0
\&
\&  # Enable install, upgrade and remove buttons in package info.
\&  INSTALL_BUTTON=1
\&
\&  # List registered package documentation.
\&  LIST_DOCUMENTATION=1
\&
\&  # Options passed to grep\-dctrl in queryPackagesByField()
\&  GREP_DCTRL_OPTS="\-i"
\&
\&  # Show local files directly. Automatically set.
\&  SHOW_LOCAL_FILES=auto
\&
\&  # Force ssh passwd prompt even if an ssh agent holds
\&  # the private key.
\&  FORCE_SSH_PASSWD=true
\&
\&  # List of Contents\-xxx.gz files, if available.
\&  DEBIAN_CONTENTS="
\&    /debian/dists/bookworm/main/Contents\-amd64.gz
\&    /debian/dists/bookworm\-updates/main/Contents\-amd64.gz
\&    /debian\-security/dists/bookworm\-security/main/Contents\-amd64.gz"
\&
\&  # Dpkg command (dpkg|dlocate|auto). Automatically detected.
\&  # DPKG=auto
\&
\&  # Manpage conversion command (dwww|man2html|auto). Automatically detected.
\&  # MAN=auto
\&
\&  # HTML background color.
\&  # BGCOLOR="#c0c0c0"
\&
\&  # Enable CGI debugging. Not really useful.
\&  # DEBUG=1
.Ve
.SS "\s-1CGI\s0 access"
.IX Subsection "CGI access"
The information provided by \fBdpkg-www\fR
and the ability to install or remove packages also remotely can potentially
give useful information to crackers and open security holes. For these reasons
access to this \s-1CGI\s0 program should be allowed only from localhost and trusted
hosts or domains. Unfortunately this configuration is dependent on the
particular installed web server.
The \fBdpkg-www\fR package configures the \fBapache\fR
server, if installed, to allow access only from localhost. Other web servers
must be configured manually by the system administrator to restrict access
to trusted hosts. If you administer many Debian system on a local network
you may want to enable access to the \s-1CGI\s0 from your network and browse
packages on any host from any other machine.
.SS "Web installation"
.IX Subsection "Web installation"
If this option is enabled in the \fI/etc/dpkg\-www.conf\fR
file, the 'Install', 'Upgrade' and 'Remove' buttons are added to the info
page of installed or uninstalled packages.
By clicking on this button the system administrator, or more precisely any
user who has the ability to become system administrator (since you don't
want to run a web browser as root!), will be able to install or remove a
package on the fly, provided he has properly configured his browser for web
installation.
.PP
For security reasons the installation is done entirely from the browser side,
so that you don't need to gain root privileges from the \s-1CGI\s0 program which is
run on the server. The only thing done on the server is to generate an
installation request which is downloaded to the browser for the execution,
which is started under control of the user and with his privileges.
The real installation is done by a small helper script run from the user's
browser when a document with content-type 'application/dpkg\-www\-installer'
is received from the web server. The helper script opens an XTerm on the
user's display and runs a script which becomes superuser, after asking the
root password, and execs an \fBapt-get\fR(8) command to install the requested
packages.
.PP
The web browser must have been configured to handle the above content-type
by running the command "\fB/usr/sbin/dpkg\-www\-installer \-x \-f '%s'\fR",
which must obviously be installed also on the client side if installing
remotely.
If the \fBdpkg-www\fR
package is not installed on the browser client you can simply
copy the script \fI/usr/sbin/dpkg\-www\-installer\fR and hope it works...
.PP
You can configure your \fBFirefox\fR
browser from the General \-> Application menu of the Preferences window.
You must add a new item with \s-1MIME\s0 type
"\fBapplication/dpkg\-www\-installer\fR\*(L"
and application \*(R"\fB/usr/sbin/dpkg\-www\-installer \-x \-f '%s'\fR".
This should add the following line to your Firefox mailcap file:
.PP
.Vb 1
\& application/dpkg\-www\-installer;/usr/sbin/dpkg\-www\-installer \-x \-f \*(Aq%s\*(Aq
.Ve
.PP
The \fBdpkg-www\fR web installation has been successfully tested only with
\&\fBFirefox\fR.
With other web browsers it is untested and it may not work correctly.
.PP
In order to be able to install the packages the user must known the root
password asked for '\fBsu root\fR' when installing on the local server,
or have the ability to ssh as root to the remote host when installing
from a remote client.
.PP
From the security point of view, executing a web installation is functionally
equivalent to opening a shell in an XTerm, becoming superuser after having
supplied the proper password and running \fBapt-get\fR(8) as root to install
or remove the required packages.
Starting this from the web could be potentially vulnerable to
man-in-the-middle (\s-1MITM\s0) attacks, but since it requires a password on the
client it seems quite safe.
If you are really paranoid connect to a secure server from an SSL-enabled
browser.
.PP
The \fBdpkg-www\fR web installation is not intended to replace the normal
use of \fBapt-get\fR(8) from the shell.
It is provided only as a shortcut to allow the installation of a package
after having located it with the browser without needing to open a root
shell and run \fBapt-get\fR(8) manually.
For normal package maintenance and system upgrade the use of
\&\fBapt-get\fR(8) from the shell is recommended.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\fB\s-1DPKG_WWW_HOST\s0\fR" 4
.IX Item "DPKG_WWW_HOST"
The hostname to use.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/etc/dpkg\-www.conf\fR" 4
.IX Item "/etc/dpkg-www.conf"
Configuration file for \fBdpkg-www\fR.
It is not necessary for this file to exist,
there are sensible defaults for everything.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdpkg\fR(1),
\&\fBdwww\fR(1),
\&\fBdwww\fR(7),
\&\fBdlocate\fR(1),
\&\fBman2html\fR(8),
\&\fBgrep-dctrl\fR(1).