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 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 We briefly describe the architecture of ``shrpx`` here. It has a
dedicated thread which listens on server sockets. When it accepted dedicated thread which listens on server sockets. When it accepted
@ -254,135 +269,160 @@ Here is the command-line options::
$ src/shrpx -h $ src/shrpx -h
Usage: shrpx [-Dh] [-s|--client|-p] [-b <HOST,PORT>] Usage: shrpx [-Dh] [-s|--client|-p] [-b <HOST,PORT>]
[-f <HOST,PORT>] [-n <CORES>] [-c <NUM>] [-L <LEVEL>] [-f <HOST,PORT>] [-n <CORES>] [-c <NUM>] [-L <LEVEL>]
[OPTIONS...] [<PRIVATE_KEY> <CERT>] [OPTIONS...] [<PRIVATE_KEY> <CERT>]
A reverse proxy for SPDY/HTTPS. A reverse proxy for SPDY/HTTPS.
Positional arguments: Positional arguments:
<PRIVATE_KEY> Set path to server's private key. Required <PRIVATE_KEY> Set path to server's private key. Required
unless either -p or --client is specified. unless either -p or --client is specified.
<CERT> Set path to server's certificate. Required <CERT> Set path to server's certificate. Required
unless either -p or --client is specified. unless either -p or --client is specified.
OPTIONS: OPTIONS:
Connections: Connections:
-b, --backend=<HOST,PORT> -b, --backend=<HOST,PORT>
Set backend host and port. Set backend host and port.
Default: '127.0.0.1,80' Default: '127.0.0.1,80'
-f, --frontend=<HOST,PORT> -f, --frontend=<HOST,PORT>
Set frontend host and port. Set frontend host and port.
Default: '0.0.0.0,3000' Default: '0.0.0.0,3000'
--backlog=<NUM> Set listen backlog size. --backlog=<NUM> Set listen backlog size.
Default: 256 Default: 256
--backend-ipv4 Resolve backend hostname to IPv4 address --backend-ipv4 Resolve backend hostname to IPv4 address
only. only.
--backend-ipv6 Resolve backend hostname to IPv6 address --backend-ipv6 Resolve backend hostname to IPv6 address
only. only.
Performance: Performance:
-n, --workers=<CORES> -n, --workers=<CORES>
Set the number of worker threads. Set the number of worker threads.
Default: 1 Default: 1
Timeout: Timeout:
--frontend-spdy-read-timeout=<SEC> --frontend-spdy-read-timeout=<SEC>
Specify read timeout for SPDY frontend Specify read timeout for SPDY frontend
connection. Default: 180 connection. Default: 180
--frontend-read-timeout=<SEC> --frontend-read-timeout=<SEC>
Specify read timeout for non-SPDY frontend Specify read timeout for non-SPDY frontend
connection. Default: 180 connection. Default: 180
--frontend-write-timeout=<SEC> --frontend-write-timeout=<SEC>
Specify write timeout for both SPDY and Specify write timeout for both SPDY and
non-SPDY frontends. non-SPDY frontends.
connection. Default: 60 connection. Default: 60
--backend-read-timeout=<SEC> --backend-read-timeout=<SEC>
Specify read timeout for backend connection. Specify read timeout for backend connection.
Default: 900 Default: 900
--backend-write-timeout=<SEC> --backend-write-timeout=<SEC>
Specify write timeout for backend Specify write timeout for backend
connection. Default: 60 connection. Default: 60
--backend-keep-alive-timeout=<SEC> --backend-keep-alive-timeout=<SEC>
Specify keep-alive timeout for backend Specify keep-alive timeout for backend
connection. Default: 60 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: SSL/TLS:
--ciphers=<SUITE> Set allowed cipher list. The format of the --ciphers=<SUITE> Set allowed cipher list. The format of the
string is described in OpenSSL ciphers(1). string is described in OpenSSL ciphers(1).
-k, --insecure When used with -p or --client, don't verify -k, --insecure When used with -p or --client, don't verify
backend server's certificate. backend server's certificate.
--cacert=<PATH> When used with -p or --client, set path to --cacert=<PATH> When used with -p or --client, set path to
trusted CA certificate file. trusted CA certificate file.
The file must be in PEM format. It can The file must be in PEM format. It can
contain multiple certificates. If the contain multiple certificates. If the
linked OpenSSL is configured to load system linked OpenSSL is configured to load system
wide certificates, they are loaded wide certificates, they are loaded
at startup regardless of this option. at startup regardless of this option.
--private-key-passwd-file=<FILEPATH> --private-key-passwd-file=<FILEPATH>
Path to file that contains password for the Path to file that contains password for the
server's private key. If none is given and server's private key. If none is given and
the private key is password protected it'll the private key is password protected it'll
be requested interactively. be requested interactively.
--subcert=<KEYPATH>:<CERTPATH>
Specify additional certificate and private
key file. Shrpx will choose certificates
used multiple times.
SPDY: SPDY:
-c, --spdy-max-concurrent-streams=<NUM> -c, --spdy-max-concurrent-streams=<NUM>
Set the maximum number of the concurrent Set the maximum number of the concurrent
streams in one SPDY session. streams in one SPDY session.
Default: 100 Default: 100
--frontend-spdy-window-bits=<N> --frontend-spdy-window-bits=<N>
Sets the initial window size of SPDY Sets the initial window size of SPDY
frontend connection to 2**<N>. frontend connection to 2**<N>.
Default: 16 Default: 16
--backend-spdy-window-bits=<N> --backend-spdy-window-bits=<N>
Sets the initial window size of SPDY Sets the initial window size of SPDY
backend connection to 2**<N>. backend connection to 2**<N>.
Default: 16 Default: 16
Mode: Mode:
-s, --spdy-proxy Enable secure SPDY proxy mode. -s, --spdy-proxy Enable secure SPDY proxy mode.
--client Instead of accepting SPDY/HTTPS connection, --spdy-bridge Communicate with the backend in SPDY. Thus
accept HTTP connection and communicate with the incoming SPDY/HTTPS connections are
backend server in SPDY. To use shrpx as converted to SPDY connection and relayed to
a forward proxy, use -p option instead. the backend. See --backend-http-proxy-uri
-p, --client-proxy Like --client option, but it also requires option if you are behind the proxy and want
the request path from frontend must be to connect to the outside SPDY proxy.
an absolute URI, suitable for use as a --client Instead of accepting SPDY/HTTPS connection,
forward proxy. 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: Logging:
-L, --log-level=<LEVEL> -L, --log-level=<LEVEL>
Set the severity level of log output. Set the severity level of log output.
INFO, WARNING, ERROR and FATAL. INFO, WARNING, ERROR and FATAL.
Default: WARNING Default: WARNING
--accesslog Print simple accesslog to stderr. --accesslog Print simple accesslog to stderr.
--syslog Send log messages to syslog. --syslog Send log messages to syslog.
--syslog-facility=<FACILITY> --syslog-facility=<FACILITY>
Set syslog facility. Set syslog facility.
Default: daemon Default: daemon
Misc: Misc:
--add-x-forwarded-for --add-x-forwarded-for
Append X-Forwarded-For header field to the Append X-Forwarded-For header field to the
downstream request. downstream request.
--no-via Don't append to Via header field. If Via --no-via Don't append to Via header field. If Via
header field is received, it is left header field is received, it is left
unaltered. unaltered.
-D, --daemon Run in a background. If -D is used, the -D, --daemon Run in a background. If -D is used, the
current working directory is changed to '/'. current working directory is changed to '/'.
--pid-file=<PATH> Set path to save PID of this program. --pid-file=<PATH> Set path to save PID of this program.
--user=<USER> Run this program as USER. This option is --user=<USER> Run this program as USER. This option is
intended to be used to drop root privileges. intended to be used to drop root privileges.
--conf=<PATH> Load configuration from PATH. --conf=<PATH> Load configuration from PATH.
Default: /etc/shrpx/shrpx.conf Default: /etc/shrpx/shrpx.conf
-v, --version Print version and exit. -v, --version Print version and exit.
-h, --help Print this help and exit. -h, --help Print this help and exit.
For those of you who are curious, ``shrpx`` is an abbreviation of For those of you who are curious, ``shrpx`` is an abbreviation of
"Spdy/https to Http Reverse ProXy". "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 Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Web Server
[reverse proxy] [reverse proxy]
@ -392,7 +432,8 @@ With ``-s`` option, it works as secure SPDY proxy::
Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Proxy Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Proxy
[SPDY proxy] (e.g., Squid) [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 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 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 $ 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 With ``-p`` option, it works as forward proxy and expects that the
backend is secure SPDY proxy:: backend is secure SPDY proxy::
Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Secure SPDY Proxy Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Secure SPDY Proxy
[forward proxy] (e.g., shrpx -s or node-spdyproxy) [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 In this configuration, clients which do not support secure SPDY proxy
can use secure SPDY proxy through ``shrpx``. Putting ``shrpx`` in the 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 Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Web Server
[reverse proxy] [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 Examples
-------- --------