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