Update README.rst

README.rst

@@ -231,15 +231,30 @@ Shrpx - A reverse proxy for SPDY/HTTPS
 ++++++++++++++++++++++++++++++++++++++
 
 The ``shrpx`` is a multi-threaded reverse proxy for SPDY/HTTPS.  It
-converts SPDY/HTTPS traffic to plain HTTP.  It is first developed as a
+converts SPDY/HTTPS traffic to plain HTTP.  It is initially developed
-reverse proxy, but now can be used as a forward proxy.  For example,
+as a reverse proxy, but now it has other operation modes such as a
-with ``--spdy-proxy`` (``-s`` in shorthand) option, it can be used as
+frontend forward proxy.  For example, with ``--spdy-proxy`` (``-s`` in
-secure SPDY proxy with a proxy (e.g., Squid) in the backend.  With
+shorthand) option, it can be used as secure SPDY proxy with a proxy
-``--cliet-proxy`` (``-p``) option, it acts like an ordinaly forward
+(e.g., Squid) in the backend.  With ``--cliet-proxy`` (``-p``) option,
-proxy but expects secure SPDY proxy in the backend. Thus it becomes an
+it acts like an ordinaly forward proxy but expects secure SPDY proxy
-adapter to secure SPDY proxy for clients which does not support secure
+in the backend. Thus it becomes an adapter to secure SPDY proxy for
-SPDY proxy.  It also supports configuration file. See ``--conf``
+clients which does not support secure SPDY proxy. The another notable
-option and sample configuration file ``shrpx.conf.sample``.
+operation mode is ``--spdy-relay``, which just relays SPDY/HTTPS
+traffic to the backend in SPDY. The following table summarizes the
+operation modes.
+
+================== ========== ======= =============
+Mode option        Frontend   Backend Note
+================== ========== ======= =============
+default            SPDY/HTTPS HTTP    Reverse proxy
+``--spdy``         SPDY/HTTPS HTTP    SPDY proxy
+``--spdy-relay``   SPDY/HTTPS SPDY
+``--client``       HTTP       SPDY
+``--client-proxy`` HTTP       SPDY    Forward proxy
+================== ========== ======= =============
+
+The ``shrpx`` supports configuration file. See ``--conf`` option and
+sample configuration file ``shrpx.conf.sample``.
 
 We briefly describe the architecture of ``shrpx`` here.  It has a
 dedicated thread which listens on server sockets.  When it accepted
@@ -306,6 +321,21 @@ Here is the command-line options::
 	--backend-keep-alive-timeout=<SEC>
 			   Specify keep-alive timeout for backend
 			   connection. Default: 60
+	--backend-http-proxy-uri=<URI>
+			   Specify proxy URI in the form
+			   http://[<USER>:<PASS>@]<PROXY>:<PORT>. If
+			   a proxy requires authentication, specify
+			   <USER> and <PASS>. Note that they must be
+			   properly percent-encoded. This proxy is used
+			   when the backend connection is SPDY. First,
+			   make a CONNECT request to the proxy and
+			   it connects to the backend on behalf of
+			   shrpx. This forms tunnel. After that, shrpx
+			   performs SSL/TLS handshake with the
+			   downstream through the tunnel. The timeouts
+			   when connecting and making CONNECT request
+			   can be specified by --backend-read-timeout
+			   and --backend-write-timeout options.
 
       SSL/TLS:
 	--ciphers=<SUITE>  Set allowed cipher list. The format of the
@@ -324,6 +354,10 @@ Here is the command-line options::
 			   server's private key. If none is given and
 			   the private key is password protected it'll
 			   be requested interactively.
+	--subcert=<KEYPATH>:<CERTPATH>
+			   Specify additional certificate and private
+			   key file. Shrpx will choose certificates
+			   used multiple times.
 
       SPDY:
 	-c, --spdy-max-concurrent-streams=<NUM>
@@ -341,6 +375,12 @@ Here is the command-line options::
 
       Mode:
 	-s, --spdy-proxy   Enable secure SPDY proxy mode.
