walkero
/
nghttp2
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update README.rst

This commit is contained in:
Tatsuhiro Tsujikawa 2013-02-09 21:17:49 +09:00
parent 8b6fbbf3a6
commit 1973cec134
1 changed files with 200 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

314
README.rst
View File

@ -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
@ -254,135 +269,160 @@ Here is the command-line options::
$ src/shrpx -h
Usage: shrpx [-Dh] [-s|--client|-p] [-b <HOST,PORT>]
[-f <HOST,PORT>] [-n <CORES>] [-c <NUM>] [-L <LEVEL>]
[OPTIONS...] [<PRIVATE_KEY> <CERT>]
[-f <HOST,PORT>] [-n <CORES>] [-c <NUM>] [-L <LEVEL>]
[OPTIONS...] [<PRIVATE_KEY> <CERT>]
A reverse proxy for SPDY/HTTPS.
Positional arguments:
<PRIVATE_KEY> Set path to server's private key. Required
unless either -p or --client is specified.
<CERT> Set path to server's certificate. Required
unless either -p or --client is specified.
<PRIVATE_KEY> Set path to server's private key. Required
unless either -p or --client is specified.
<CERT> Set path to server's certificate. Required
unless either -p or --client is specified.
OPTIONS:
Connections:
-b, --backend=<HOST,PORT>
Set backend host and port.
Default: '127.0.0.1,80'
-f, --frontend=<HOST,PORT>
Set frontend host and port.
Default: '0.0.0.0,3000'
--backlog=<NUM> Set listen backlog size.
Default: 256
--backend-ipv4 Resolve backend hostname to IPv4 address
only.
--backend-ipv6 Resolve backend hostname to IPv6 address
only.
-b, --backend=<HOST,PORT>
Set backend host and port.
Default: '127.0.0.1,80'
-f, --frontend=<HOST,PORT>
Set frontend host and port.
Default: '0.0.0.0,3000'
--backlog=<NUM> Set listen backlog size.
Default: 256
--backend-ipv4 Resolve backend hostname to IPv4 address
only.
--backend-ipv6 Resolve backend hostname to IPv6 address
only.
Performance:
-n, --workers=<CORES>
Set the number of worker threads.
Default: 1
-n, --workers=<CORES>
Set the number of worker threads.
Default: 1
Timeout:
--frontend-spdy-read-timeout=<SEC>
Specify read timeout for SPDY frontend
connection. Default: 180
--frontend-read-timeout=<SEC>
Specify read timeout for non-SPDY frontend
connection. Default: 180
--frontend-write-timeout=<SEC>
Specify write timeout for both SPDY and
non-SPDY frontends.
connection. Default: 60
--backend-read-timeout=<SEC>
Specify read timeout for backend connection.
Default: 900
--backend-write-timeout=<SEC>
Specify write timeout for backend
connection. Default: 60
--backend-keep-alive-timeout=<SEC>
Specify keep-alive timeout for backend
connection. Default: 60
--frontend-spdy-read-timeout=<SEC>
Specify read timeout for SPDY frontend
connection. Default: 180
--frontend-read-timeout=<SEC>
Specify read timeout for non-SPDY frontend
connection. Default: 180
--frontend-write-timeout=<SEC>
Specify write timeout for both SPDY and
non-SPDY frontends.
connection. Default: 60
--backend-read-timeout=<SEC>
Specify read timeout for backend connection.
Default: 900
--backend-write-timeout=<SEC>
Specify write timeout for backend
connection. Default: 60
--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
string is described in OpenSSL ciphers(1).
-k, --insecure When used with -p or --client, don't verify
backend server's certificate.
--cacert=<PATH> When used with -p or --client, set path to
trusted CA certificate file.
The file must be in PEM format. It can
contain multiple certificates. If the
linked OpenSSL is configured to load system
wide certificates, they are loaded
at startup regardless of this option.
--private-key-passwd-file=<FILEPATH>
Path to file that contains password for the
server's private key. If none is given and
the private key is password protected it'll
be requested interactively.
--ciphers=<SUITE> Set allowed cipher list. The format of the
string is described in OpenSSL ciphers(1).
-k, --insecure When used with -p or --client, don't verify
backend server's certificate.
--cacert=<PATH> When used with -p or --client, set path to
trusted CA certificate file.
The file must be in PEM format. It can
contain multiple certificates. If the
linked OpenSSL is configured to load system
wide certificates, they are loaded
at startup regardless of this option.
--private-key-passwd-file=<FILEPATH>
Path to file that contains password for the
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>
Set the maximum number of the concurrent
streams in one SPDY session.
Default: 100
--frontend-spdy-window-bits=<N>
Sets the initial window size of SPDY
frontend connection to 2**<N>.
Default: 16
--backend-spdy-window-bits=<N>
Sets the initial window size of SPDY
backend connection to 2**<N>.
Default: 16
-c, --spdy-max-concurrent-streams=<NUM>
Set the maximum number of the concurrent
streams in one SPDY session.
Default: 100
--frontend-spdy-window-bits=<N>
Sets the initial window size of SPDY
frontend connection to 2**<N>.
Default: 16
--backend-spdy-window-bits=<N>
Sets the initial window size of SPDY
backend connection to 2**<N>.
Default: 16
Mode:
-s, --spdy-proxy Enable secure SPDY proxy mode.
--client Instead of accepting SPDY/HTTPS connection,
accept HTTP connection and communicate with
backend server in SPDY. To use shrpx as
a forward proxy, use -p option instead.
-p, --client-proxy Like --client option, but it also requires
the request path from frontend must be
an absolute URI, suitable for use as a
forward proxy.
-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
a forward proxy, use -p option instead.
-p, --client-proxy Like --client option, but it also requires
the request path from frontend must be
an absolute URI, suitable for use as a
forward proxy.
Logging:
-L, --log-level=<LEVEL>
Set the severity level of log output.
INFO, WARNING, ERROR and FATAL.
Default: WARNING
--accesslog Print simple accesslog to stderr.
--syslog Send log messages to syslog.
--syslog-facility=<FACILITY>
Set syslog facility.
Default: daemon
-L, --log-level=<LEVEL>
Set the severity level of log output.
INFO, WARNING, ERROR and FATAL.
Default: WARNING
--accesslog Print simple accesslog to stderr.
--syslog Send log messages to syslog.
--syslog-facility=<FACILITY>
Set syslog facility.
Default: daemon
Misc:
--add-x-forwarded-for
Append X-Forwarded-For header field to the
downstream request.
--no-via Don't append to Via header field. If Via
header field is received, it is left
unaltered.
-D, --daemon Run in a background. If -D is used, the
current working directory is changed to '/'.
--pid-file=<PATH> Set path to save PID of this program.
--user=<USER> Run this program as USER. This option is
intended to be used to drop root privileges.
--conf=<PATH> Load configuration from PATH.
Default: /etc/shrpx/shrpx.conf
-v, --version Print version and exit.
-h, --help Print this help and exit.
--add-x-forwarded-for
Append X-Forwarded-For header field to the
downstream request.
--no-via Don't append to Via header field. If Via
header field is received, it is left
unaltered.
-D, --daemon Run in a background. If -D is used, the
current working directory is changed to '/'.
--pid-file=<PATH> Set path to save PID of this program.
--user=<USER> Run this program as USER. This option is
intended to be used to drop root privileges.
--conf=<PATH> Load configuration from PATH.
Default: /etc/shrpx/shrpx.conf
-v, --version Print version and exit.
-h, --help Print this help and exit.
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
--------