From 1973cec134a7e184b30f0ecc53e8a5b3db66384f Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 9 Feb 2013 21:17:49 +0900 Subject: [PATCH] Update README.rst --- README.rst | 314 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 200 insertions(+), 114 deletions(-) diff --git a/README.rst b/README.rst index a0895ca2..944cff91 100644 --- a/README.rst +++ b/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 @@ -254,135 +269,160 @@ Here is the command-line options:: $ src/shrpx -h Usage: shrpx [-Dh] [-s|--client|-p] [-b ] - [-f ] [-n ] [-c ] [-L ] - [OPTIONS...] [ ] + [-f ] [-n ] [-c ] [-L ] + [OPTIONS...] [ ] A reverse proxy for SPDY/HTTPS. Positional arguments: - Set path to server's private key. Required - unless either -p or --client is specified. - Set path to server's certificate. Required - unless either -p or --client is specified. + Set path to server's private key. Required + unless either -p or --client is specified. + Set path to server's certificate. Required + unless either -p or --client is specified. OPTIONS: Connections: - -b, --backend= - Set backend host and port. - Default: '127.0.0.1,80' - -f, --frontend= - Set frontend host and port. - Default: '0.0.0.0,3000' - --backlog= 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= + Set backend host and port. + Default: '127.0.0.1,80' + -f, --frontend= + Set frontend host and port. + Default: '0.0.0.0,3000' + --backlog= 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= - Set the number of worker threads. - Default: 1 + -n, --workers= + Set the number of worker threads. + Default: 1 Timeout: - --frontend-spdy-read-timeout= - Specify read timeout for SPDY frontend - connection. Default: 180 - --frontend-read-timeout= - Specify read timeout for non-SPDY frontend - connection. Default: 180 - --frontend-write-timeout= - Specify write timeout for both SPDY and - non-SPDY frontends. - connection. Default: 60 - --backend-read-timeout= - Specify read timeout for backend connection. - Default: 900 - --backend-write-timeout= - Specify write timeout for backend - connection. Default: 60 - --backend-keep-alive-timeout= - Specify keep-alive timeout for backend - connection. Default: 60 + --frontend-spdy-read-timeout= + Specify read timeout for SPDY frontend + connection. Default: 180 + --frontend-read-timeout= + Specify read timeout for non-SPDY frontend + connection. Default: 180 + --frontend-write-timeout= + Specify write timeout for both SPDY and + non-SPDY frontends. + connection. Default: 60 + --backend-read-timeout= + Specify read timeout for backend connection. + Default: 900 + --backend-write-timeout= + Specify write timeout for backend + connection. Default: 60 + --backend-keep-alive-timeout= + Specify keep-alive timeout for backend + connection. Default: 60 + --backend-http-proxy-uri= + Specify proxy URI in the form + http://[:@]:. If + a proxy requires authentication, specify + and . 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= 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= 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= - 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= 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= 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= + 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=: + Specify additional certificate and private + key file. Shrpx will choose certificates + used multiple times. SPDY: - -c, --spdy-max-concurrent-streams= - Set the maximum number of the concurrent - streams in one SPDY session. - Default: 100 - --frontend-spdy-window-bits= - Sets the initial window size of SPDY - frontend connection to 2**. - Default: 16 - --backend-spdy-window-bits= - Sets the initial window size of SPDY - backend connection to 2**. - Default: 16 + -c, --spdy-max-concurrent-streams= + Set the maximum number of the concurrent + streams in one SPDY session. + Default: 100 + --frontend-spdy-window-bits= + Sets the initial window size of SPDY + frontend connection to 2**. + Default: 16 + --backend-spdy-window-bits= + Sets the initial window size of SPDY + backend connection to 2**. + 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= - 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= - Set syslog facility. - Default: daemon + -L, --log-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= + 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= Set path to save PID of this program. - --user= Run this program as USER. This option is - intended to be used to drop root privileges. - --conf= 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= Set path to save PID of this program. + --user= Run this program as USER. This option is + intended to be used to drop root privileges. + --conf= 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 + `_). 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 + `_ for + details how to change Policy setup on the platform you use. The + Policy name we are looking for is `MaxConnectionsPerProxy + `_ + For example, if you are using Linux, follow the instruction + described in `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 --------