Mercurial > hg > nginx-site

changeset 801:b95a6d779c89

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented that "listen ... ssl" is preferred over "ssl on".
author Ruslan Ermilov <ru@nginx.com>
date Thu, 27 Dec 2012 17:16:39 +0000
parents 015981070efd
children 8af7fe0794b0
files xml/en/docs/http/configuring_https_servers.xml xml/en/docs/http/ngx_http_ssl_module.xml xml/ru/docs/http/configuring_https_servers.xml xml/ru/docs/http/ngx_http_ssl_module.xml
diffstat 4 files changed, 79 insertions(+), 72 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/configuring_https_servers.xml	Thu Dec 27 13:23:32 2012 +0000
+++ b/xml/en/docs/http/configuring_https_servers.xml	Thu Dec 27 17:16:39 2012 +0000
@@ -8,22 +8,24 @@
 <article name="Configuring HTTPS servers"
          link="/en/docs/http/configuring_https_servers.html"
          lang="en"
-         rev="4"
+         rev="5"
          author="Igor Sysoev"
          editor="Brian Mercer">
 
 <section>
 
 <para>
-To configure an HTTPS server, the SSL protocol must be enabled
-in the server block, and the locations of the server certificate
+To configure an HTTPS server, the <literal>ssl</literal> parameter
+must be enabled on
+<link doc="ngx_http_core_module.xml" id="listen">listening sockets</link>
+in the <link doc="ngx_http_core_module.xml" id="server"/> block,
+and the locations of the server certificate
 and private key files should be specified:
 
 <programlisting>
 server {
-    listen              443;
+    listen              443 <b>ssl</b>;
     server_name         www.example.com;
-    ssl                 <b>on</b>;
     ssl_certificate     <b>www.example.com.crt</b>;
     ssl_certificate_key <b>www.example.com.key</b>;
     ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
@@ -107,11 +109,10 @@
     <b>ssl_session_timeout 10m</b>;
 
     server {
-        listen              443;
+        listen              443 ssl;
         server_name         www.example.com;
         <b>keepalive_timeout   70</b>;
 
-        ssl                 on;
         ssl_certificate     www.example.com.crt;
         ssl_certificate_key www.example.com.key;
         ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
@@ -147,9 +148,8 @@
 
 <programlisting>
 server {
-    listen              443;
+    listen              443 ssl;
     server_name         www.example.com;
-    ssl                 on;
     ssl_certificate     www.example.com.chained.crt;
     ssl_certificate_key www.example.com.key;
     ...
@@ -223,10 +223,8 @@
 <section id="single_http_https_server" name="A single HTTP/HTTPS server">
 
 <para>
-If HTTP and HTTPS servers are equal,
-a single server that handles both HTTP and HTTPS requests may be configured
-by deleting the directive “<literal>ssl on</literal>”
-and adding the <literal>ssl</literal> parameter for *:443 port:
+It is possible to configure a single server that handles both HTTP
+and HTTPS requests:
 
 <programlisting>
 server {
@@ -240,11 +238,17 @@
 </programlisting>
 
 <note>
-Prior to 0.8.21, nginx only allows the <literal>ssl</literal> parameter
-to be set on listen sockets with the <literal>default</literal> parameter:
-<programlisting>
-listen 443 default ssl;
-</programlisting>
+Prior to 0.7.14 SSL could not be enabled selectively for
+individual listening sockets, as shown above.
+SSL could only be enabled for the entire server using the
+<link doc="ngx_http_ssl_module.xml" id="ssl"/> directive,
+making it impossible to set up a single HTTP/HTTPS server.
+The <literal>ssl</literal> parameter of the
+<link doc="ngx_http_core_module.xml" id="listen"/> directive
+was added to solve this issue.
+The use of the
+<link doc="ngx_http_ssl_module.xml" id="ssl"/> directive
+in modern versions is thus discouraged.
 </note>
 </para>
 
@@ -259,17 +263,15 @@
 
 <programlisting>
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ssl_certificate www.example.com.crt;
     ...
 }
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ssl_certificate www.example.org.crt;
     ...
 }
@@ -289,25 +291,21 @@
 
 <programlisting>
 server {
-    listen          192.168.1.1:443;
+    listen          192.168.1.1:443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ssl_certificate www.example.com.crt;
     ...
 }
 
 server {
-    listen          192.168.1.2:443;
+    listen          192.168.1.2:443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ssl_certificate www.example.org.crt;
     ...
 }
 </programlisting>
 </para>
 
-</section>
-
 
 <section id="certificate_with_several_names"
          name="An SSL certificate with several names">
@@ -345,16 +343,14 @@
 ssl_certificate_key common.key;
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ...
 }
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ...
 }
 </programlisting>
