Skip to content

N
nghttp2
Commit df7023bd authored by Tatsuhiro Tsujikawa's avatar Tatsuhiro Tsujikawa
Browse files
Options

Update README.rst

parent 7a219053
Hide whitespace changes
Inline Side-by-side
Showing with 104 additions and 52 deletions
README.rst
View file @ df7023bd
......@@ -225,11 +225,15 @@ 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 can be used as SSL/SPDY
proxy with the http proxy (e.g., Squid) in the backend. To enable
SSL/SPDY proxy mode, use ``--spdy-proxy`` option. It also supports
configuration file. See ``--conf`` option and sample configuration
file ``shrpx.conf.sample``.
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``.
We briefly describe the architecture of ``shrpx`` here. It has a
dedicated thread which listens on server sockets. When it accepted
......@@ -243,40 +247,36 @@ low-level network I/O.
Here is the command-line options::
$ src/shrpx -h
Usage: shrpx [-Dhs] [-b <HOST,PORT>] [-f <HOST,PORT>] [-n <CORES>]
[-c <NUM>] [-L <LEVEL>] [OPTIONS...]
<PRIVATE_KEY> <CERT>
shrpx --client-mode [-Dh] [-b <HOST,PORT>] [-f <HOST,PORT>]
[-n <CORES>] [-c <NUM>] [-L <LEVEL>] [OPTIONS...]
Usage: shrpx [-Dh] [-s|--client|-p] [-b <HOST,PORT>]
[-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.
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
Performance:
-n, --workers=<CORES>
Set the number of worker threads.
Default: 1
-c, --spdy-max-concurrent-streams=<NUM>
Set the maximum number of the concurrent
streams in one SPDY session.
Default: 100
-L, --log-level=<LEVEL>
Set the severity level of log output.
INFO, WARNING, ERROR and FATAL.
Default: WARNING
-D, --daemon Run in a background. If -D is used, the
current working directory is changed to '/'.
-s, --spdy-proxy SSL/SPDY proxy mode.
--add-x-forwarded-for
Append X-Forwarded-For header field to the
downstream request.
Timeout:
--frontend-spdy-read-timeout=<SEC>
Specify read timeout for SPDY frontend
connection. Default: 180
......@@ -296,47 +296,88 @@ Here is the command-line options::
--backend-keep-alive-timeout=<SEC>
Specify keep-alive timeout for backend
connection. Default: 60
--accesslog Print simple accesslog to stderr.
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.
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
--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
--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.
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
--backlog=<NUM> Set listen backlog size.
Default: 256
--ciphers=<SUITE> Set allowed cipher list. The format of the
string is described in OpenSSL ciphers(1).
--client-mode Instead of accepting SPDY/HTTPS connection,
accept HTTP connection and communicate with
backend server in SPDY. This is for testing
purpose.
-h, --help Print this help.
Misc:
--add-x-forwarded-for
Append X-Forwarded-For header field to the
downstream request.
-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 ``-s`` option, it works in the following configuration::
Without any of ``-s``, ``-p`` and ``--client`` options, ``shrpx``
works as reverse proxy to the backend server::
Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Web Server
[reverse proxy]
With ``-s`` option, it works in the following configuration::
With ``-s`` option, it works as secure SPDY proxy::
Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Proxy (e.g., Squid)
Client <-- (SPDY, HTTPS) --> Shrpx <-- (HTTP) --> Proxy
[SPDY proxy] (e.g., Squid)
* Client is configured to use Shrpx as SSL/SPDY proxy.
* Client 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
SSL/SPDY proxy. The one way to configure Chrome to use SSL/SPDY proxy
is create proxy.pac script like this::
secure SPDY proxy. The one way to configure Chrome to use secure SPDY
proxy is create proxy.pac script like this::
function FindProxyForURL(url, host) {
return "HTTPS SERVERADDR:PORT";
......@@ -344,19 +385,30 @@ is create proxy.pac script like this::
``SERVERADDR`` and ``PORT`` is the hostname/address and port of the
machine shrpx is running. Please note that Chrome requires valid
certificate for SSL/PROXY.
certificate for secure SPDY proxy.
Then run chrome with the following arguments::
$ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn
There is an interesting option ``--client-mode``. If it is given,
``shrpx`` accepts HTTP connections and communicates with the backend
in SPDY::
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.
In this configuration, clients which do not support secure SPDY proxy
can use secure SPDY proxy through ``shrpx``. Putting ``shrpx`` in the
same box or same network with the clients, this configuration can
bring the benefits of secure SPDY proxy to those clients.
Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Web Server or another Shrpx
With ``--client`` option, it works as reverse proxy and expects that
the backend is SPDY-enabled Web server::
``--client-mode`` option is for testing purpose only.
Client <-- (HTTP) --> Shrpx <-- (SPDY) --> Web Server
[reverse proxy]
Examples
--------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment