From 4f1b45df4eb1ba43176e98615d30dcca3c5d5fbb Mon Sep 17 00:00:00 2001 From: Jeff Trawick Date: Sun, 13 Mar 2016 15:31:15 +0000 Subject: [PATCH] make docs git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1734819 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/howto/access.html.fr | 2 + docs/manual/howto/http2.html.en | 176 +++++++++++++++++- docs/manual/mod/mod_authz_host.html.en | 25 ++- docs/manual/mod/mod_authz_host.html.fr | 2 + docs/manual/mod/mod_authz_host.xml.fr | 2 +- docs/manual/mod/mod_authz_host.xml.meta | 2 +- docs/manual/mod/mod_include.html.en | 20 +- docs/manual/mod/mod_include.xml.ja | 2 +- docs/manual/mod/mod_ssl.html.en | 42 +++-- docs/manual/mod/quickreference.html.de | 2 +- docs/manual/mod/quickreference.html.en | 2 +- docs/manual/mod/quickreference.html.es | 2 +- docs/manual/mod/quickreference.html.ja.utf8 | 2 +- docs/manual/mod/quickreference.html.ko.euc-kr | 2 +- docs/manual/mod/quickreference.html.tr.utf8 | 2 +- .../manual/mod/quickreference.html.zh-cn.utf8 | 2 +- 16 files changed, 247 insertions(+), 40 deletions(-) diff --git a/docs/manual/howto/access.html.fr b/docs/manual/howto/access.html.fr index 0c9d43e20e..e676275eb6 100644 --- a/docs/manual/howto/access.html.fr +++ b/docs/manual/howto/access.html.fr @@ -26,6 +26,8 @@

Langues Disponibles:  en  |  fr 

+
Cette traduction peut être périmée. Vérifiez la version + anglaise pour les changements récents.

Le contrôle d'accès fait référence à tout concept de contrôle d'accès à une ressource quelconque. Il est distinct du processus d'authentification et d'autorisation.

diff --git a/docs/manual/howto/http2.html.en b/docs/manual/howto/http2.html.en index de927bd6fb..5823a7f579 100644 --- a/docs/manual/howto/http2.html.en +++ b/docs/manual/howto/http2.html.en @@ -30,39 +30,195 @@  tr 

-

This howto is still a work in progress! Please do not trust completely the following information until the work is finished.

+

This is the howto guide for the HTTP/2 implementation in Apache httpd. This + feature is experimental and you may expect interfaces and directives to + change between releases. +

See also

top

The HTTP/2 protocol

-

This section should contain an overview of the protocol and links to official docs.

+

HTTP/2 is the evolution of the world's most successful application layer protocol, HTTP. + It focuses on making more efficient use of network resources. It does not change the fundamentals + of HTTP, the semantics. There are still request and responses and headers and all that. So, if + you already know HTTP/1, you know 95% about HTTP/2 as well.

+

There has been a lot written about HTTP/2 and how it works. The most normative is, of course, + its RFC 7540 + (also available in more readable formatting, YMMV). + So, there you'll find the nuts and bolts.

+

But, as RFC do, it's not really a good thing to read first. It's better to first understand + what a thing wants to do and then read the RFC about how it is done. A much + better document to start with is http2 explained + by Daniel Stenberg, the author of curl. It is available in + an ever growing list of languages, too!

+
top
+
+

HTTP/2 in Apache httpd

+ +

The HTTP/2 protocol is implemented by its own httpd module, aptly named + mod_http2. It implements the complete set + of features described by RFC 7540 and supports HTTP/2 over cleartext (http:), as + well as secure (https:) connections. The cleartext variant is named 'h2c', + the secure one 'h2'. For h2c it allows the direct + mode and the Upgrade: via an initial HTTP/1 request.

+

One feature of HTTP/2 that offers new capabilities for web developers is + Server Push. See that section on how your web application + can make use of it.

top

Build httpd with HTTP/2 support

-

This section should contain info about how to build HTTP/2 support into httpd plus other requirements.

+

mod_http2 uses the library of nghttp2 + as its implementation base. In order to build mod_http2 you need at least version 1.2.1 of + libnghttp2 installed on your system.

+

When you ./configure you Apache httpd source tree, you need to give it + '--enable-http2' as additional argument to trigger the build of the module. + Should your libnghttp2 reside in an unusual place (whatever that is on your + operating system), you may announce its location with '--with-nghttp2=<path>' + to configure.

+

While that should do the trick for most, they are people who might prefer a statically + linked nghttp2 in this module. For those, the option --enable-nghttp2-staticlib-deps + exists. It works quite similar to how one statically links openssl to mod_ssl.

+

