Provided by: dpkg-www_2.54+nmu1_all bug

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                                DPKG-WWW(8)