From 757f3f7d870d5c4d6c7ed47a4120a9e9348f7ecb Mon Sep 17 00:00:00 2001 From: Luca Toscano Date: Mon, 11 Dec 2017 15:22:20 +0000 Subject: [PATCH] documentation rebuild git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1817786 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/directives.html.en | 6 +- docs/manual/mod/mod_md.html.en | 236 ++++++++++++------------- docs/manual/mod/mod_ssl.html.en | 180 ++++++++++--------- docs/manual/mod/mod_ssl.xml.fr | 2 +- docs/manual/mod/mod_ssl.xml.meta | 2 +- docs/manual/mod/quickreference.html.en | 8 +- docs/manual/sections.html.en | 2 +- docs/manual/sections.xml.fr | 2 +- docs/manual/sections.xml.ja | 2 +- docs/manual/sections.xml.ko | 2 +- docs/manual/sections.xml.meta | 2 +- docs/manual/sections.xml.tr | 2 +- 12 files changed, 226 insertions(+), 220 deletions(-) diff --git a/docs/manual/mod/directives.html.en b/docs/manual/mod/directives.html.en index bd4117fe0e..1f895379a4 100644 --- a/docs/manual/mod/directives.html.en +++ b/docs/manual/mod/directives.html.en @@ -436,8 +436,6 @@
  • <Macro>
  • MacroIgnoreBadNesting
  • MacroIgnoreEmptyArgs
    • -
  • ManagedDomain
    • -
  • <ManagedDomain>
  • MaxConnectionsPerChild
  • MaxKeepAliveRequests
  • MaxMemFree
    • @@ -458,6 +456,8 @@
  • MDMembers
  • MDMustStaple
  • MDNotifyCmd
    • +
  • MDomain
    • +
  • <MDomainSet>
  • MDPortMap
  • MDPrivateKeys
  • MDRenewWindow
    • @@ -691,8 +691,8 @@
  • SSLOpenSSLConfCmd
  • SSLOptions
  • SSLPassPhraseDialog
    • -
  • <SSLPolicy>
  • SSLPolicy
    • +
  • <SSLPolicyDefine>
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
    • diff --git a/docs/manual/mod/mod_md.html.en b/docs/manual/mod/mod_md.html.en index e58acfc89b..23cf66f005 100644 --- a/docs/manual/mod/mod_md.html.en +++ b/docs/manual/mod/mod_md.html.en @@ -56,7 +56,7 @@

    Simple configuration example:

    TLS in a VirtualHost context

    - 
    ManagedDomain example.org
+        
    MDomain example.org
 
 <VirtualHost *:443>
     ServerName example.org