Speaking of SSL, you need to be aware that most browsers will speak HTTP/2 only on https: + URLs, so you need a server with SSL support. But not only that, you will need a SSL library + that supports the ALPN extension. If OpenSSL is the library you use, you need + at least version 1.0.2.

top
-

Configurations

+

Basic Configuration

+ + +

When you have a httpd built with mod_http2 you need some + basic configuration for it becoming active. The first thing, as with every Apache module, + is that you need to load it:

+ 
LoadModule http2_module modules/mod_http2.so
+ -

This section should contain various configuration examples for HTTP/2 (h2, h2c, etc..) plus common pitfalls (for example not setting a strong TLS cipher suite with h2).

+

The second directive you need to add to your server configuration is

+ 
Protocols h2 http/1.1
+ +

This allows h2, the secure variant, to be the preferred protocol on your server + connections. When you want to enable all HTTP/2 variants, you simply write:

+ 
Protocols h2 h2c http/1.1
+ +

Depending on where you put this directive, it affects all connections or just + the ones to a certain virtual host. You can nest it, as in:

+ 
Protocols http/1.1
+<VirtualHost ...>
+    ServerName test.example.org
+    Protocols h2 http/1.1
+</VirtualHost>
+ + +

This allows only HTTP/1 on connections, except SSL connections to test.example.org + which offer HTTP/2.

+

The order of protocols mentioned is also relevant. By default, the first one is the + most peferred protocol. When a client offers multiple choices, the one most to the + left is selected. In

+ 
Protocols http/1.1 h2
+ +

the most preferred protocol is HTTP/1 and it will always be selected unless a + client only supports h2. Since we want to talk HTTP/2 to clients that + support it, the better order is

+ 
Protocols h2 h2c http/1.1
+ + +

There is one more thing to ordering: the client has its own preferences, too. If + you want, you can configure your server to select the protocol most preferred by + the client:

+ 
ProtocolsHonorOrder Off
+ +

makes the order you wrote the Protocols irrelevant and only the client's + ordering will decide.

+

A last thing: the protocols you configure are not checked for correctness + or spelling. You can mention protocols that do not exist, so there is no need + to guard Protocols with any IfModule checks.

+

For more advanced tips on configuration, see the + modules section about dimensioning and + how to manage multiple hosts with the same certificate.

top
-

Browsers

+

Clients

-

Browser support.

+

Almost all modern browsers support HTTP/2, but only over SSL connections: Firefox (v43), + Chrome (v45), Safari (since v9), iOS Safari (v9), Opera (v35), Chrome for Android (v49) + and Internet Explorer (v11 on Windows10) (source).

+

Other clients, as well as servers, are listed + on the Implementations wiki, + among them implementations for c, c++, common lisp, dart, erlang, haskell, java, nodejs, php, + python, perl, ruby, rust, scala and swift.

+

Several of the non-browser client implementations support HTTP/2 over cleartext, h2c. The + most versatile being curl.

top

Useful tools to debug HTTP/2

-

This section should contain examples of tools to test/debug HTTP/2 connections.

+

curl.

+

And for really deep inspection wireshark.

+

The nghttp2 package also includes clients, such as + nghttp and h2load, the latter one being very useful in putting + some stress on your server.

+

Chrome offers also detailed HTTP/2 logs on its connections via the + special net-internals page.

+
top
+
+

Server Push

+ +

The HTTP/2 protocol allows the server to PUSH responses to a client it never + asked for. The tone of the conversation is: "here is a request that you + never sent and the response to it will arrive soon..."

+

But there are restrictions: the client can disable this feature and the + server may only ever PUSH on a request that came from the client.

+

The intention is to allow the server to send resources to the clien that + it will most likely need: a css or javascript resource that belongs to a html + page the client requested. A set of images that is referenced by a css, etc.

+

The advantage for the client is that it saves the time to send the request which + may range from a few milli seconds to half a second, depending on where on the + globe both are located. The disadvantage is that the client may get sent + things it already has in its cache. Sure, HTTP/2 allows for the early cancellation + of such requests, but still there are resources wasted.

+

To summarize: there is no one good strategy on how to make best use of this + feature of HTTP/2 and everyone is still experimenting. So, how do you experiment + with it in Apache httpd?

+

mod_http2 inspect response header for Link headers + in a certain format:

+ 
Link </xxx.css>;rel=preload, </xxx.js>; rel=preload
+ +

If the connection supports PUSH, these two resources will be sent to the + client. As a web developer, you may set these headers either directly in + your application response or you configure the server via

+ 
<Location /xxx.html>
+    Header add Link "</xxx.css>;rel=preload"
+    Header add Link "</xxx.js>;rel=preload"
+</Location>
+ +

If you want to use preload links without triggering a PUSH, you + can use the nopush parameter, as in

+ 
Link </xxx.css>;rel=preload;nopush
+ +

