Debian WWW standards version 2.0
Please criticize and return.
Bruce
Debian WWW Organization
Version 2.0
Bruce Perens
3-November-1996
1. Rationale
1.1 Serving Debian Documentation
A primary purpose of the WWW server and browser on a Debian system is to
provide access to all available Debian documentation. This implies several
goals:
A. WWW configuration must be automatic.
Since the user is reading documentation via WWW, we must provide
that user with a WWW configuration that works correctly right away,
without any configuration on the user's part.
B. The WWW service of Debian documents must be robust.
If a WWW server is removed and a different one is then installed,
access to Debian documentation must be maintained.
C. Automatic installation of documents must be supported.
Packages need a well-known fixed path that can be used to install
files, and a corresponding well-known URL to access those files
once they are installed.
1.2 Serving as a User-Specific WWW Site
Obviously, Debian users may wish to build large, publicly-accessable WWW
sites. Debian should not stand in the way of that. However, the
webmaster can be expected to understand their document organization and
to put a good deal of custom configuration into their system. This is not
the case for the user who simply uses the local WWW server to read Debian
documentation.
There are a few goals necessary to support the webmaster:
A. Debian can't take over the WWW site. This will only get in the way
of the webmaster. Thus, Debian should restrict its
activities to its own well-known locations, and should _not_
install files in the root of the WWW server.
B. Webmasters all have their favorite server. Thus, we should support
as many servers as possible, and the documentation scheme should
work with all of them.
C. Security is important to the webmaster. Thus, we should make it as
easy as possible to maintain the security of the system while it
serves documents that have been installed by Debian.
2.0 Implementation
2.1 Well-Known Paths and URLs
The WWW server package maintainer may locate the document root of their
WWW server where they wish, except that the document root may not be located
in any of the directories mentioned in this proposal. A Debian package must not
install data in the document root of the WWW server, unless it is the package
that installs the server itself.
Debian will maintain a directory /var/lib/debian-www/documents . Each WWW
server must export this directory as "http://<hostname>/debian/".
Data in this directory may be rewritten while the system is operating.
The WWW server may write its own housekeeping files under this directory.
Debian will maintain a directory /var/lib/debian-www/cgi-bin . Each WWW
server must export this directory as "http://<hostname>/cgi-bin/debian/ .
Data in this directory may be rewritten while the system is operating.
The WWW server may write its own housekeeping files under this directory.
Debian will maintain a directory /usr/lib/debian-www/documents. This directory
is restricted in that it may be on a read-only medium once packages have been
installed. This is an appropriate place to install data that does not need
to be re-written while the system is operating. Each WWW server must export
this directory as "http://<hostnamne>/debian/ROM.documents . The WWW server
must treat this as ROM space, and must not write files under this directory.
The WWW server is allowed to use any contrivance to make this space available.
For example, it can provide access to the URL through a "virtual path" CGI
script, or it can create symbolic links from all of the documents in the ROM
space to a directory in read-write space.
Debian will maintain a directory /usr/doc . This directory
is restricted in that it may be on a read-only medium once packages have been
installed. This is an appropriate place to install program documentation and
examples that do not need
to be re-written while the system is operating. Each WWW server must export
this directory as "http://<hostnamne>/debian/ROM.usr.doc . The WWW server
must treat this as ROM space, and must not write files under this directory.
The WWW server is allowed to use any contrivance to make this space available.
For example, it can provide access to the URL through a "virtual path" CGI
script, or it can create symbolic links from all of the documents in the ROM
space to a directory in read-write space.
Debian packages may install files under the above directories and may expect
the WWW server to immediately make these files available. To facilitate this
the WWW server may create a script "/usr/bin/update-debian-www". Packages that
install files in the above-mentioned directories will detect the existance of
this script in their postinst scripts, and will execute the script if it
exists. The script must scan the above mentioned areas for files, and must
make those files accessable.
Debian will maintain a directory /usr/lib/debian-www/cgi-bin. WWW servers
must not directly export this directory. However, symbolic links may be
created from /var/lib/debian-www/cgi-bin to /usr/lib/debian-www/cgi-bin
to make CGI scripts available for the server to export. Packages may
install these symbolic links automaticaly. If a symbolic link is installed to
make a new CGI script available, the package that installs it must detect the
presence of /usr/bin/update-debian-www, and execute it if it exists.
CGI scripts installed by Debian packages must conform to the current CGI
standard. If CGI scripts use server-specific features, they must detect the
presence or absence of those features, and should continue to operate or
at least fail gracefully with a message to the user if a desired feature is
not available.
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: