[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]

Webapps Policy Manual
Chapter 3 - Common issues and recommended solutions


3.1 Web applications and the FHS

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 /srv, /var/www or /usr/local.

Specifically, the following table should serve as a guideline for the placement of files:

Static and dynamically interpreted content

/usr/share/PACKAGE/www

Dynamically executed content

A unique subdirectory of either /usr/lib/cgi-bin/PACKAGE or /usr/lib/PACKAGE (architecture-dependant)

A unique subdirectory of /usr/share/PACKAGE (architecture-independant)

Application-specific include files

A unique subdirectory of /usr/share/PACKAGE

Other static data, and helper scripts that don't belong in users' paths

A unique subdirectory of /usr/share/PACKAGE

Persistent application data

Cached and regenerated application data

rrd, mrtg and other database files

See database application policy.

Site configuration (settings/passwords)

/etc/PACKAGE

Modifiable and overridable content

A subdirectory of /etc/PACKAGE

PHP includable libraries

/usr/share/php/PACKAGE

Perl includable libraries

See Debian Perl Policy


3.2 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 local administrator must not be required to edit these files because package upgrades could lead to loss of such configuration.

The best way to work around such a problem is by using the appropriate "include" construct for the language in question. to include a smaller, trimmed down configuration file from /etc/PACKAGE. In PHP this would be require_once, and in perl this would be use.


3.2.1 Permissions and Ownership of Configuration Files

Web application configuration files may 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 applications 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 behaviour by changing the file permissions via dpkg-statoverride. TODO: should configuration files generated via a web interface exist in /etc, or in /var/lib as included files?

The following table reflects the requirements for configuration file permissions and ownership

Sensitive settings/passwords

Ownership: root:www-data

Permissions: 640

Non-sensitive settings (themes, etc)

Ownership: root:www-data

Permissions: 644

Application-modifiable configuration

Ownership: root:www-data

Permissions: 660


3.3 Static content

Static content can be divided into smaller subsets based on their nature:

Static content provided by the package should be considered read-only data. The local administrator should not be required to modify such files. Content requiring or suggesting modification for customizing a web application must not exist in the same location as standard package-provided content.

If a web application supports using an alternate location for customized content, it should either follow the previously mentioned guidelines for configuration and customizable content or use a subdirectory of /usr/local/PACKAGE. Managing the latter is outside the scope of this document.


3.4 Database issues

If the web application needs a database to run properly, it must abide by the database application policy. The maintainer is highly encouraged to use a common tool such as dbconfig-common to perform the database configuration. Please see the dbconfig-common manual for more information.


3.5 Architecture independent scripts (Perl, PHP and others)

Scripts that shouldn't normally need to exist in the standard system path should follow the standard Debian policy and exist in /usr/share/PACKAGE.

However, web applications have the additional requirement that if such scripts are not intended to be directly accessed via the web, they must not exist under the document root or other directly web-accessible location. Scripts intended for execution or interpretation via the web must exist in locations where their underlying source code can be directly retrieved.


3.6 Architecture dependant binaries

The policy for Architecture dependant binaries should follow the general rules of the FHS and Debian policy, and exist in /usr/lib/PACKAGE. Additionally, policy permits these files to exist in /usr/lib/cgi-bin/PACKAGE though this may become deprecated in the future.

Similar to Architecture-independent files, if such files are intended to be executed via the web, they must not exist in a location where they can be directly retrieved.


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]

Webapps Policy Manual

$Revision: 1.15 $

Alexis Sukrieh
Pascal Hakim
Neil McGovern
Sean Finney