or you may disable PUSHes for your server entirely with the directive

+ 
H2Push Off
+ +

And there is more:

+

The module will keep a diary of what has been PUSHed for each connection + (hashes of URLs, basically) and will not PUSH the same resource twice. When + the connection closes, this information is discarded.

+

There are people thinking about how a client can tell a server what it + already has, so PUSHes for those things can be avoided, but this is all + highly experimental right now.

+

Another experimental draft that has been implemented in mod_http2 + is the + Accept-Push-Policy Header Field where a client can, for each request, define + what kind of PUSHes it accepts.

Available Languages:  en  | diff --git a/docs/manual/mod/mod_authz_host.html.en b/docs/manual/mod/mod_authz_host.html.en index f85896b553..3f6f9606c6 100644 --- a/docs/manual/mod/mod_authz_host.html.en +++ b/docs/manual/mod/mod_authz_host.html.en @@ -73,7 +73,8 @@ address)

Apache's Require directive is used during the authorization phase to ensure that a user is allowed or denied access to a resource. mod_authz_host extends the - authorization types with ip, host and local. + authorization types with ip, host, + forward-dns and local. Other authorization types may also be used but may require that additional authorization modules be loaded.

@@ -165,6 +166,28 @@ Require host .net example.edu +

Require forward-dns

+ +

The forward-dns provider allows access to the server + to be controlled based on simple host names. When + Require forward-dns host-name is specified, + all IP addresses corresponding to host-name + are allowed access.

+ +

In contrast to the host provider, this provider does not + rely on reverse DNS lookups: it simply queries the DNS for the host name + and allows a client if its IP matches. As a consequence, it will only + work with host names, not domain names. However, as the reverse DNS is + not used, it will work with clients which use a dynamic DNS service.

+ + 
Require forward-dns bla.example.org
+ + +

A client the IP of which is resolved from the name + bla.example.org will be granted access.

+ + +

Require local

The local provider allows access to the server if any diff --git a/docs/manual/mod/mod_authz_host.html.fr b/docs/manual/mod/mod_authz_host.html.fr index 22d9d59ba3..b5b1ebdd1b 100644 --- a/docs/manual/mod/mod_authz_host.html.fr +++ b/docs/manual/mod/mod_authz_host.html.fr @@ -29,6 +29,8 @@

Langues Disponibles:  en  |  fr 

+
Cette traduction peut être périmée. Vérifiez la version + anglaise pour les changements récents.
diff --git a/docs/manual/mod/mod_authz_host.xml.fr b/docs/manual/mod/mod_authz_host.xml.fr index 7178097fee..b5e648ddc8 100644 --- a/docs/manual/mod/mod_authz_host.xml.fr +++ b/docs/manual/mod/mod_authz_host.xml.fr @@ -1,7 +1,7 @@ - + diff --git a/docs/manual/mod/mod_authz_host.xml.meta b/docs/manual/mod/mod_authz_host.xml.meta index 2df68a979b..c67d019aa9 100644 --- a/docs/manual/mod/mod_authz_host.xml.meta +++ b/docs/manual/mod/mod_authz_host.xml.meta @@ -8,6 +8,6 @@ en - fr + fr diff --git a/docs/manual/mod/mod_include.html.en b/docs/manual/mod/mod_include.html.en index 0c6802bbca..1f0b69d097 100644 --- a/docs/manual/mod/mod_include.html.en +++ b/docs/manual/mod/mod_include.html.en @@ -560,10 +560,22 @@ AddOutputFilter INCLUDES .shtml the user.
QUERY_STRING_UNESCAPED
-
If a query string is present, this variable contains the - (%-decoded) query string, which is escaped for shell - usage (special characters like & etc. are - preceded by backslashes).
+
If a query string is present in the request for the active + SSI document, this variable contains the (%-decoded) query + string, which is escaped for shell usage (special + characters like & etc. are preceded by + backslashes). It is not set if a query string is not + present. Use DOCUMENT_ARGS if shell escaping + is not desired.
+ +
DOCUMENT_ARGS
+
This variable contains the query string of the active SSI + document, or the empty string if a query string is not + included. For subrequests invoked through the + include SSI directive, QUERY_STRING + will represent the query string of the subrequest and + DOCUMENT_ARGS will represent the query string of + the SSI document.
top
diff --git a/docs/manual/mod/mod_include.xml.ja b/docs/manual/mod/mod_include.xml.ja index 726e24953e..0f4fa632b0 100644 --- a/docs/manual/mod/mod_include.xml.ja +++ b/docs/manual/mod/mod_include.xml.ja @@ -1,7 +1,7 @@ - +
Description:Autorisations de groupe basées sur l'hôte (nom ou adresse IP)
Statut:Base