Provided by: dpkg-www_2.63_all bug

NAME

       dpkg-www, dpkg-www-installer - WWW Debian package browser

SYNOPSIS

       https://<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 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(1) 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.

       wildcard 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(1) 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 https:// 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(8) 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(1) or
           dlocate(1), or auto.  Default is auto, meaning that the CGI will use dlocate(1) if
           installed, otherwise revert to dpkg(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.

       MAN Man page to HTML translation command. Can be dwww(7), man2html or auto.  Default is
           auto, meaning that the CGI will use man2thml if installed, otherwise revert to
           dwww(7).  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 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 web server to dwww(7) cgi-bin.

       INFO2WWW_PATH
           Path on web server to info2www(1) cgi-bin.

       The following is an example /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/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

   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(8)
       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 be installed also
       on the client side if installing remotely.  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 Firefox browser from the General -> 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 Firefox mailcap file:

        application/dpkg-www-installer;/usr/sbin/dpkg-www-installer -x -f '%s'

       The dpkg-www web installation has been successfully tested only with Firefox.  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(8) as root to install or remove the required packages.
       Starting this from the web could be potentially vulnerable to man-in-the-middle (MITM)
       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(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 apt-get(8)
       manually.  For normal package maintenance and system upgrade the use of apt-get(8) from
       the shell is recommended.

ENVIRONMENT

       DPKG_WWW_HOST
           The hostname to use.

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(1), dwww(1), dwww(7), dlocate(1), man2html(8), grep-dctrl(1).