Repository files navigation

This project is officially deprecated due to upstream inactivity (last updated Feb 2015, 2d36766; last release Apr 2014, 0.3.1).

The following is a list of other HTTP proxies which might be suitable replacements depending on your needs:

traefikvulcandnginxhaproxyhttpd

This is the documentation formaster. If you are installing Hipache fromNPM,you should look at the documentation on the0.3.x branch.

Hipache (pronouncehɪ'pætʃɪ) is afully-featured distributedproxy designed to route high volumes of HTTP and WebSocket traffic to unusuallylarge numbers of virtual hosts, in a highly dynamic topology where backends areadded and removed several times per second. It is particularly well-suited forPaaS (Platform-as-a-Service) and other environments that are bothbusiness-critical and multi-tenant.

Hipache was originally developed atdotCloud, apopular platform-as-a-service, to replace its first-generation routing layerbased on a heavily instrumented nginx deployment. It currently serves productiontraffic for tens of thousands of applications hosted on dotCloud. Hipache isbased on thenode-http-proxylibrary.

From the shell:

$ npm install hipache -g

The '-g' option will make the 'hipache' bin-script available system-wide(usually linked from '/usr/local/bin').

Basic Hipache configuration is described in aconfig.json file. For example,this is the configuration file for themaster version of Hipache (i.e. underdevelopment, you should rather look at the documentation of the latest stableversion you installed):

{    "server": {        "debug": false,        "workers": 10,        "maxSockets": 100,        "tcpTimeout": 30,        "deadBackendTTL": 30,        "retryOnError": 3,        "accessLog": "/var/log/hipache/access.log",        "httpKeepAlive": false,        "deadBackendOn500": true,        "staticDir": null    },    "http": {        "port": 80,        "bind": ["127.0.0.1"]    },    "https": {        "bind": [],        "port": 443,        "ca": [],        "secureProtocol": "SSLv23_method",        "secureOptions": 50331648,        "key": "/etc/ssl/ssl.key",        "cert": "/etc/ssl/ssl.crt",        "passphrase": undefined,        "ciphers": "DH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+a RSA+SHA384 EECDH+aRSA+SHA256 EECDH+aRSA+RC4 EECDH EDH+aRSA RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS !RC4",        "honorCipherOrder": true    },    "driver": "redis:",    "user": "www-data",    "group": "www-data"}

• server: generic server settings, like accesslog location, or number ofworkers
  • server.debug: debug mode.
  • server.workers: number of workers to be spawned. You need to requestto have at least 1 worker, as the master process does not serve anyrequest. Defaults to10 if not specified.
  • server.maxSockets: the maximum number of sockets which can be openedon each backend (per worker). Defaults to100 if not specified.
  • server.tcpTimeout: the number of seconds of inactivity on the socketto wait before timeout-ing it. If sets to0, then the existing idletimeout is disabled. Defaults to30 seconds.
  • server.deadBackendTTL: the number of seconds a backend is flagged as'dead' before retrying to proxy another request to it (doesn't apply ifyou are using a third-party health checker). Defaults to30 seconds.
  • server.retryOnError: retries limit. Defaults to3.
  • server.accessLog: location of the Access logs, the format is the sameas nginx. Defaults to/var/log/hipache/access.log if not specified.
  • server.httpKeepAlive: enable/disable keep-alive functionality.Defaults tofalse (disabled).
  • server.deadBackendOn500: consider500 HTTP status code as criticalerror if sets totrue. Defaults totrue.
  • server.staticDir: the absolute path of the directory containing yourcustom static error pages. Default valuenull means it uses Hipache'spages. Defaults to Hipache'sstatic/ directory.
• http: specifies on which ips/ports Hipache will listen for http traffic.By default, Hipache listens only on 127.0.0.1:80
  • http.port: port to listen to for http. Defaults to80.
  • http.bind: IPv4 (or IPv6) address, or addresses to listen to. You canspecify a single ip, an array of ips, or an array of objects{address: IP, port: PORT} if you want to use a specific port on a specific ip.Defaults to127.0.0.1.
• https: specifies on which ips/ports Hipache will listen for httpstraffic. By default, Hipache doesn't listens for https traffic.
  • https.port: port to listen to for https. Defaults to443.
  • https.key: path to key file to use. No default.
  • https.passphrase: optional passphrase for the key file. No default.
  • https.cert: path to certificate file to use. No default.
  • https.ca: optional path to additional CA file to serve. Might be astring, or an array.
  • https.bind: similarly to http.bind, you can specific a single IP, anarray of IP, or an array of objects to override the port, key/cert/cafiles on a per-IP basis.
  • https.secureProtocol: SSL/TLS protocol to use. Defaults toSSLv23_method (auto-negotiation).
  • https.secureOptions: extra options to pass to the SSL/TLS layer. Rawvalues must be provided. For instance, defaults is50331648, and standsforSSL_OP_NO_SSLv3 | SSL_OP_NO_SSLv2 (constants).
  • https.ciphers: cipher suites. See the default value above.
  • https.honorCipherOrder: when choosing a cipher, use the server'spreferences instead of the client preferences. Defaults totrue.
• driver: driver URL to connect to for dynamic VHOST configurations. Seedrivers section for more information. Defaults toredis:.
• user: if starting asroot (which you might do if you want to use aprivileged port), will drop root privileges as soon as it's bound. Defaultstowww-data. Note that you MUST specify a user if you start Hipache asroot. You can specifyuser: 'root' if you don't mind (stronglydiscouraged!). You can use either user names or identifiers.
• group: if starting asroot, will downgrade group to this. If leftempty, will try to downgrade to a group named after the specifieduser.Defaults towww-data.

From the shell (defaults to using theconfig/config.json file):

$ hipache

If you use a privileged port (e.g.:80):

$ sudo hipache

If you want to use a specific configuration file:

$ hipache --config path/to/someConfig.json

If you want to just test a specific configuration file:

$ hipache --dry --config path/to/someConfig.json

Managing multiple configuration files:

The default configuration file isconfig/config.json. It's possible to havedifferent configuration files namedconfig_<suffix>.json, where the suffix isthe value of an environment variable namedSETTINGS_FLAVOR.

For instance, here is how to spawn the server with theconfig_test.jsonconfiguration file in order to run the tests.

$ SETTINGS_FLAVOR=test hipache

All VHOST configuration is managed through a configuration backend (cf.drivers). This makes it possible to update the configurationdynamically and gracefully while the server is running, and have that stateshared across workers and even across Hipache instances.

The recommended backend to use isRedis. It also makes it simple to writeconfiguration adapters. It would be trivial to load a plain text configurationfile into Redis (and update it at runtime).

Different configuration adapters will follow, but for the moment you have toprovision the Redis manually.

Let's take an example to proxify requests to 2 backends for the hostnamewww.dotcloud.com. The 2 backends IP are192.168.0.42 and192.168.0.43 andthey serve the HTTP traffic on the port80.

redis-cli is the standard client tool to talk to Redis from the terminal.

Follow these steps:

1. Create the frontend and associate an identifier:

    $ redis-cli rpush frontend:www.dotcloud.com mywebsite (integer) 1

The frontend identifer ismywebsite, it could be anything.

2. Associate the 2 backends:

    $ redis-cli rpush frontend:www.dotcloud.com http://192.168.0.42:80 (integer) 2 $ redis-cli rpush frontend:www.dotcloud.com http://192.168.0.43:80 (integer) 3

3. Review the configuration:

    $ redis-cli lrange frontend:www.dotcloud.com 0 -1 1) "mywebsite" 2) "http://192.168.0.42:80" 3) "http://192.168.0.43:80"

