Re: Request for review: Apache2 docs and configuration
Arno Töll wrote:
> (please CC: me on replies)
>
> could someone willing to help us non-native English speakers to review
> our existing documentation and configuration files for the upcoming
> Apache2 package supposed to be included in Wheezy? Any help would be
> welcomed. You can obtain the source package in our git repository at
> [1]. Beware all documentation and configuration files I'm referring to,
> can be found in the next branch, not master. Alternatively you can
> browse the source on-line at [2]. I'd prefer a git format patch but any
> patch format acceptable to patch(1) would work for me.
As a non-developer I'm not familiar with the incantations required to
check things in and out of git; but now I've worked out how to get
"raw" versions out of anonscm I can easily give you diffs.
> In particular I'd need someone to review these files (relative to the
> main directory):
>
> * debian/PACKAGING
This is the long one...
I gather 'singlequotes' are being used to indicate verbatim-quoted
filenames, while "doublequotes" indicate actual quotations.
A couple of sentences use "shall" where I think they mean "should";
but maybe it's "must"? Or a non-normative "ought to"?
> * debian/apache2.NEWS (latest entry only)
Okay, a few English tweaks.
> * debian/apache2.README.Debian
I've changed s/building block/foundation stone/ on the assumption
that this was the metaphor you were going for.
I haven't changed the references to /var/run, which these days should
probably be talking about /run. Likewise, you might mention "service
foo restart" as a standard administrative interface rather than
"/etc/init.d/foo restart".
I've extended the use of '/path/in/single/quotes' to this file instead
of allowing extra spaces before punctuation.
> * debian/config-dir/apache2.conf
Amended some of those ASCII-art "|-"s to "`-"s.
> * debian/config-dir/sites-available/000-default.conf
Needed some de-garbling.
> There are more files, but these are probably not that important.
Of course I've also ended up looking at debian/control... and finding
one tiny typo in apache2-doc.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- old/PACKAGING 2012-04-24 13:00:36.752037389 +0100
+++ new/PACKAGING 2012-04-24 15:24:01.359392348 +0100
@@ -35,18 +35,18 @@
The Apache 2 web server package in Debian supports two types of reverse
dependencies: modules and web applications. They need to be treated differently
-as their requirements are different. We have special requirements how to declare
-dependencies against Apache 2 web server packages depending on the type of
-package. Refer to the respective parts for extensive information.
-
-Furthermore, there are several helper tools available to assist on common tasks.
-These are outlined in their respective sub sections as well. You should use
-these tools to get maintainer scripts and dependencies right.
-
-This document follows normative wording of the Debian Policy Manual §1.1 [1]. The
-words must, should and may, and the adjectives required, recommended and optional,
-are used to distinguish the significance of the various guidelines in this policy
-document.
+as their requirements are different. We have special requirements for how to
+declare dependencies against Apache 2 web server packages depending on the type
+of package. Refer to the appropriate parts for extensive information.
+
+Furthermore, there are several helper tools available to assist with common
+tasks. These are outlined in their respective sub sections as well. You should
+use these tools to get maintainer scripts and dependencies right.
+
+This document adopts the normative wording of the Debian Policy Manual §1.1[1].
+The words "must", "should", and "may", and the adjectives "required",
+"recommended", and "optional", are used to distinguish the significance of the
+various guidelines in this policy document.
[1] http://www.debian.org/doc/debian-policy/ch-scope.html#s1.1
@@ -54,64 +54,67 @@
===================
Modules are packages which are installing third party extensions to the Apache 2
-web server which can be loaded at runtim to extend the functionality of the core
-server. Please realize such modules make use of a stable Application Binary
-Interface (ABI) once compiled which need a recompile if the web server changes.
-Hence be careful how you declare dependencies against the web server. You need
-to make sure it does not break upon upgrades.
+web server which can be loaded at runtime to extend the functionality of the
+core server. Please be aware that such compiled modules make use of a stable
+Application Binary Interface (ABI) and therefore need a recompile if the web
+server changes. Hence be careful how you declare dependencies against the web
+server. You need to make sure it does not break upon upgrades.
-A module package providing an Apache module must obey our policies to make sure
-it can be upgraded without breakage at the installation site. To achieve this, a
+A module package providing an Apache module must obey these policies to make
+sure it can be upgraded without breakage of local sites. To achieve this, a
package must build-depend on apache2-dev. That package provides the 'apxs'
compile helper which makes sure the module to be compiled is compatible with the
Apache 2 web server and the C headers the server is providing as a public
interface. If an updated package is not buildable with Apache 2.2 anymore, the
-apache2-dev build-dependency should be versioned ">> 2.4~", because older versions
-of apache2-threaded-dev did provide apache2-dev.
+apache2-dev build-dependency should be versioned ">> 2.4~", because older
+versions of apache2-threaded-dev did provide apache2-dev.
The resulting binary package should be called libapache2-mod-<modulename> and
MUST NOT depend on apache2 or apache2-bin. Instead a module package must depend
-on our virtual package providing the module magic number which is denoting the ABI
+on our virtual package providing the module magic number which denotes the ABI
compatibility version number. The virtual package is called apache2-api-YYYYMMDD
-and is guaranteed to be stable among all binary updates of 2.4.x. The dh_apache2
-helper assists to get dependencies right.
+and is guaranteed to be stable through all binary updates of 2.4.x. The
+dh_apache2 helper assists in getting the dependencies right.
2.1 '.load' and '.conf' files
-----------------------------
-The module must install a 'module.load' file to /etc/apache2/modules-available
-where 'module' is the name of the installed module without "mod_" prefix. The
+The module must install a 'module.load' file to /etc/apache2/modules-available,
+where 'module' is the name of the installed module minus the "mod_" prefix. The
'.load' file must contain an appropriate "LoadModule" directive only.
-Additionally maintainers may declare module dependencies and conflicts in a magic
-line in '.load' files which need to be resolved to load a module at the
-installation site. This is useful if a module depends on other modules to be
+Additionally maintainers may use a magic line in '.load' files to declare
+module dependencies and conflicts which need to be resolved to load a module for
+a local site. This is useful if a module depends on other modules to be
loaded, or to conflict with other modules if they can't be loaded at the same
-time. a2enmod and a2dismod will parse "# Depends: module [module [...]]" and "#
-Conflicts: module [module [...]]" magic comments, for example to load mod_foo:
+time. a2enmod and a2dismod will parse any "magic comment lines" with the format
+"# Depends: module [module [...]]" and "# Conflicts: module [module [...]]";
+for example to load mod_foo:
-foo.load:
+In 'foo.load':
# Depends: bar
# Conflicts: baz
LoadModule foo_module /usr/lib/modules/mod_foo.so
-Additionally, a 'foo.conf' configuration file may be installed along the 'load'
-file to configure the module following the same naming scheme if required. This
-is useful if the module in question requires some initial configuration to be
-useful. No magic comments are recognized in '.conf' files. Aside they have the
-same functionality and requirements as configuration files (see section 3 below).
-You should use only directives provided by default by our web server configuration
-or which are provided by your module itelf in a supplied '.conf' file.
-
-In some rare cases it can't be avoided that a module depends on an another module
-to be loaded already before its own load approach can succeed. The module load
-order is guaranteed to be sorted alphabetically which could yield to problems if
-the new module to be loaded sorts later. In most cases such pre-load dependencies
-could be avoided upstream - consider filing a bug. If there is no way out that
-problem, you may want to add a conditional Include in your own module file.
+Additionally, if required, a 'foo.conf' configuration file to configure the
+module may be installed along with the 'load' file, following the same naming
+scheme. This is useful if the module in question requires some initial
+configuration to be useful. No magic comments are recognized in '.conf' files.
+Otherwise they have the same functionality and requirements as configuration
+files (see section 3 below). You should use only directives provided by default
+by our web server configuration or which are provided by your module itelf in a
+supplied '.conf' file.
+
+In some rare cases it can't be avoided that a module depends on an another
+module being loaded already before its own loading process can succeed. The
+module load order is guaranteed to be sorted alphabetically, which could lead to
+problems if the new module to be loaded sorts later. In most cases such
+pre-load dependencies can be avoided upstream - consider filing a bug. If there
+is no way out of this problem, you may want to add a conditional Include in your
+own module file.
-Suppose mod_foo relies on mod_bar to be loaded before, you may want to write a
+Suppose mod_foo relies on mod_bar to be loaded first. You may want to write a
module 'load' file like this:
# Depends: bar
@@ -121,22 +124,22 @@
LoadModule foo_module /usr/lib/modules/mod_foo.so
-Please note, that the bar.load file must also contain a respective "<IfModule
-!mod_bar.c>" guard as it would be loaded twice oterhwise. Use this method
-extremely sparingly and in agreement with related package maintainers only. Note,
-such a module '.load' file must still contain a "Depends:" magic line to make sure
-that the a2enmod/a2dismod dependency resolver works correctly.
+Please note that the bar.load file must also contain a matching "<IfModule
+!mod_bar.c>" guard as it would be loaded twice otherwise. Use this method
+extremely sparingly and in agreement with related package maintainers only.
+Note that such a module '.load' file must still contain a "Depends:" magic line
+to make sure that the a2enmod/a2dismod dependency resolver works correctly.
2.2 Maintainer scripts
----------------------
Maintainer scripts should not invoke a2enmod directly. Instead, the
-apache2-maintscript-helper should be used. Please realize, the helper is not
-guaranteed to be installed on the target system. There are certain setups which
-do not require Debian specific configurations, so modules must not do anything
-in maintainer scripts which makes use of Debian specific enhancements like
-apache2-maintscript-helper, a2enmod, or a2query unconditionally. It is recommended
-to invoke it like this:
+apache2-maintscript-helper should be used. Please be aware that the helper is
+not guaranteed to be installed on the target system. There are certain setups
+which do not require Debian specific configurations, so modules must not do
+anything in maintainer scripts which makes use of Debian-specific enhancements
+like apache2-maintscript-helper, a2enmod, or a2query unconditionally. It is
+recommended to invoke it like this:
if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
. /usr/share/apache2/apache2-maintscript-helper
@@ -157,29 +160,30 @@
Web applications are different from modules in that they do not have a hard
dependency on the web server. Typically they require a running web server,
but they do not need to worry about binary compatibility of modules. We accept
-there are other web servers besides Apache, thus we discourage package
-maintainers of web applications to depend unconditionally on Apache. That
+that there are other web servers besides Apache; thus we discourage package
+maintainers of web applications from depending unconditionally on Apache. That
said, we provide several helpers to assist web application packagers to invoke
configuration snippets to enable a web application in the Apache 2 web server.
-We differentiate between two sub types: Sites and general configuration. Sites
+We differentiate between two sub-types: sites and general configuration. Sites
are installed to /etc/apache2/sites-available and configure a particular
-virtual hosts. Special care must be taken when installing a site configuration
-to make sure it does not interfere with site local configuration the
-administrator uses. Typically there are a few use cases only, where a Debian
+virtual host. Special care must be taken when installing a site configuration
+to make sure it does not interfere with site-local configuration used by the
+administrator. Typically there are only a few use cases where a Debian
package should include a virtual host configuration.
The general configuration snippets are installed to /etc/apache2/conf-available
instead. Package maintainers are advised to avoid "local-" prefixes to
installed conffiles, and ideally use "packagename.conf" to avoid name clashes.
-This type of configration shall be used when installing a global (i.e. virtual
+This type of configuration must be used when installing a global (i.e. virtual
host independent) configuration. Usually these configuration snippets will be
included in the global server context via the conf-enabled directory. However,
it is planned to allow the administrator to only enable the configuration
snippets in a selected set of virtual hosts.
Typically a "packagename.conf" should enable a global alias pointing to your web
-application along a script-dependendent per-script configuration, for example:
+application along with a script-dependendent per-script configuration; for
+example:
Alias /packagename /usr/share/packagename
@@ -192,12 +196,12 @@
directives from these modules: mod_access_compat, mod_alias, mod_auth_basic,
mod_authn_file, mod_authz_host, mod_authz_user, mod_autoindex, mod_deflate,
mod_dir, mod_env, mod_filter, mod_logio, mod_mime, mod_negotiation,
-mod_setenvif, mod_unixd, mod_version, mod_watchdog. Check the respective module
-documentations about the modules providing directives you are using.
+mod_setenvif, mod_unixd, mod_version, mod_watchdog. Check the module
+documentation for the modules providing directives you are using.
-Note, not all directives are really required. Suppose your <Directory>
-configuration can be enhanced, but does not necessarily need to use mod_rewrite
-rules you could do something like:
+Note that not all directives are really required. If your <Directory>
+configuration can be enhanced by mod_rewrite rules, but does not necessarily
+need to use them, you could do something like:
<Directory /usr/share/packagename>
...
@@ -214,31 +218,31 @@
---------------------------------------
There are use cases where a configuration really needs a certain module to be
-enabled. This is tricky to achieve for web applications as dependences could lead
-to complex dependency chains which could break unrelated web applications
-installed along your package. Thus, we do not resolve module dependencies for web
-applications automatically, but they may be expressed (see 'load' files in section
-2.1), and a2enconf will warn the site administrator about modules which need to
-enabled. Moreover, modules can be arbitrarly enabled and disabled, thus a web
-application must make sure not to break the web server start-up if a required
-module is not available.
+enabled. This is tricky to achieve for web applications as dependencies could
+lead to complex dependency chains which could break unrelated web applications
+installed alongside your package. Thus, we do not resolve module dependencies
+for web applications automatically, but they may be expressed (see 'load' files
+in section 2.1), and a2enconf will warn the site administrator about modules
+which need to enabled. Moreover, modules can be arbitrarily enabled and
+disabled by local administrators, so a web application must make sure not to
+break the web server's start-up if a required module is not available.
The syntax for config snippets to express dependencies is identical to the
-syntax in modules' ".load" files. Within your package.conf file you still need
-to protect non-default directives by <IfModule> clauses as there is no
-guarantee, that the modules are actually enabled. It is acceptable if your
-configuration file turns to a no-op then, as long as it does not break the
-server start-up.
+syntax in modules' '.load' files. Within your package.conf file you still need
+to protect non-default directives with <IfModule> clauses as there is no
+guarantee that the modules are actually enabled. It is acceptable if your
+configuration file turns into a no-op as long as it does not break the server
+start-up.
-For both types of configuration, configurations and sites dh_apache2 can be used
-to assist packagers.
+For both types of configuration (configurations and sites), dh_apache2 can be
+used to assist packagers.
3.2 Package dependencies
------------------------
-Web applications must depend (or recommend respectively) the apache2 package only. Web
-applications must not depend or recommend apache2-bin or apache2-data packages.
-Generally web server dependencies should be declared in the form:
+Web applications must only depend on (or recommend) the apache2 package. Web
+applications must not depend on or recommend the packages apache2-bin or
+apache2-data. Generally, web server dependencies should be declared in the form:
Depends: apache2 | <alternative web servers you support> | httpd-cgi
@@ -246,17 +250,17 @@
Recommends relation only. While a consolidated and consistent behavior among web
applications would be desirable, from Apache's point of view, both alternatives
are acceptable. If your web application depends on a particular web server module
-you need to depend on it, too. For example, PHP applications might need to
+you need to depend on that, too. For example, PHP applications might need to
formulate dependency lines in the form:
Depends: libapache2-mod-php5 | php5-cgi | php5-fpm
Recommends: apache2 | <alternative web servers you support> | httpd-cgi
-Similar to modules, web applications may enable their configuration files in
+A with modules, web applications may enable their configuration files in
maintainer scripts. Use of dh_apache2 is recommended to achieve this. Generally,
-special care must be taken not to use Apache2 Debian helper scripts like a2query
-and a2enmod unconditionally. You can use the apache2-maintscript-helper tools
-provided by the apache2 package for common tasks this way:
+special care should be taken not to use Apache2 Debian helper scripts like
+a2query and a2enmod unconditionally. You can use the apache2-maintscript-helper
+tools provided by the apache2 package for common tasks this way:
if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
. /usr/share/apache2/apache2-maintscript-helper
@@ -265,46 +269,47 @@
Refer to the reference documentation below to learn how to use
apache2-maintscript-helper. Do not enable or disable modules in web
-application maintainer scripts, instead protect your configuration by <IfModule>
-clauses if you require non-standard modules.
+application maintainer scripts; instead protect your configuration with
+<IfModule> clauses if you require non-standard modules.
4 Maintainer Scripts
====================
-While it was already discussed briefly in previous sections, here follow some
-clarifications regarding the invokation of wrapper scripts in maintainer scripts
+Though already discussed briefly in previous sections, here follow some
+clarifications regarding the invocation of wrapper scripts in maintainer scripts
of modules and web applications.
4.1 Enabling Configurations
---------------------------
-Both, modules and web applications should use the apache2-maintscript-helper in
+Both modules and web applications should use the apache2-maintscript-helper in
general. The helper will obey local policies to decide when to enable a piece of
-configuration, to reload the web server and such. Moreover, it will remember
+configuration, to reload the web server, and so on. Moreover, it will remember
whether a module was activated by the site administrator or a maintainer script.
-Thus, it is particularly important you do not use "a2enmod" and such directly
-(a2query is acceptable though).
+Thus, it is particularly important you do not use "a2enmod" and so on directly
+(though a2query is acceptable).
-This is a summary how the apache2-maintscript-helper shall be invoked in
+This is a summary of how the apache2-maintscript-helper should be invoked in
maintainer scripts:
Modules:
- Modules should unconditionally call apache2_invoke (unless a maintainer
- or debconf script verified not to install any configuration at all, e.g.
- for scripts supporting several web servers) in their "postinst configure"
- sections. It will obey site local policies in future and will make sure
- that during upgrade of a module package, disabled modules are not enabled
- again.
- Modules need to be disabled on removal (and purge anyway), otherwise
+ Unless a maintainer or debconf script verified that no configuration was
+ to be installed at all, e.g. for scripts supporting several web servers,
+ modules should unconditionally call apache2_invoke in their "postinst
+ configure" sections. It will obey site-local policies in future and will
+ make sure that disabled modules are not enabled again during upgrades of
+ a module package.
+
+ Modules need to be disabled on removal (and purge anyway), as otherwise
their configuration will be broken (as LoadModule would fail because of
the missing shared object file). Thus, modules need to call
- apache2_invoke dismod on both, removal and purge. It's apache2_invoke's
+ "apache2_invoke dismod" on both removal and purge. It's apache2_invoke's
job to deal with upgrades and it will remember modules it removed during
removal and will reenable them during re-install.
Web Applications:
- Web Application derive the same behavior as modules if the web
- application can be run with a sensible out-of-box configuration, don't
+ Web Applications derive the same behavior as modules if the web
+ application can be run with a sensible out-of-box configuration; don't
enable it otherwise. Likewise, web application should also be disabled
on removal (and on purge anyway), because important files may be missing
(and that's the point of package removal, anyway).
@@ -314,20 +319,20 @@
Only modules are allowed to switch the enabled MPM. Web applications must not
switch the enabled MPM in their maintainer scripts. To actually switch the MPM,
-packagers can use a2query to find out whether it is necessary and eventually
+packagers can use a2query to find out whether it is necessary, and if so, can
switch it by using the corresponding helper function provided in
apache2-maintscript-helper. Do not try to switch the MPM yourself - the helper
-function takes special care not to leave the site back in a state without enabled
+function takes special care not to leave the site in a state without an enabled
MPM, which is a fatal error.
The helper call may fail. Your maintainer script must cope with this
possibility. It is not recommended to make your maintainer script fail if the
MPM could not be changed. Instead emit a warning. You can use the apache2_msg
-function from apache2-maintscript-helper which sill also log to syslog. If you
+function from apache2-maintscript-helper which will also log to syslog. If you
are using debconf anyway you may want to consider using that - but continue
operation. However, make sure you only enable the module in question if the MPM
-was changed successfully. Below you find an example snippet:
+was changed successfully. See below for an example snippet:
if [ -e /usr/share/apache2/apache2-maintscript-helper ] ; then
@@ -350,18 +355,18 @@
5. Tools
========
-This is an overview of tools supplied with the Apache2 package which can assist to
-build web application and module packages.
+This is an overview of tools supplied with the Apache2 package which can assist
+in building web application and module packages.
5.1 apache2-maintscript-helper
------------------------------
The apache2-maintscript-helper is a collection of functions which can be
sourced in maintainer scripts to do required tasks in a simple and
-standardized way. It is NOT a script, it is a library
-(insofar shell functions can be called as such). This is to avoid users to call
-these functions. They are not meant to be used by users. The helper is installed
-within the apache2 binary package. Thus you MUST NOT use any function of it
+standardized way. It is NOT a script; it is a library (insofar as shell
+functions can be libraries). This is to avoid users calling these functions.
+They are not meant to be used by users. The helper is installed within the
+apache2 binary package. Thus you MUST NOT use any function of it
unconditionally, as for both modules and web applications there are use cases
when this package is not added as a dependency. Thus, use it in a protected
conditional like this only:
@@ -375,9 +380,9 @@
restart the web server, switch the MPM in use and similar. Refer to the source
code for detailed interface documentation. When available, please use the
apache2-maintscript-helper instead of calling helper scripts directly, as these
-functions are careful to invoke and use particular helper. Later versions may
-be configurable to allow the administrator to influence which actions are
-preformed.
+functions are careful to invoke and use the appropriate helper. Later versions
+may be configurable to allow the administrator to influence which actions are
+performed.
Always check the return code of the called function to find out whether
something went wrong:
@@ -390,22 +395,23 @@
--------------
dh_apache2 is a debhelper which can be used to install modules, module
-configuration, site configuration and global configuration snippets. It assists
+configuration, site configuration, and global configuration snippets. It assists
you to set appropriate dependencies and maintainer scripts. Refer to
dh_apache2(1) for full usage guidelines.
5.2 a2enmod
-----------
-a2enmod and its special invokations a2enconf, a2ensite, a2dismod, a2dissite and
+a2enmod and its special invocations a2enconf, a2ensite, a2dismod, a2dissite and
a2disconf can be used to enable all types of Apache 2 configuration files. When
invoking these helpers in maintainer scripts, you should carefully check their
-error return codes. These scripts must be used with the -q (quiet) and -m
-(maintainer mide) switches only in maintainer scripts. Preferrably you should not
-interface with this scripts directly, instead it is recommended to use
-apache2-maintscript-helper. For detailed usage refer to their respective man pages.
+error return codes. These scripts must always be used with the -q (quiet) and -m
+(maintainer mode) switches in maintainer scripts. Preferably, you should not
+interface with this scripts directly; instead it is recommended to use
+apache2-maintscript-helper. For detailed usage refer to their respective man
+pages.
-5.3 2query
+5.3 a2query
----------
a2query is a query tool to retrieve runtime status information about the Apache
@@ -415,8 +421,8 @@
files in /etc/apache2 directly as it tries its best to return useful information
even on incomplete or broken configurations.
-For example you can use a2query to retrieve the MPM enabled at the installation
-site and make actions dependent on the result like this:
+For example, you can use a2query to retrieve the MPM enabled on the local site
+and make actions dependent on the result like this:
[ -x /usr/sbin/a2query ] || exit $?
CUR_MPM=$(a2query -M) || exit $?
@@ -426,8 +432,8 @@
...
esac
-Refer to the a2query(1) man page for the full documentation. Please note, the
-apache2-maintscript-helper can be used to inteface with this task as well.
+Refer to the a2query(1) man page for the full documentation. Please note that
+the apache2-maintscript-helper can be used to interface with this task as well.
6 Version
=========
@@ -435,7 +441,7 @@
Document version: 1.0
Starting with Apache2 2.4.2-2 this document is versioned. Any change which affects
-packaging are denoted by an increased major nummer, clarifications, spelling fixes
+packaging is denoted by an increased major nummer; clarifications, spelling fixes
and minor edits are denoted by minor numbers. In future, a changelog will appear
here as well.
@@ -443,4 +449,4 @@
-----------
1.0:
- * first version of this document which is versionated.
+ * first version of this document which is versioned.
--- old/000-default.conf 2012-04-24 13:01:35.739844318 +0100
+++ new/000-default.conf 2012-04-24 13:13:55.179392381 +0100
@@ -4,7 +4,6 @@
# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
# error, crit, alert, emerg.
- # include it only for a particular virtual host. For example the
# It is also possible to configure the loglevel for particular
# modules, e.g.
#LogLevel info ssl:warn
@@ -14,9 +13,9 @@
# For most configuration files from conf-available/, which are
# enabled or disabled at a global level, it is possible to
- # include a it only for a particular virtual host. For example the
- # following line enables the CGI configuration for this host
- # only after disabling it globally with "a2disconf".
+ # include a line for only one particular virtual host. For example the
+ # following line enables the CGI configuration for this host only
+ # after it has been globally disabled with "a2disconf".
#Include conf-available/serve-cgi-bin.conf
</VirtualHost>
--- old/apache2.conf 2012-04-24 13:02:21.659386164 +0100
+++ new/apache2.conf 2012-04-24 13:28:17.163722722 +0100
@@ -5,7 +5,7 @@
# hints.
#
#
-# Summary how the Apache 2 configuration works in Debian:
+# Summary of how the Apache 2 configuration works in Debian:
# The Apache 2 web server configuration in Debian is quite different to
# upstream's suggested way to configure the web server. This is because Debian's
# default Apache2 installation attempts to make adding and removing modules,
@@ -13,7 +13,7 @@
# order to make automating the changes and administering the server as easy as
# possible.
-# It is splitted into several files forming the configuration hierarchy outlined
+# It is split into several files forming the configuration hierarchy outlined
# below, all located in the /etc/apache2/ directory:
#
# /etc/apache2/
@@ -21,14 +21,14 @@
# | `-- ports.conf
# |-- mods-enabled
# | |-- *.load
-# | |-- *.conf
+# | `-- *.conf
# |-- conf-enabled
-# | |-- *.conf
-# |-- sites-enabled
-# | |-- *.conf
+# | `-- *.conf
+# `-- sites-enabled
+# `-- *.conf
#
#
-# * apache2.conf is the main configuration file (this file). It puts all pieces
+# * apache2.conf is the main configuration file (this file). It puts the pieces
# together by including all remaining configuration files when starting up the
# web server.
#
@@ -45,7 +45,7 @@
# helpers a2enmod/a2dismod, a2ensite/a2dissite and a2enconf/a2disconf. See
# their respective man pages for detailed information.
#
-# * The binary is called apache2, Due to the use of environment variables, in
+# * The binary is called apache2. Due to the use of environment variables, in
# the default configuration, apache2 needs to be started/stopped with
# /etc/init.d/apache2 or apache2ctl. Calling /usr/bin/apache2 directly will not
# work with the default configuration.
@@ -80,7 +80,7 @@
PidFile ${APACHE_PID_FILE}
#
-# Timeout: The number of seconds before receives and sends time out.
+# Timeout: The number of seconds to allow before sending a time out.
#
Timeout 300
@@ -144,7 +144,7 @@
# Sets the default security model of the Apache2 HTTPD server. It does
-# not allow access to the root filesystem except of /usr/share and
+# not allow access to the root filesystem outside of /usr/share and
# /var/www. The former is used by web applications packaged in Debian,
# the latter may be used for local directories served by the web server.
<Directory />
--- old/apache2.NEWS 2012-04-24 13:01:50.316079280 +0100
+++ new/apache2.NEWS 2012-04-24 13:34:46.043392384 +0100
@@ -1,42 +1,43 @@
apache2 (2.4.1-1) experimental; urgency=low
This package introduces a new major release of the Apache HTTP server. It is
- likely the site configuration needs changes to work with this release. Notable
- changes which need special care are:
+ likely the site configuration needs changes to work with this release.
+ Notable changes which need special care are:
The module interface (ABI) has changed. If you have any locally compiled
modules, you have to re-compile them for apache2 2.4.
- The authorization and authentication system changed. Existing configurations
- using deprecated Order/Allow/Deny directives should be upgraded to the new
- system. Please review upstream's "Authentication, Authorization and Access
- Control Howto" [1]. However, "mod_access_compat" is loaded by default to
- provide backward compatibility.
-
- Furthermore, MPMs are simple modules now. Thus, the MPM can be changed anytime
- by (un-)loading a specific module. Be careful when upgrading. An example of
- changing the MPM is given below
+ The authorization and authentication system has changed. Existing
+ configurations using deprecated Order/Allow/Deny directives should be
+ upgraded to the new system. Please review upstream's "Authentication,
+ Authorization and Access Control Howto" [1]. However, "mod_access_compat" is
+ loaded by default to provide backward compatibility.
+
+ Furthermore, MPMs are simple modules now. Thus, the MPM can be changed
+ at any time by (un-)loading a specific module. Be careful when upgrading. An
+ example of changing the MPM is given below:
a2dismod mpm_worker
a2enmod mpm_prefork
- Moreover, the configuration mechanism in Debian changed. All configurations
- in sites-enabled and conf-enabled need a ".conf" suffix now. The latter was
- transitioned from the deprecated /etc/apache2/conf.d/ directory which is not
- supported anymore and works just like {sites,mods}-{available,enabled} by
- using the "a2enconf" tool. The upgrade tries to migrate known configuration
+ Moreover, the configuration mechanism in Debian has changed. All
+ configurations in sites-enabled and conf-enabled need a ".conf" suffix now.
+ The latter replaces the deprecated /etc/apache2/conf.d/ directory (which is
+ not supported any more) and works just like {sites,mods}-{available,enabled}
+ via the "a2enconf" tool. The upgrade tries to migrate known configuration
files from /etc/apache2/conf.d/ to /etc/apache2/conf-available/ - please
- review this changes.
- Note this means all existing sites are ignored until they get a ".conf" suffix
- and are being re-enabled by the use of a2ensite. The script in [3] can
+ review these changes.
+
+ Note this means all existing sites are ignored until they get a ".conf"
+ suffix and are re-enabled by the use of a2ensite. The script in [3] can
automate that for simple cases. This change also includes Debian default
- sites, hence the default site was renamed to 000-default to avoid naming
+ sites, so the default site has been renamed to 000-default to avoid naming
confusions. The rename of the config files to *.conf makes the special
- handling inside apache2 to ignore *.dpkg-* backup files obsolete. This special
- handling has been removed.
+ handling inside apache2 to ignore *.dpkg-* backup files obsolete. This
+ special handling has been removed.
- Packagers are advised to review their packages whether they comply with this
- new version. Please see [2] for detailed documentation and instructions
+ Packagers are advised to review whether their packages comply with this
+ new version. Please see [2] for detailed documentation and instructions.
[1] http://httpd.apache.org/docs/2.4/howto/auth.html
[2] </usr/share/doc/apache2/PACKAGING>
--- old/apache2.README.Debian 2012-04-24 13:02:02.771382706 +0100
+++ new/apache2.README.Debian 2012-04-24 17:31:59.315392242 +0100
@@ -2,7 +2,7 @@
========
Apache2 Configuration under Debian GNU/Linux
- Files and Directories in /etc/apache2
+ Files and Directories in '/etc/apache2'
Tools
Using mod_cache_disk
@@ -32,24 +32,24 @@
Please be aware that this layout is quite different from the standard
Apache configuration. Due to the use of environment variables, apache2
-needs to be started/stopped with /etc/init.d/apache2, apachectl, or
-apache2ctl. Calling /usr/bin/apache2 directly will not work with the
+needs to be started/stopped with '/etc/init.d/apache2', apachectl, or
+apache2ctl. Calling '/usr/bin/apache2' directly will not work with the
default configuration. To call apache2 with specific command line
arguments, just call apache2ctl with the same arguments.
-Files and Directories in /etc/apache2:
--------------------------------------
+Files and Directories in '/etc/apache2':
+---------------------------------------
apache2.conf
This is the main configuration file. It does not include any
- actual configuration we expect to be adapted on your site. Thus,
- please do not touch it when possible. This file is the building
- block of the Apache configuration in Debian and should be up to
- date after upgrades to make sure all configuration pieces are
- properly included.
+ actual configuration we expect to be adapted on your site, so
+ where possible please do not touch it. This file is the
+ foundation stone of the Apache configuration in Debian and should
+ be up to date after upgrades to make sure all configuration pieces
+ are properly included.
- If you want to extend the global configuration you can customize
+ If you want to extend the global configuration, you can customize
the Apache web server by including configuration files through the
conf-available mechanism. To change listening ports and socket
configuration use ports.conf (see below).
@@ -70,9 +70,9 @@
configuration. Some settings, like user and pid file, need to
go in here so that other scripts can use them. It can also
be used to change some default settings used by apache2ctl,
- including the ulimit value for the max number of open files.
- Here is also the default LANG=C setting that can be changed
- to a different language.
+ including the ulimit value for the maximum number of open files.
+ The default LANG=C setting is also here, and can be changed to a
+ different language.
conf-available/
@@ -89,7 +89,7 @@
files installed by packages.
Configuration snippets can be enabled and disabled by using the
- a2enconf and a2disconf executables. This works similar to the
+ a2enconf and a2disconf executables. This works similarly to the
approach used for modules and sites below.
Configuration snippets can of course also be included in individual
@@ -105,7 +105,7 @@
This directory contains a series of .load and .conf files.
The .load files contain the Apache configuration directive
- necessary to load the module in question. The respective
+ necessary to load the module in question. The corresponding
.conf files contain configuration directives necessary to
utilize the module in question.
@@ -122,7 +122,7 @@
sites-available/
- Like mods-available/, except it contains configuration
+ Like mods-available/, except that it contains configuration
directives for different virtual hosts that might be used with
apache2. Note that the hostname doesn't have to correspond
exactly with the filename. '000-default.conf' is the default
@@ -132,7 +132,7 @@
Similar in functionality to mods-enabled/, sites-enabled
contains symlinks to sites in sites-available/ that the
- admnistrator wishes to enable.
+ administrator wishes to enable.
Apache uses the first VirtualHost that matches the IP/Port
as default for named virtual hosts. Therefore the 'default'
@@ -145,21 +145,21 @@
The a2ensite helper can be used to enable a site.
The Include directives ignore files with names that do not end with a
-.conf suffix. This behavior changed to previous releases!
+.conf suffix. This behavior has changed from previous releases!
In some cases you may want to enable a specific piece of configuration
(think of files shipped in conf-available/) for a particular virtual
-host only and not globally as our default is. In such cases you can
+host only and not globally as is our default. In such cases you can
disable the configuration at a global scope for example by doing
a2disconf some-configuration
-Then it can be included it in a particular virtual host within a file in
+Then it can be included in a particular virtual host within a file in
sites-enabled/. You may want to add
Include conf-available/some-configuration.conf
-in that site configuration. However, be careful as this may not work for
+in that site configuration. However, be careful, as this may not work for
some configurations, depending on the context and implications of some
directives.
@@ -178,13 +178,13 @@
a2ensite and a2dissite do essentially the same thing as the above tools, but
for sites rather than modules. Finally a2enconf and a2disconf are the
-respective tools for configuration snippets.
+corresponding tools for configuration snippets.
a2query is a helper script providing runtime information about the running
server instance. For example it can be used to query enabled modules, the
-picked MPM and other information. This tool is primarily meant to package
+selected MPM, and other information. This tool is primarily meant for package
maintainers who need to interact with the Apache packages to activate
-their configurations upon package installations, but can be used by users
+their configurations upon package installation, but it can be used by users
as well.
apxs2 -a/-A is modified to use a2enmod to activate newly installed modules.
@@ -195,12 +195,12 @@
To ensure that the disk cache does not grow indefinitely, htcacheclean is
started when mod_cache_disk is enabled. Both daemon and cron (daily) mode
-are supported. The configuration (run mode, cache size, ...) is in
-/etc/default/apache2 .
+are supported. The configuration (run mode, cache size, etc.) is in
+'/etc/default/apache2'.
Normally, htcacheclean is automatically started and stopped by
-/etc/init.d/apache2. However, if you change the state of mod_cache_disk or the
-configuration of htcacheclean while apache2 is running, you may need to
+'/etc/init.d/apache2'. However, if you change the state of mod_cache_disk or
+the configuration of htcacheclean while apache2 is running, you may need to
manually start/stop htcacheclean with "/etc/init.d/apache2 start-htcacheclean"
or "/etc/init.d/apache2 stop-htcacheclean".
@@ -219,15 +219,15 @@
a2enmod ssl
If you want to use self-signed certificates, you should install the ssl-cert
-package (see below). Otherwise, just adjust the SSLCertificateFile and
-SSLCertificateKeyFile directives in /etc/apache2/sites-available/default-ssl.conf
+package (see below). Otherwise, just adjust the SSLCertificateKeyFile and
+SSLCertificateFile directives in '/etc/apache2/sites-available/default-ssl.conf'
to point to your SSL certificate. Then restart apache:
/etc/init.d/apache2 restart
-The SSL key file should only be readable by root, the certificate file may be
+The SSL key file should only be readable by root; the certificate file may be
globally readable. These files are read by the Apache parent process which runs
-as root. Therefore it is not necessary to make the files readable by the
+as root, and it is therefore not necessary to make the files readable by the
www-data user.
Creating self-signed certificates
@@ -235,7 +235,7 @@
If you install the ssl-cert package, a self-signed certificate will be
automatically created using the hostname currently configured on your computer.
-You can recreate that certificate (e.g. after you have changed /etc/hosts or
+You can recreate that certificate (e.g. after you have changed '/etc/hosts' or
DNS to give the correct hostname) as user root with:
make-ssl-cert generate-default-snakeoil --force-overwrite
@@ -245,11 +245,11 @@
make-ssl-cert /usr/share/ssl-cert/ssleay.cnf /path/to/cert-file.crt
This will ask you for the hostname and place both SSL key and certificate in
-the file /path/to/cert-file.crt . Use this file with the SSLCertificateFile
+the file '/path/to/cert-file.crt'. Use this file with the SSLCertificateFile
directive in the Apache config (you don't need the SSLCertificateKeyFile in
-this case as it also contains the key). The file /path/to/cert-file.crt should
-only be readable by root. A good directory to use for the additional
-certificates/keys is /etc/ssl/private .
+this case as it also contains the key). The file '/path/to/cert-file.crt'
+should only be readable by root. A good directory to use for the additional
+certificates/keys is '/etc/ssl/private'.
SSL workaround for MSIE
-----------------------
@@ -263,7 +263,7 @@
downgrade-1.0 force-response-1.0
BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
-The default SSL virtual host in /etc/apache2/sites-available/default-ssl.conf
+The default SSL virtual host in '/etc/apache2/sites-available/default-ssl.conf'
already contains this workaround.
@@ -275,7 +275,7 @@
issues. The package apache2-suexec-pristine contains the standard version
that works only with document root /var/www, userdir suffix public_html,
and Apache run user www-data. The package apache2-suexec-custom contains a
-customizable version, that can be configured with a config file to use
+customizable version that can be configured with a config file to use
different settings (like /srv/www as document root). For more information
see the suexec(8) man page in the apache2-suexec-custom package.
@@ -325,7 +325,7 @@
==================
There is some support for running multiple instances of Apache2 on the same
-machine. See /usr/share/doc/apache2/README.multiple-instances for more
+machine. See '/usr/share/doc/apache2/README.multiple-instances' for more
information.
@@ -337,10 +337,10 @@
This can usually be ignored but it means that Apache httpd was unable to obtain
a fully-qualified hostname by doing a reverse lookup on your server's IP
-address. You may want to add the fully-qualified hostname to /etc/hosts .
+address. You may want to add the fully-qualified hostname to '/etc/hosts'.
An alternative is to specify "ServerName 127.0.0.1" in the global server
context of the configuration, e.g. in
-/etc/apache2/conf-enabled/local-servername.conf .
+'/etc/apache2/conf-enabled/local-servername.conf'.
2) Error message "mod_rewrite: could not create rewrite_log_lock"
@@ -373,14 +373,14 @@
fs.epoll.max_user_instances=1024
-to /etc/sysctl.conf.
+to '/etc/sysctl.conf'.
There are several other error messages related to creating a pollset that can
appear for the same reason.
-On the other hand, errors about to adding to a pollset are related to the
-setting fs.epoll.max_user_watches. On most systems, max_user_watches should be
-high enough by default.
+On the other hand, errors about adding to a pollset are related to the setting
+fs.epoll.max_user_watches. On most systems, max_user_watches should be high
+enough by default.
5) Message "Server should be SSL-aware but has no certificate configured" in
error log
@@ -415,7 +415,7 @@
8) Message "apache2: bad user name ${APACHE_RUN_USER}" when starting apache2
directly
-Use apache2ctl (it accepts all options of apache2).
+Use apache2ctl (it accepts all the same options as apache2).
9) Apache is using a lot of memory and is not freeing it even when idle
@@ -423,7 +423,7 @@
later use.
* Tune StartServers, MaxConnectionsPerChild, MinSpareThreads/MinSpareServers,
- MaxSpareThreads/MaxSpareServers in /etc/apache2/mods-enabled/mpm_*.conf
+ MaxSpareThreads/MaxSpareServers in '/etc/apache2/mods-enabled/mpm_*.conf'
* If you are really starved for memory, try adding 'MaxMemFree 4' to your
Apache configuration. This will reduce Apache's performance.
--- old/control 2012-04-24 13:05:36.327725759 +0100
+++ new/control 2012-04-24 13:36:28.667392490 +0100
@@ -178,8 +178,8 @@
result has long been the number one web server on the Internet.
.
This package provides the documentation for the Apache 2 HTTP server. The
- documentation is shipped in HTML format an can be accessed from a local running
- Apache HTTP server instance or by browsing the file system directly.
+ documentation is shipped in HTML format and can be accessed from a local
+ running Apache HTTP server instance or by browsing the file system directly.
Package: apache2-dev
Architecture: any
Reply to: