[ 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 /home, /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


Dynamically executed content

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

or 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, for example htdocs

User uploaded content

A unique subdirectory of /var/lib/PACKAGE

Persistent application data, Cached/regenerated application data, rrd, mrtg and other database files

See database application policy.

Site configuration (settings/passwords)


Modifiable and overridable content

A subdirectory of /etc/PACKAGE

PHP includable libraries


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 (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. These application created files should be located in /etc/PACKAGE.

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/share/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 Security measurements

Web applications that are configured by default to be publically accessable must not rely on features or particular configurations of a webserver or scripting engine that are considered to be insecure. For example, applications must not depend on the "register_globals" setting in the PHP scripting engine

Web-based applications should not blindly trust any user-provided data. Before emitting them, the data needs to be checked for cross-site scripting attempts, i.e. HTML code needs to be escaped. Input for databases needs to be checked against SQL-injection attempts, i.e. quotes need to be escaped. User-driven arguments to any file or permission related functions need to be checked against information disclosure, i.e. input needs to be checked for ways to escape the intended path on the filesystem.

3.6 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 not be directly retrieved.

This may require to split upstream source into two directories and adjusting the include path or statements.

3.7 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 not 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: DRAFT-1.10

Alexis Sukrieh
Pascal Hakim
Neil McGovern
Sean Finney
Joey Schulze