While the server is running, any of these steps can be re-run without messing upwith the traffic.

Upstart

Copyupstart.conf to/etc/init/hipache.conf. Then you can use:

start hipachestop hipacherestart hipache

The configuration file used is/etc/hipache.json.

Hipache supports several drivers for dynamic VHOST configurations.

This is the default backend.

If you want a master/slave Redis, specify a second url for the master, e.g.:driver: ["redis://slave:port", "redis://master:port"]. More generally, thedriver syntax is:redis://:password@host:port/database#prefix - all parameterare optional, hence justredis: is a valid driver URI. You can omit thisentirely to use the local redis on the default port, which is the default.

See thedriversdocumentation.

See thedriversdocumentation.

See thedriversdocumentation.

As seen in the example above, multiple backends can be attached to a frontend.

All requests coming to the frontend are load-balanced across all healthybackends.

The backend to use for a specific request is determined randomly. Subsequentrequests coming from the same client won't necessarily be routed to the samebackend (since backend selection is purely random).

If a backend stops responding, it will be flagged as dead for a configurableamount of time. The dead backend will be temporarily removed from theload-balancing rotation.

To optimize response times and make use of all your available cores, Hipacheuses the cluster module (included in NodeJS), and spreads the load acrossmultiple NodeJS processes. A master process is in charge of spawning workers andmonitoring them. When a worker dies, the master spawns a new one.

The memory footprint of Hipache tends to grow slowly over time, indicating aprobable memory leak. A close examination did not turn up any memory leak inHipache's code itself; but it doesn't prove that there is none. Also, we did notinvestigate (yet) thoroughly the code of Hipache's external dependencies, so theleaks could be creeping there.

While we profile Hipache's memory to further reduce its footprint, weimplemented a memory monitoring system to make sure that memory use doesn't goout of bounds. Each worker monitors its memory usage. If it crosses a giventhreshold, the worker stops accepting new connections, it lets the currentrequests complete cleanly, and it stops itself; it is then replaced by a newcopy by the master process.

You can alter the configuration stored in Redis at any time. There is no need torestart Hipache, or to signal it that the configuration has changed: Hipachewill re-query Redis at each request. Worried about performance? We were, too!And we found out that accessing a local Redis is helluva fast. So fast, that itdidn't increase measurably the HTTP request latency!

Hipache supports the WebSocket protocol. It doesn't do any fancy handlingon its own and relies entirely on NodeJS and node-http-proxy.

Hipache supports SSL for "regular" requests as well as WebSocket upgrades.Hipache's default configuration matches latest recommandations for a secure andwell-configured SSL/TLS layer.

When something wrong happens (e.g., a backend times out), or when a request foran undefined virtual host comes in, Hipache will display an error page. Thoseerror pages can be customized, and a configuration parameter (server.staticDir)is available to specify where these custom pages are located.

When adding virtual hosts in Hipache configuration, you can specify wildcards.E.g., instead (or in addition to)www.example.tld, you can insert*.example.tld. Hipache will look for an exact match first, and then for awildcard one up to 5 subdomains deep, e.g.foo.bar.baz.qux.quux will attemptto match itself first, then*.bar.baz.qux.quux, then*.baz.qux.quux, etc.

Even though Hipache support passive health checks, it's also possible to runactive health checks. This mechanism requires to run an external program (seethird-party softwares below).

SeeCONTRIBUTING.md

Health-checkers:

• hipache-hchecker (golang)
• hipcheck (node.js).

A web interface to manage VHOSTs:

• airfield

PaaS

• tsuru (golang)