Changeset 5f15295 in mod_gnutls for doc/mod_gnutls_manual.mdwn


Ignore:
Timestamp:
Oct 2, 2018, 12:40:20 PM (14 months ago)
Author:
Fiona Klute <fiona.klute@…>
Branches:
debian/master, master
Children:
469861a
Parents:
1a3068c
Message:

Update configuration examples

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/mod_gnutls_manual.mdwn

    r1a3068c r5f15295  
    535535
    536536The default should be reasonable for most servers and requires
    537 `mod_socache_shmcb` to be loaded. Servers with very many virtual hosts
    538 may need to increase the default cache size via the parameters string,
    539 those with few virtual hosts and constrains could save a few KB by
    540 reducing it. Note that `mod_socache_dbm` has a size constraint for
    541 entries that is generally too small for OCSP responses.
     537[mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
     538to be loaded. Servers with very many virtual hosts may need to
     539increase the default cache size via the parameters string, those with
     540few virtual hosts and memory constraints could save a few KB by reducing
     541it. Note that `mod_socache_dbm` has a size constraint for entries that
     542is generally too small for OCSP responses.
    542543
    543544If the selected cache implementation is not thread-safe, access
     
    691692======================
    692693
    693 Simple Standard TLS Example
    694 ---------------------------
    695 
    696 The following is an example of simple TLS hosting, using one IP
    697 Addresses for each virtual host.
     694Minimal Example
     695---------------
     696
     697A minimal server configuration using mod_gnutls might look like this
     698(other than the default setup):
     699
     700     # Load mod_gnutls into Apache.
     701     LoadModule gnutls_module modules/mod_gnutls.so
     702
     703         Listen 192.0.2.1:443
     704
     705     <VirtualHost _default_:443>
     706             # Standard virtual host stuff
     707         DocumentRoot /www/site1.example.com/html
     708         ServerName site1.example.com:443
     709         
     710                 # Minimal mod_gnutls setup: enable, and set credentials
     711                 GnuTLSEnable on
     712         GnuTLSCertificateFile conf/tls/site1_cert_chain.pem
     713         GnuTLSKeyFile conf/tls/site1_key.pem
     714     </VirtualHost>
     715
     716This gives you an HTTPS site using the GnuTLS `NORMAL` set of
     717ciphersuites. OCSP stapling will be enabled if the server certificate
     718contains an OCSP URI, `conf/tls/site1_cert_chain.pem` contains the
     719issuer certificate in addition to the server's, and
     720[mod\_socache\_shmcb](http://httpd.apache.org/docs/current/en/mod/mod_socache_shmcb.html)
     721is loaded. With Gnutls 3.6.4 or newer session tickets are enabled,
     722too.
     723
     724Virtual Hosts with Server Name Indication
     725-----------------------------------------
     726
     727`mod_gnutls` supports "Server Name Indication", as specified in [RFC
     7286066, Section 3](https://tools.ietf.org/html/rfc6066#section-3). This
     729allows hosting many TLS websites with a single IP address, you can
     730just add the virtual host conigurations. All recent browsers support
     731this standard. Here is an example using SNI:
    698732
    699733     # Load the module into Apache.
    700734     LoadModule gnutls_module modules/mod_gnutls.so
     735         # This example server uses session tickets, no cache.
     736     GnuTLSSessionTickets on
     737
     738     # SNI allows hosting multiple sites using one IP address. This
     739     # could also be 'Listen *:443', just like '*:80' is common for
     740     # non-HTTPS
     741     Listen 198.51.100.1:443
     742
     743     <VirtualHost _default_:443>
     744         GnuTLSEnable on
     745         DocumentRoot /www/site1.example.com/html
     746         ServerName site1.example.com:443
     747         GnuTLSCertificateFile conf/tls/site1.crt
     748         GnuTLSKeyFile conf/tls/site1.key
     749     </VirtualHost>
     750
     751     <VirtualHost _default_:443>
     752         GnuTLSEnable on
     753         DocumentRoot /www/site2.example.com/html
     754         ServerName site2.example.com:443
     755         GnuTLSCertificateFile conf/tls/site2.crt
     756         GnuTLSKeyFile conf/tls/site2.key
     757     </VirtualHost>
     758
     759     <VirtualHost _default_:443>
     760         GnuTLSEnable on
     761         DocumentRoot /www/site3.example.com/html
     762         ServerName site3.example.com:443
     763         GnuTLSCertificateFile conf/tls/site3.crt
     764         GnuTLSKeyFile conf/tls/site3.key
     765     </VirtualHost>
     766
     767Virtual Hosts without SNI
     768-------------------------
     769
     770If you need to support clients that do not use SNI, you have to use a
     771unique IP address/port combination for each virtual host. In this
     772example all virtual hosts use the default port for HTTPS (443) and
     773different IP addresses.
     774
     775     # Load the module into Apache.
     776     LoadModule gnutls_module modules/mod_gnutls.so
     777         # This example server uses a session cache.
    701778     GnuTLSCache dbm:/var/cache/www-tls-cache
    702      GnuTLSCacheTimeout 500
    703 
    704      # Without SNI you need one IP Address per-site.
     779     GnuTLSCacheTimeout 1200
     780
     781     # Without SNI you need one IP Address per site. The IP addresses
     782         # are listed separately for clarity, you could also use "Listen 443"
     783         # to use that port on all available IP addresses.
    705784     Listen 192.0.2.1:443
    706785     Listen 192.0.2.2:443
    707786     Listen 192.0.2.3:443
    708      Listen 192.0.2.4:443
    709787
    710788     <VirtualHost 192.0.2.1:443>
     
    740818     </VirtualHost>
    741819
    742      <VirtualHost 192.0.2.4:443>
    743          GnuTLSEnable on
    744          # %COMPAT disables some security features to enable maximum
    745          # compatibility with clients. Don't use this if you need strong
    746          # security.
    747          GnuTLSPriorities NORMAL:%COMPAT
    748          DocumentRoot /www/site4.example.com/html
    749          ServerName site4.example.com:443
    750          GnuTLSCertificateFile conf/tls/site4.crt
    751          GnuTLSKeyFile conf/tls/site4.key
    752      </VirtualHost>
    753 
    754 Server Name Indication Example
    755 ------------------------------
    756 
    757 `mod_gnutls` supports "Server Name Indication", as specified in
    758 [RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3). This
    759 allows hosting many TLS websites with a single IP address. All recent
    760 browsers support this standard. Here is an example using SNI:
     820OCSP Stapling Example
     821---------------------
     822
     823This is an example with a customized OCSP stapling configuration. What
     824is a resonable cache timeout varies depending on how long your CA's
     825OCSP responses are valid. Some CAs provide responses that are valid
     826for multiple days, in that case timeout and fuzz time could be
     827significantly larger.
    761828
    762829     # Load the module into Apache.
    763830     LoadModule gnutls_module modules/mod_gnutls.so
    764 
    765      # SNI allows hosting multiple sites using one IP address. This
    766      # could also be 'Listen *:443', just like '*:80' is common for
    767      # non-HTTPS
    768      Listen 198.51.100.1:443
     831         # A 64K cache is more than enough for one response
     832     GnuTLSOCSPCache shmcb:ocsp_cache(65536)
     833
     834     Listen 192.0.2.1:443
    769835
    770836     <VirtualHost _default_:443>
    771          GnuTLSEnable on
    772          GnuTLSSessionTickets on
    773          DocumentRoot /www/site1.example.com/html
    774          ServerName site1.example.com:443
    775          GnuTLSCertificateFile conf/tls/site1.crt
    776          GnuTLSKeyFile conf/tls/site1.key
    777      </VirtualHost>
    778 
    779      <VirtualHost _default_:443>
    780          GnuTLSEnable on
    781          DocumentRoot /www/site2.example.com/html
    782          ServerName site2.example.com:443
    783          GnuTLSCertificateFile conf/tls/site2.crt
    784          GnuTLSKeyFile conf/tls/site2.key
    785      </VirtualHost>
    786 
    787      <VirtualHost _default_:443>
    788          GnuTLSEnable on
    789          DocumentRoot /www/site3.example.com/html
    790          ServerName site3.example.com:443
    791          GnuTLSCertificateFile conf/tls/site3.crt
    792          GnuTLSKeyFile conf/tls/site3.key
    793      </VirtualHost>
    794 
    795      <VirtualHost _default_:443>
    796          GnuTLSEnable on
    797          DocumentRoot /www/site4.example.com/html
    798          ServerName site4.example.com:443
    799          GnuTLSCertificateFile conf/tls/site4.crt
    800          GnuTLSKeyFile conf/tls/site4.key
    801      </VirtualHost>
    802 
    803 OCSP Stapling Example
    804 ---------------------
    805 
    806 This example uses an X.509 server certificate. The server will fetch
    807 OCSP responses from the responder listed in the certificate and store
    808 them im a memcached cache shared with another server.
    809 
    810      # Load the module into Apache.
    811      LoadModule gnutls_module modules/mod_gnutls.so
    812      GnuTLSCache memcache:192.0.2.1:11211,192.0.2.2:11211
    813      GnuTLSCacheTimeout 600
    814 
    815      Listen 192.0.2.1:443
    816 
    817      <VirtualHost _default_:443>
    818          GnuTLSEnable          On
    819          DocumentRoot          /www/site1.example.com/html
    820          ServerName            site1.example.com:443
    821          GnuTLSCertificateFile conf/tls/site1.crt
    822          GnuTLSKeyFile         conf/tls/site1.key
    823          GnuTLSOCSPStapling    On
     837         GnuTLSEnable           On
     838         DocumentRoot           /www/site1.example.com/html
     839         ServerName             site1.example.com:443
     840         GnuTLSCertificateFile  conf/tls/site1_cert_chain.pem
     841         GnuTLSKeyFile          conf/tls/site1_key.pem
     842         GnuTLSOCSPStapling     On
     843                 # The cached OCSP response is kept for up to 4 hours,
     844                 # with updates scheduled every 3 to 3.5 hours.
     845         GnuTLSOCSPCacheTimeout 21600
     846                 GnuTLSOCSPFuzzTime     3600
    824847     </VirtualHost>
    825848
Note: See TracChangeset for help on using the changeset viewer.