@@ -438,6 +434,8 @@
 
 </section>
 
+</section>
+
 
 <section id="compatibility" name="Compatibility">
 
@@ -453,6 +451,8 @@
 The <literal>ssl</literal> parameter of the
 <link doc="ngx_http_core_module.xml" id="listen"/>
 directive has been supported since 0.7.14.
+Prior to 0.8.21 it could only be specified along with the
+<literal>default</literal> parameter.
 </listitem>
 
 <listitem>
--- a/xml/en/docs/http/ngx_http_ssl_module.xml	Thu Dec 27 13:23:32 2012 +0000
+++ b/xml/en/docs/http/ngx_http_ssl_module.xml	Thu Dec 27 17:16:39 2012 +0000
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_ssl_module"
         link="/en/docs/http/ngx_http_ssl_module.html"
         lang="en"
-        rev="5">
+        rev="6">
 
 <section id="summary">
 
@@ -68,10 +68,9 @@
     ...
 
     server {
-        listen              443;
+        listen              443 ssl;
         <emphasis>keepalive_timeout   70;</emphasis>
 
-        ssl                 on;
         ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
         ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
         ssl_certificate     /usr/local/nginx/conf/cert.pem;
@@ -97,6 +96,11 @@
 
 <para>
 Enables the HTTPS protocol for the given virtual server.
+<note>
+It is recommended to use the <literal>ssl</literal> parameter of the
+<link doc="ngx_http_core_module.xml" id="listen"/> directive instead
+of this directive.
+</note>
 </para>
 
 </directive>
--- a/xml/ru/docs/http/configuring_https_servers.xml	Thu Dec 27 13:23:32 2012 +0000
+++ b/xml/ru/docs/http/configuring_https_servers.xml	Thu Dec 27 17:16:39 2012 +0000
@@ -8,22 +8,24 @@
 <article name="Настройка HTTPS-серверов"
          link="/ru/docs/http/configuring_https_servers.html"
          lang="ru"
-         rev="4"
+         rev="5"
          author="Игорь Сысоев"
          editor="Brian Mercer">
 
 <section>
 
 <para>
-Чтобы настроить HTTPS-сервер, необходимо включить протокол SSL
-в блоке server, а также указать местоположение файлов с
+Чтобы настроить HTTPS-сервер, необходимо включить параметр
+<literal>ssl</literal> на
+<link doc="ngx_http_core_module.xml" id="listen">слушающих сокетах</link>
+в блоке <link doc="ngx_http_core_module.xml" id="server"/>,
+а также указать местоположение файлов с
 сертификатом сервера и секретным ключом:
 
 <programlisting>
 server {
-    listen              443;
+    listen              443 <b>ssl</b>;
     server_name         www.example.com;
-    ssl                 <b>on</b>;
     ssl_certificate     <b>www.example.com.crt</b>;
     ssl_certificate_key <b>www.example.com.key</b>;
     ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
@@ -107,11 +109,10 @@
     <b>ssl_session_timeout 10m</b>;
 
     server {
-        listen              443;
+        listen              443 ssl;
         server_name         www.example.com;
         <b>keepalive_timeout   70</b>;
 
-        ssl                 on;
         ssl_certificate     www.example.com.crt;
         ssl_certificate_key www.example.com.key;
         ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
@@ -147,9 +148,8 @@
 
 <programlisting>
 server {
-    listen              443;
+    listen              443 ssl;
     server_name         www.example.com;
-    ssl                 on;
     ssl_certificate     www.example.com.chained.crt;
     ssl_certificate_key www.example.com.key;
     ...
@@ -223,11 +223,8 @@
 <section id="single_http_https_server" name="Единый HTTP/HTTPS сервер">
 
 <para>
-Если серверы HTTP и HTTPS идентичны,
-можно настроить единый сервер, который обслуживает как HTTP-,
-так и HTTPS-запросы.
-Для этого следует исключить директиву “<literal>ssl on</literal>”
-и добавить параметр <literal>ssl</literal> к порту *:443:
+Можно настроить единый сервер, который обслуживает как HTTP-,
+так и HTTPS-запросы:
 
 <programlisting>
 server {
@@ -241,11 +238,17 @@
 </programlisting>
 
 <note>
-До версии 0.8.21 nginx допускал указание параметра <literal>ssl</literal>
-на слушающем сокете только совместно с параметром <literal>default</literal>:
-<programlisting>
-listen  443  default  ssl;
-</programlisting>
+До версии 0.7.14 SSL нельзя было включить выборочно для
+отдельных слущающих сокетов, как показано выше.
+SSL можно было включить только для всего сервера целиком,
+с помощью директивы <link doc="ngx_http_ssl_module.xml" id="ssl"/>,
+что не позволяло настроить единый HTTP/HTTPS сервер.
+Для решения этой задачи был добавлен
+параметр <literal>ssl</literal>
+директивы <link doc="ngx_http_core_module.xml" id="listen"/>.
+Поэтому использование
+директивы <link doc="ngx_http_ssl_module.xml" id="ssl"/>
+в современных версиях не рекомендуется.
 </note>
 </para>
 
@@ -260,17 +263,15 @@
 
 <programlisting>
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ssl_certificate www.example.com.crt;
     ...
 }
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ssl_certificate www.example.org.crt;
     ...
 }
@@ -290,25 +291,21 @@
 
 <programlisting>
 server {
-    listen          192.168.1.1:443;
+    listen          192.168.1.1:443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ssl_certificate www.example.com.crt;
     ...
 }
 
 server {
-    listen          192.168.1.2:443;
+    listen          192.168.1.2:443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ssl_certificate www.example.org.crt;
     ...
 }
 </programlisting>
 </para>
 
-</section>
-
 
 <section id="certificate_with_several_names"
          name="SSL-сертификат с несколькими именами">
@@ -346,16 +343,14 @@
 ssl_certificate_key common.key;
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.com;
-    ssl             on;
     ...
 }
 
 server {
-    listen          443;
+    listen          443 ssl;
     server_name     www.example.org;
-    ssl             on;
     ...
 }
 </programlisting>
@@ -439,6 +434,8 @@
 
 </section>
 
+</section>
+
 
 <section id="compatibility" name="Совместимость">
 
@@ -454,6 +451,8 @@
 Параметр <literal>ssl</literal> директивы
 <link doc="ngx_http_core_module.xml" id="listen"/>
 поддерживается начиная с версии 0.7.14.
+До версии 0.8.21 его можно было указывать только совместно с
+параметром <literal>default</literal>.
 </listitem>
 
 <listitem>
--- a/xml/ru/docs/http/ngx_http_ssl_module.xml	Thu Dec 27 13:23:32 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_ssl_module.xml	Thu Dec 27 17:16:39 2012 +0000
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_ssl_module"
         link="/ru/docs/http/ngx_http_ssl_module.html"
         lang="ru"
-        rev="5">
+        rev="6">
 
 <section id="summary">
 
@@ -68,10 +68,9 @@
     ...
 
     server {
-        listen              443;
+        listen              443 ssl;
         <emphasis>keepalive_timeout   70;</emphasis>
 
-        ssl                 on;
         ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
         ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
         ssl_certificate     /usr/local/nginx/conf/cert.pem;
@@ -96,7 +95,12 @@
 <context>server</context>
 
 <para>
-Разрешает протокол HTTPS для данного виртуального сервера.
+Включает протокол HTTPS для данного виртуального сервера.
+<note>
+Вместо этой директивы рекомендуется использовать параметр
+<literal>ssl</literal> директивы
+<link doc="ngx_http_core_module.xml" id="listen"/>.
+</note>
 </para>
 
 </directive>