[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.txt,1.5,1.6
seanius@haydn.debian.org
seanius@haydn.debian.org
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv12812
Modified Files:
Webapps-Policy-Manual-DRAFT.txt
Log Message:
a little bit from sean on the FHS and config files
Index: Webapps-Policy-Manual-DRAFT.txt
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/Webapps-Policy-Manual-DRAFT.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- Webapps-Policy-Manual-DRAFT.txt 6 May 2005 13:50:14 -0000 1.5
+++ Webapps-Policy-Manual-DRAFT.txt 7 May 2005 21:16:01 -0000 1.6
@@ -37,14 +37,16 @@
Contents
+NOTE: let's not worry too much about the numbering/order right now
+
1 About this manual
1.1 Scope
1.2 Authors and Maintainers
1.3 Related Documents
2 Common issues and recommended solutions
- 2.1 The document root
- 2.2 Web param files
+ 2.1 Web applications and the FHS
+ 2.2 Configuration Files and Customizable Content
2.3 Static files
2.4 Database issues
2.5 Architecture independant scripts (Perl, PHP and others)
@@ -118,19 +120,74 @@
the points covered here are mandatory if you want your package to be included in
the Debian Archive.
-2.1 Web param files
+2.0 Web applications and the FHS
-FIXME
+web applications should follow the same guidelines as any other
+software. most specifically, they should not make any assumption about
+how the administrator has arranged the file hierarchy outside of the FHS
+by placing files in non-standard places such as /var/www or /usr/local.
-Web application can provide some configuration files which are editable through
-the web interface. Those files are seen as special conffile (in the Debian
-point of view).
+specifically, the following table should serve as guidelines for the
+location of files:
-Every file that is meant to change the behaviour of the application should be a
-conffile located under `/etc/$package'.
+type of file location
+static web pages /usr/share/PACKAGE/www*
+dynamically interpreted web pages /usr/share/PACKAGE/www*
+dynamcially executed web pages /usr/lib/cgi-bin/PACKAGE**
+application-specific libraries /usr/share/PACKAGE/include***
+site configuration (settings/passwords) /etc/PACKAGE
+locally modifiable/overridable content /etc/PACKAGE****
+php libraries /usr/share/php/PACKAGE
+rrd, mrtg and other database files see database application policy
+
+*: also acceptable are "htdocs", "site", or any other name, as long as
+ it is clearly identifying and a subdirectory of /usr/share/PACKAGE. this
+ will allow other non-web-accessible data to also be stored in the parent
+ directory.
+**: what to do with non-architecture-specific executable files is up
+ for debate. another possible location would be /usr/share/PACKAGE/cgi-bin
+***: other names, such as "lib" or "functions" are acceptable, as is anything
+ else, as long as it is identifiable, outside the documentroot, and in
+ a subdirectory of /usr/share/PACKAGE.
+
+2.1 Configuration Files and Customizable Content
+
+in-line with standard FHS policy, any files that require being edited by
+the local administrator (for information such as "themes" or credentials
+to a database) must be located under /etc, in a directory specific to
+the package in question.
+
+often the upstream authors of software will ship a configuration file
+that is located underneath the web root of the application. the admin
+must not be required to edit these files because package upgrades could
+lead to loss of this configuration.
+
+the best way to work around such a problem is by using whatever is
+the appropriate "include" construct for the language in question (in
+PHP this would be "require_once", in perl "use") to include a smaller,
+trimmed down configuration file from underneath /etc.
+
+2.1.1 Permissions and Ownership of Configuration Files
+
+Webapp configuration files will likely need to have permissions and ownership
+different from the standard root:root ownership and 644 permissions. The most
+notable reason for this is that the webserver usually needs the ability to
+read some of these configuration files. note that some applicatoins provide
+the ability to edit their configuration via a web-based interface. in such
+a case, the files should be writable by the www-data group. the local
+administrator should always be able to prevent this behavior by changing the
+file permissions via dpkg-statoverride.
+
+the following table reflects the requirements for configuration file
+permissions and ownership
+
+FIXME: maybe we should add this to the above table, with specs for all files?
+
+file type/content ownership permissions
+sensitive settings/passwords root:www-data 640
+non-sensitive data (themes, etc) root:www-data 644
+application-editable configuration root:www-data 660
-Note that this file should be writable by the `www-data' user in order to let
-the application edit the file.
2.2 Static files