NAME
dpkg-www, dpkg-www-installer - WWW Debian package browser
SYNOPSIS
http://<hostname>/cgi-bin/dpkg
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 dpkg(1) command,
but navigating through the package dependencies and the documentation
files can be a very frustrating and time-consuming task.
With the dpkg-www cgi 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 a few
mouse clicks. If you have superuser privileges you can even install,
upgrade or remove packages from your WEB browser. The output provided
by dpkg-www is basically that of dpkg with the addition of HREF’s for
packages dependencies and documentation files.
The cgi program can take an optional query argument which can be given
in the URL or entered in the query field of the html form. This can be:
<empty>
list concisely all installed packages
* (asterisk)
list concisely all installed and available packages
<list of packages>
list concisely the requested packages
<wilcard expession>
list concisely all packages whose name matches the expression,
for example ‘*image*’ will find all packages which contain the
string ‘image’.
<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.
<absolute pathname>
list all the packages owners of a file. This can be used for
example to find which package installed a program.
/<regexp>
list all the packages owners of a file. The regexp form can be
used to find which packages own a non installed file.
<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 GREP_DCTRL_OPTS option in
the config file. This feature works only if the grep-dctrl
package is installed.
? (question mark)
show a concise help about the cgi usage.
<space> (a single space)
print only the input form, for use from window-manager menus.
Configuration
dpkg-www can be configured by the local system administrator via the
optional /etc/dpkg-www.conf file. This file is a simple Bourne shell
(/bin/sh) script that defines some or all the following variables
(defaults are used if the file doesn’t exist, or doesn’t define the
variable):
CHECK_BUTTONS
If this option is enabled dpkw-www 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.
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 WEB
Installation. 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 "top" the button will be
located before the file list, default is the bottom of the page.
SHOW_LOCAL_FILES
If this variable is set, dpkg-www will use file:/ style URL’s to
access html files -- bypassing the cgi script. This is faster
on slow machines. Default is not defined, which means use local
files for connection from localhost and http:// URL’s for remote
connections.
CHECK_PACKAGE_VERSION
If this variable is set, dpkg-www 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.
LIST_UNAVAILABLE
This option enables listing also unavailable packages in the
packages list. Disabled by default.
LIST_DOCUMENTATION
This option enables the display of references to documents
registered with install-docs(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 install-docs and the search is done with an ugly
hack. Hopefully things will change in woody. This option is
enabled (1) by default.
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.
GREP_DCTRL_OPTS
These options are passed to grep-dctrl(1) when doing a query by
field. Default is "-i" for case-insensitive fixed substring
match. See grep-dctrl(1) for more info.
DPKG Command providing the dpkg(1) query functionalities. This can be
dpkg or dlocate , or auto . Default is auto, meaning that the
cgi will use dlocate if installed, otherwise revert to dpkg
which should always be available on a Debian system. By
specifying this option you can force the use of one of the two
program.
MAN Manpage to HTML translation command. Can be dwww , man2html or
auto . Default is auto, meaning that the cgi will use man2thml
if installed, otherwise revert to dwww . By specifying this
option you can force the use of one of the two program.
DEBIAN_CONTENTS
Optional list of one or more Contents-xxx.gz files mapping each
file available in the Debian GNU/Linux 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.
BGCOLOR
background color of the HTML body.
DEBUG internal option used only for debugging. Disabled by default
since it is useless for normal users.
DWWW_PATH
path on webserver to dwww cgi-bin.
INFO2WWW_PATH
path on webserver to info2www cgi-bin.
The following is an exaple /etc/dpkg-www.conf file:
# 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/stable/Contents-i386.gz
/debian/dists/potato/non-US/Contents-i386.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
Cgi access
The information provided by dpkg-www 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
cgi program should be allowed only from localhost and trusted hosts or
domains. Unfortunately this configuration is dependent on the
particular installed WEB server. The dpkg-www package configures the
apache 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 cgi from your
network and browse packages on any host from any other machine.
WEB installation
If this option is enabled in the /etc/dpkg-www.conf 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.
For security reasons the installation is done entirely from the browser
side, so that you don’t need to gain root privileges from the cgi
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 apt-get command to install the requested packages.
The WEB browser must have been configured to handle the above content-
type by running the command "/usr/sbin/dpkg-www-installer -x -f ’%s’",
which must obviously intalled also on the client side if installing
from remote. If the dpkg-www package is not installed on the browser
client you can simply copy the script /usr/sbin/dpkg-www-installer and
hope it works...
You can configure your Netscape. browser from the Navigator ->
Application menu of the Preferences window. You must add a new item
with MIME type "application/dpkg-www-installer" and application
"/usr/sbin/dpkg-www-installer -x -f ’%s’". This should add the
following line to your Netscape mailcap file:
application/dpkg-www-installer;/usr/sbin/dpkg-www-installer -x -f
’%s’
The dpkg-www WEB installation has been succesfully tested only with
Netscape. With other WEB browsers it is untested and it may not work
correctly.
In order to be able to install the packages the user must known the
root password asked for ‘su root’ when installing on the local server,
or have the ability to ssh as root to the remote host when installing
from a remote client.
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 apt-get
as root to install or remove the required packages. Starting this from
the WEB could be potentially vulnerable to man-in-the-middle 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.
The dpkg-www WEB installation is not intended to replace the normal use
of apt-get 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 apt-get manually. For
normal package maintenance and system upgrade the use of apt-get from
the shell is recommended.
FILES
/etc/dpkg-www.conf
Configuration file for dpkg-www. It is not necessary for this
file to exist, there are sensible defaults for everything.
SEE ALSO
dpkg(8), dwww(1), dwww(8), dlocate(1), man2html(8), grep-dctrl(1)
AUTHOR
Massimo Dal Zotto <dz@debian.org>.
Bugs should be reported via the normal Debian bug reporting system.
LICENCE
dpkg-www is licensed under the GNU General Public License version 2.
Oct 7, 2005