Update README.rst
This commit is contained in:
Tatsuhiro Tsujikawa
parent
8b6fbbf3a6
commit
1973cec134
112
README.rst
112
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
|
||||
reverse proxy, but now can be used as a forward proxy. For example,
|
||||
with ``--spdy-proxy`` (``-s`` in shorthand) option, it can be used as
|
||||
secure SPDY proxy with a proxy (e.g., Squid) in the backend. With
|
||||
``--cliet-proxy`` (``-p``) option, it acts like an ordinaly forward
|
||||
proxy but expects secure SPDY proxy in the backend. Thus it becomes an
|
||||
adapter to secure SPDY proxy for clients which does not support secure
|
||||
SPDY proxy. It also supports configuration file. See ``--conf``
|
||||
option and sample configuration file ``shrpx.conf.sample``.
|
||||
converts SPDY/HTTPS traffic to plain HTTP. It is initially developed
|
||||
as a reverse proxy, but now it has other operation modes such as a
|
||||
frontend forward proxy. For example, with ``--spdy-proxy`` (``-s`` in
|
||||
shorthand) option, it can be used as secure SPDY proxy with a proxy
|
||||
(e.g., Squid) in the backend. With ``--cliet-proxy`` (``-p``) option,
|
||||
it acts like an ordinaly forward proxy but expects secure SPDY proxy
|
||||
in the backend. Thus it becomes an adapter to secure SPDY proxy for
|
||||
clients which does not support secure SPDY proxy. The another notable
|
||||
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``
|
||||
works as reverse proxy to the backend server::
|
||||
Without any of ``-s``, ``--spdy-bridge``, ``-p`` and ``--client``
|
||||
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
|
||||
--------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue