Provided by: dpkg-www_2.56_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 successfully 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)