+	--spdy-bridge      Communicate with the backend in SPDY. Thus
+			   the incoming SPDY/HTTPS connections are
+			   converted to SPDY connection and relayed to
+			   the backend. See --backend-http-proxy-uri
+			   option if you are behind the proxy and want
+			   to connect to the outside SPDY proxy.
 	--client           Instead of accepting SPDY/HTTPS connection,
 			   accept HTTP connection and communicate with
 			   backend server in SPDY. To use shrpx as
@@ -381,8 +421,8 @@ Here is the command-line options::
 For those of you who are curious, ``shrpx`` is an abbreviation of
 "Spdy/https to Http Reverse ProXy".
 
-Without any of ``-s``, ``-p`` and ``--client`` options, ``shrpx``
+Without any of ``-s``, ``--spdy-bridge``, ``-p`` and ``--client``
-works as reverse proxy to the backend server::
+options, ``shrpx`` works as reverse proxy to the backend server::
 
     Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Web Server
                             [reverse proxy]
@@ -392,7 +432,8 @@ With ``-s`` option, it works as secure SPDY proxy::
     Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Proxy
                               [SPDY proxy]            (e.g., Squid)
 
-    * Client is needs to be configured to use shrpx as secure SPDY proxy.
+The ``Client`` in the above is needs to be configured to use shrpx as
+secure SPDY proxy.
 
 At the time of this writing, Chrome is the only browser which supports
 secure SPDY proxy. The one way to configure Chrome to use secure SPDY
@@ -410,13 +451,45 @@ Then run chrome with the following arguments::
 
     $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
 
+.. note::
+
+   At the time of this writing, Chrome 24 limits the maximum
+   concurrent connections to the proxy to 32. And due to the
+   limitation of socket pool handling in Chrome, it is quickly filled
+   up if SPDY proxy is used and many SPDY sessions are established. If
+   it reaches the limit, the new connections are simply blocked until
+   existing connections are timed out. (See `Chrome Issue 92244
+   <https://code.google.com/p/chromium/issues/detail?id=92244>`_). The
+   workaround is make the number of maximum connections high, say, 99,
+   which is the highest. To do this, you need to change so called
+   Policy setup.  See `Policy Templates
+   <http://dev.chromium.org/administrators/policy-templates>`_ for
+   details how to change Policy setup on the platform you use.  The
+   Policy name we are looking for is `MaxConnectionsPerProxy
+   <http://dev.chromium.org/administrators/policy-list-3#MaxConnectionsPerProxy>`_
+   For example, if you are using Linux, follow the instruction
+   described in `Linux Quick Start
+   <http://dev.chromium.org/administrators/linux-quick-start>`_ and
+   create ``/etc/opt/chrome/policies/managed/test_policy.json`` file
+   with the following content and restart Chrome::
+
+       {
+           "MaxConnectionsPerProxy" :99
+       }
+
+With ``--spdy-bridge``, it accepts SPDY/HTTPS connections and
+communicates with backend in SPDY::
+
+    Client <-- (SPDY, HTTPS) --> Shrpx <-- (SPDY) --> Web or SPDY Proxy etc
+                              [SPDY bridge]           (e.g., shrpx -s)
+
 With ``-p`` option, it works as forward proxy and expects that the
 backend is secure SPDY proxy::
 
     Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Secure SPDY Proxy
                      [forward proxy]         (e.g., shrpx -s or node-spdyproxy)
 
-    * Client is needs to be configured to use shrpx as forward proxy.
+The ``Client`` is needs to be configured to use shrpx as forward proxy.
 
 In this configuration, clients which do not support secure SPDY proxy
 can use secure SPDY proxy through ``shrpx``. Putting ``shrpx`` in the
@@ -437,6 +510,19 @@ the backend is SPDY-enabled Web server::
     Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Web Server
                      [reverse proxy]
 
+For the operation modes which talk to the backend in SPDY, the backend
+connections can be tunneled though HTTP proxy. The proxy is specified
+using ``--backend-http-proxy-uri`` option. The following figure
+illustrates the example of ``--spdy-bridge`` and
+``--backend-http-proxy-uri`` option to talk to the outside SPDY proxy
+through HTTP proxy::
+
+    Client <-- (SPDY, HTTPS) --> Shrpx <-- (SPDY) --
+                             [SPDY bridge]
+
+            --===================---> SPDY Proxy
+              (HTTP proxy tunnel)     (e.g., shrpx -s)
+
 Examples
 --------