@@ -83,8 +83,6 @@

    Directives

    -
    top
    -

    ManagedDomain Directive

    - - - - - - -
    Description:Define list of domain names that belong to one group.
    Syntax:ManagedDomain dns-name [ other-dns-name... ] [auto|manual]
    Context:server config
    Status:Extension
    Module:mod_md
    -

    - All the names in the list are managed as one Managed Domain (MD). - mod_md will request one single certificate that is valid for all these names. This - directive uses the global settings (see other MD directives below). If you - need specific settings for one MD, use - the <ManagedDomain>. -

    - There are 2 additional settings that are necessary for a Managed Domain: - ServerAdmin - and MDCertificateAgreement. - The mail address of ServerAdmin - is used to register at the CA (Let's Encrypt by default). - The CA may use it to notify you about - changes in its service or status of your certificates. -

    - The second setting, MDCertificateAgreement, - is the URL of the Terms of Service of the CA. When you configure the URL, - you confirm that you have read and agree to the terms described in the linked - document. Before you do that, the CA will not hand out certificates to you. -

    -

    Example

    ServerAdmin mailto:admin@example.org
-MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
-ManagedDomain example.org www.example.org
-
-<VirtualHost *:443>
-    ServerName example.org
-    DocumentRoot htdocs/root
-
-    SSLEngine on
-</VirtualHost>
-
-<VirtualHost *:443>
-    ServerName www.example.org
-    DocumentRoot htdocs/www
-
-    SSLEngine on
-</VirtualHost>
    -
    -

    - There are two special names that you may use in this directive: 'manual' - and 'auto'. This determines if a Managed Domain shall have exactly the - name list as is configured ('manual') or offer more convenience. With 'auto' - all names of a virtual host are added to a MD. Conventiently, 'auto' is also - the default. -

    -

    Example

    ManagedDomain example.org
-
-<VirtualHost *:443>
-    ServerName example.org
-    ServerAlias www.example.org
-    DocumentRoot htdocs/root
-
-    SSLEngine on
-</VirtualHost>
-
-ManagedDomain example2.org auto
-
-<VirtualHost *:443>
-    ServerName example2.org
-    ServerAlias www.example2.org
-    ...
-</VirtualHost>
    -
    -

    - In this example, the domain 'www.example.org' is automatically added to - the MD 'example.org'. Similarly for 'example2.org' where 'auto' is configured - explicitly. Whenever you add more ServerAlias names to this - virtual host, they will be added as well to the Manged Domain. -

    - If you prefer to explicitly declare all the domain names, use 'manual' mode. - An error will be logged if the names do not match with the expected ones. -

    - -
    -
    top
    -

    <ManagedDomain> Directive

    - - - - - - -
    Description:Container for directives applied to the same managed domains.
    Syntax:<ManagedDomain dns-name [ other-dns-name... ]>...</ManagedDomain>
    Context:server config
    Status:Extension
    Module:mod_md
    -

    - This directive allows you to define a Managed Domain (MD) with specific - settings, different from the global MD* ones. For example, you can have - such an MD use another CA then Let's Encrypt, have its unique renewal duration - etc. -

    -

    Example

    <ManagedDomain sandbox.example.org>
-    MDCertificateAuthority   https://someotherca.com/ACME
-    MDCertificateAgreement   https://someotherca.com/terms/v_1.02.pdf
-</ManagedDomain>
    -
    -

    This is a specialized version of ManagedDomain, - it should be used only when a fine grained configuration is required. - ManagedDomain is the suggested choice - for the general use case.

    - -
    top

    MDCAChallenges Directive

    @@ -249,7 +140,7 @@ ManagedDomain example2.org auto

    In case of Let's Encrypt, their current Terms of Service are here. Those terms might (and probably will) change over time. So, the certificate renewal might require you to update this agreement URL.

    Example

    MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
-ManagedDomain example.org www.example.org mail.example.org
    +MDomain example.org www.example.org mail.example.org
    @@ -344,15 +235,15 @@ MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2 MDMember to add such names to a managed domain.

    -

    Example

    <ManagedDomain example.org>
+            
    Example
    <MDomainSet example.org>
     MDMember www.example.org
     MDMember mail.example.org
-</ManagedDomain example.org>
    
+</MDomainSet example.org>

    If you use it in the global context, outside a specific MD, you can only specify one value, 'auto' or 'manual' as the default for all other MDs. See - ManagedDomain for a + MDomain for a description of these special values.

    @@ -406,6 +297,115 @@ MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2 run successfully.

    + +
    top
    +

    MDomain Directive

    +
    + + + + + +
    Description:Define list of domain names that belong to one group.
    Syntax:MDomain dns-name [ other-dns-name... ] [auto|manual]
    Context:server config
    Status:Extension
    Module:mod_md
    +

    + All the names in the list are managed as one Managed Domain (MD). + mod_md will request one single certificate that is valid for all these names. This + directive uses the global settings (see other MD directives below). If you + need specific settings for one MD, use + the <MDomainSet>. +

    + There are 2 additional settings that are necessary for a Managed Domain: + ServerAdmin + and MDCertificateAgreement. + The mail address of ServerAdmin + is used to register at the CA (Let's Encrypt by default). + The CA may use it to notify you about + changes in its service or status of your certificates. +

    + The second setting, MDCertificateAgreement, + is the URL of the Terms of Service of the CA. When you configure the URL, + you confirm that you have read and agree to the terms described in the linked + document. Before you do that, the CA will not hand out certificates to you. +

    +

    Example

    ServerAdmin mailto:admin@example.org
+MDCertificateAgreement https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
+MDomain example.org www.example.org
+
+<VirtualHost *:443>
+    ServerName example.org
+    DocumentRoot htdocs/root
+
+    SSLEngine on
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerName www.example.org
+    DocumentRoot htdocs/www
+
+    SSLEngine on
+</VirtualHost>
    +
    +

    + There are two special names that you may use in this directive: 'manual' + and 'auto'. This determines if a Managed Domain shall have exactly the + name list as is configured ('manual') or offer more convenience. With 'auto' + all names of a virtual host are added to a MD. Conventiently, 'auto' is also + the default. +

    +

    Example

    MDomain example.org
+
+<VirtualHost *:443>
+    ServerName example.org
+    ServerAlias www.example.org
+    DocumentRoot htdocs/root
+
+    SSLEngine on
+</VirtualHost>
+
+MDomain example2.org auto
+
+<VirtualHost *:443>
+    ServerName example2.org
+    ServerAlias www.example2.org
+    ...
+</VirtualHost>
    +
    +

    + In this example, the domain 'www.example.org' is automatically added to + the MD 'example.org'. Similarly for 'example2.org' where 'auto' is configured + explicitly. Whenever you add more ServerAlias names to this + virtual host, they will be added as well to the Manged Domain. +

    + If you prefer to explicitly declare all the domain names, use 'manual' mode. + An error will be logged if the names do not match with the expected ones. +

    + +
    +
    top
    +

    <MDomainSet> Directive

    + + + + + + +
    Description:Container for directives applied to the same managed domains.
    Syntax:<MDomainSet dns-name [ other-dns-name... ]>...</MDomainSet>
    Context:server config
    Status:Extension
    Module:mod_md
    +

    + This directive allows you to define a Managed Domain (MD) with specific + settings, different from the global MD* ones. For example, you can have + such an MD use another CA then Let's Encrypt, have its unique renewal duration + etc. +

    +

    Example

    <MDomainSet sandbox.example.org>
+    MDCertificateAuthority   https://someotherca.com/ACME
+    MDCertificateAgreement   https://someotherca.com/terms/v_1.02.pdf
+</MDomainSet>
    +
    +

    This is a specialized version of MDomain, + it should be used only when a fine grained configuration is required. + MDomain is the suggested choice + for the general use case.

    +
    top

    MDPortMap Directive

    @@ -556,9 +556,9 @@ MDRenewWindow 10%

    If you set this globally, it applies to all managed domains. If you want it for a specific domain only, use:

    -

    Example

    <ManagedDomain xxx.yyy>
+            
    Example
    <MDomainSet xxx.yyy>
   MDRequireHttps temporary
-</ManagedDomain>
    
+</MDomainSet>
    diff --git a/docs/manual/mod/mod_ssl.html.en b/docs/manual/mod/mod_ssl.html.en index 7b421651d7..af92141517 100644 --- a/docs/manual/mod/mod_ssl.html.en +++ b/docs/manual/mod/mod_ssl.html.en @@ -84,8 +84,8 @@ to provide the cryptography engine.

  • SSLOpenSSLConfCmd
  • SSLOptions
  • SSLPassPhraseDialog
    • -
  • <SSLPolicy>
  • SSLPolicy
    • +
  • <SSLPolicyDefine>
  • SSLProtocol
  • SSLProxyCACertificateFile
  • SSLProxyCACertificatePath
    • @@ -961,7 +961,7 @@ SSLCryptoDevice ubsec Context:server config, virtual host Status:Extension Module:mod_ssl -Compatibility:The addr:port parameter is available in Apache 2.4.28 and later. +Compatibility:The addr:port parameter is available in Apache 2.4.30 and later.

    This directive toggles the usage of the SSL/TLS Protocol Engine. Values 'on', @@ -1472,27 +1472,95 @@ query can be done in two ways which can be configured by

    top
    -

    <SSLPolicy> Directive

    +

    SSLPolicy Directive

    + + + + + + + +
    Description:Apply a SSLPolicy by name
    Syntax:SSLPolicy name
    Context:server config, virtual host
    Status:Extension
    Module:mod_ssl
    Compatibility:Available in httpd 2.4.30 and later
    +

    This directive applies the set of SSL* directives defined +under 'name' (see <SSLPolicyDefine>) as the base +settings in the current context. Apache comes with the following pre-defined policies from +Mozilla, the makers of the Firefox browser +(see here +for a detailed description by them.): +

    +
      +
    • modern: recommended when your server is accessible on the open Internet. Works with all modern browsers, but old devices might be unable to connect.
      • +
    • intermediate: the fallback if you need to support old (but not very old) clients.
      • +
    • old: when you need to give Windows XP/Internet Explorer 6 access. The last resort.
      • +
    + +

    You can check the detailed description of all defined policies via the command line:

    +

    List all Defined Policies

    httpd -t -D DUMP_SSL_POLICIES
    +
    + +

    A SSLPolicy defines the baseline for the context it is used in. That means that any +other SSL* directives in the same context override it. As an example of this, see the effective +SSLProtocol value in the following settings:

    + +

    Policy Precedence

    <VirtualHost...> # effective: 'all'
+   SSLPolicy modern
+   SSLProtocol all
+</VirtualHost>
+
+<VirtualHost...> # effective: 'all'
+   SSLProtocol all
+   SSLPolicy modern
+</VirtualHost>
+
+SSLPolicy modern
+<VirtualHost...> # effective: 'all'
+   SSLProtocol all
+</VirtualHost>
+   
+SSLProtocol all
+<VirtualHost...> # effective: '+TLSv1.2'
+  SSLPolicy modern
+</VirtualHost>
    +
    + +

    There can be more than one policy applied in a context. The +later ones overshadowing the earlier ones:

    + +

    Policy Ordering

    <VirtualHost...> # effective protocol: 'all -SSLv3'
+   SSLPolicy modern
+   SSLPolicy intermediate
+</VirtualHost>
+
+<VirtualHost...> # effective protocol: '+TLSv1.2'
+   SSLPolicy intermediate
+   SSLPolicy modern
+</VirtualHost>
    +
    + + +
    +
    top
    +

    <SSLPolicyDefine> Directive

    - +
    Description:Define a named set of SSL configurations
    Syntax:<SSLPolicy name>
    Context:server config
    Status:Extension
    Module:mod_ssl
    Compatibility:Available in httpd 2.4.28 and later
    Compatibility:Available in httpd 2.4.30 and later

    This directive defines a set of SSL* configurations under and gives it a name. This name can be used in the directives SSLPolicy and SSLProxyPolicy to apply this configuration set in the current context.

    -

    Define and Use of a Policy

    <SSLPolicy safe-stapling>
+
    Define and Use of a Policy
    <SSLPolicyDefine safe-stapling>
    SSLUseStapling on
    SSLStaplingResponderTimeout 2
    SSLStaplingReturnResponderErrors off
    SSLStaplingFakeTryLater off
    SSLStaplingStandardCacheTimeout 86400
-</SSLPolicy>
+</SSLPolicyDefine>
 
    ...
    <VirtualHost...>
@@ -1515,17 +1583,23 @@ detailed configurations each policy is made of:
    
 
    List all Defined Policies
    httpd -t -D DUMP_SSL_POLICIES
    
 
    
 
-
    The directive can only be used in the server config (global context), so 
-there cannot be two policies with the same name. However, policies can
+
    The directive can only be used in the server config (global context). It can take
+most SSL* directives, however a few can only be set once and are not allowed inside
+policy defintions. These are SSLCryptoDevice, 
+SSLRandomSeed, 
+SSLSessionCache and 
+SSLStaplingCache.
+
    
+
    Two policies cannot have the same name. However, policies can
 be redefined:
    
 
-
    Policy Overwrite
    <SSLPolicy proxy-trust>
+
    Policy Overwrite
    <SSLPolicyDefine proxy-trust>
    SSLProxyVerify require
-</SSLPolicy>
+</SSLPolicyDefine>
    ...
-<SSLPolicy proxy-trust>
+<SSLPolicyDefine proxy-trust>
    SSLProxyVerify none
-</SSLPolicy>
    
+</SSLPolicyDefine>
    
 
    
 
 
    Policy definitions are added in the order they appear, but are
@@ -1537,14 +1611,14 @@ without the need to disable them.
    
 
    Additional to replacing policies, redefinitions may just alter
 an aspect of a policy:
    
 
-
    Policy Redefine
    <SSLPolicy proxy-trust>
+
    Policy Redefine
    <SSLPolicyDefine proxy-trust>
    SSLProxyVerify require
-</SSLPolicy>
+</SSLPolicyDefine>
    ...
-<SSLPolicy proxy-trust>
+<SSLPolicyDefine proxy-trust>
    SSLPolicy proxy-trust
    SSLProxyVerifyDepth 10
-</SSLPolicy>
    
+</SSLPolicyDefine>
    
 
    
 
 
    This re-uses all settings from the previous 'proxy-trust' and adds
@@ -1556,78 +1630,10 @@ be setup like this:
    
 
 
    Tweak a Pre-Defined Policy
    Include ssl-policies.conf
 
-<SSLPolicy modern>
+<SSLPolicyDefine modern>
    SSLPolicy modern
    SSLProxyVerify none
-</SSLPolicy>
    
-
    
-
-
-
    
-
    top
    
-
    SSLPolicy Directive
    
-
-
-
-
-
-
-
-
    Description:Apply a SSLPolicy by name
    Syntax:SSLPolicy name
    Context:server config, virtual host
    Status:Extension
    Module:mod_ssl
    Compatibility:Available in httpd 2.4.28 and later
    
-
    This directive applies the set of SSL* directives defined
-under 'name' (see <SSLPolicy>) as the base
-settings in the current context. Apache comes with the following pre-defined policies from 
-Mozilla, the makers of the Firefox browser 
-(see here
-for a detailed description by them.):
-
    
-
      
-    
    • modern: recommended when your server is accessible on the open Internet. Works with all modern browsers, but old devices might be unable to connect.
      • 
-    
    • intermediate: the fallback if you need to support old (but not very old) clients.
      • 
-    
    • old: when you need to give Windows XP/Internet Explorer 6 access. The last resort.
      • 
-
    
-
-
    You can check the detailed description of all defined policies via the command line:
    
-
    List all Defined Policies
    httpd -t -D DUMP_SSL_POLICIES
    
-
    
-
-
    A SSLPolicy defines the baseline for the context it is used in. That means that any 
-other SSL* directives in the same context override it. As an example of this, see the effective
-SSLProtocol value in the following settings:
    
-
-
    Policy Precedence
    <VirtualHost...> # effective: 'all'
-   SSLPolicy modern
-   SSLProtocol all
-</VirtualHost>
-
-<VirtualHost...> # effective: 'all'
-   SSLProtocol all
-   SSLPolicy modern
-</VirtualHost>
-
-SSLPolicy modern
-<VirtualHost...> # effective: 'all'
-   SSLProtocol all
-</VirtualHost>
-   
-SSLProtocol all
-<VirtualHost...> # effective: '+TLSv1.2'
-  SSLPolicy modern
-</VirtualHost>
    
-
    
-
-
    There can be more than one policy applied in a context. The
-later ones overshadowing the earlier ones:
    
-
-
    Policy Ordering
    <VirtualHost...> # effective protocol: 'all -SSLv3'
-   SSLPolicy modern
-   SSLPolicy intermediate
-</VirtualHost>
-
-<VirtualHost...> # effective protocol: '+TLSv1.2'
-   SSLPolicy intermediate
-   SSLPolicy modern
-</VirtualHost>
    
+</SSLPolicyDefine>
    @@ -2045,7 +2051,7 @@ directory contains the appropriate symbolic links.

    Context:server config, virtual host Status:Extension Module:mod_ssl -Compatibility:Available in httpd 2.4.28 and later +Compatibility:Available in httpd 2.4.30 and later

    This directive is similar to SSLPolicy, but applies only the SSLProxy* directives defined in the policy. This helps diff --git a/docs/manual/mod/mod_ssl.xml.fr b/docs/manual/mod/mod_ssl.xml.fr index 6c6dc63191..78897461bf 100644 --- a/docs/manual/mod/mod_ssl.xml.fr +++ b/docs/manual/mod/mod_ssl.xml.fr @@ -1,7 +1,7 @@ - + - + + + +