terraeclipse-dgate

# dgate Domain gateway, a simple clustered HTTP virtual host router ## Purpose `dgate` is a Node.js-based HTTP gateway. It can proxy or redirect incoming requests to any host or port, based on a flexible set of rules, defined as comments in your `/etc/hosts` file. `dgate` makes use of [cluster](http://nodejs.org/api/cluster.html) forking for better performance on a multi-core machine, and privilege separation for better security. Features: - serve an arbitrary number of web apps on a single port - SSL termination - virtual host matching on domain, subdomain, wildcard, or path - develop several apps locally, and use domains like `test.dev` - enforce canonical domains, SSL, or redirect certain domains/paths to arbitrary locations - central logging for all requests - use all your CPUs with flexible worker pool - simple hot-reloadable configuration via `/etc/hosts` ## Install ``` $ [sudo] npm install -g dgate ``` ## Start the server ``` $ sudo dgate --verbose --port 80 ``` On POSIX you can drop privileges for tighter security: ``` $ sudo dgate --port 80 --setuid nobody --setgid nogroup ``` To enable SSL, use these options: ``` $ sudo dgate --port 443 --sslCert /path/to/server.pem --sslKey /path/to/server.key --setuid nobody --setgid nogroup ``` ## Configuration `dgate` works by reading the domain -> IP mappings in your `/etc/hosts` file and turning them into virtual hosts. Additionally you **MUST** provide a `#dgate` comment above each line you wish to enable as a virtual host: ``` #dgate option1=value1&option2=value2 <ip1> <hostname1> [hostname2...] #dgate option1=value1&option2=value2 <ip2> <hostname3> [hostname4...] ``` ### /etc/hosts Example ``` # route traffic from my.dev to 127.0.0.1:3000 #dgate port=3000 127.0.0.1 my.dev # route traffic from *.myother.dev to 127.0.0.1:3001 #dgate port=3001&wildcard=true 127.0.0.1 myother.dev # route traffic from *.blah.dev to terraeclipse.com #dgate target=terraeclipse.com&wildcard=true 127.0.0.1 blah.dev # make this the default vhost, with a canonical url (also force https) #dgate port=3002&default=true&canonical=s8f.org&https=true 127.0.0.1 s8f.org www.s8f.org # redirect requests from mytemp.com to myreal.com/$path #dgate redirect=myreal.com__path 127.0.0.1 mytemp.com ``` ### Order of operations 1. If a match is found, the one first defined is served 2. else if defined, the default is served 3. else a 404 response is generated. To disable a rule, just add a space between `#` and `dgate`. ### Virtual host options Values must be properly urlencoded, i.e. in JavaScript `encodeURIComponent(value)` - `port=number` (**required** unless using an alternative listed below) - the TCP port of the target to proxy to, appended to the IP from the `/etc/hosts` rule. - `target=host[:port]` (alternative to `port`) - the target host, and optional port to proxy to, i.e. `example.com:80` (supports token replacement, see below) - `redirect=url` (alternative to `port`) - redirect all requests to the specified url. (supports token replacement, see below) - `file=abspath` (alternative to `port`) - serve a file instead of proxying or redirecting. (path supports token replacement, see below) - `path=glob` - match the virtual host only if the incoming path matches the glob. i.e. `/some/**/path` - `canonical=host` - redirect requests to this hostname if the request's `Host` header doesn't match it. i.e. `www.example.com` - `wildcard=true` - also accept requests to subdomains of the matched hostname. - `default=true` - treat the virtual host as "default", falling back to it if no other matches are found. - `https=true` - force HTTPS by redirecting requests to `https://` version of URLs. - `sethost=host` - artificially set the `Host` header when forwarding requests to the proxy target. i.e. `specific.host.example.com` ### Token replacement Some options such as `redirect` can contain placeholders to be filled in by request variables: ``` #dgate redirect=http%3A%2F%2Fwww.example.com%2F%3Fhref%3D__href_u 127.0.0.1 mydomain.com ``` This will redirect requests from mydomain.com to `http://www.example.com/?href=(urlencoded version of the originally requested absolute URL)` #### Auto URL encoding - For the raw token value, use `__[name]` (leading double underscore). - For the urlencoded token value, use `__[name]_u` - For the double-urlencoded token value, use `__[name]_uu` #### Supported tokens - `__protocol` The incoming protocol string, i.e. `https:` - `__auth` The incoming basic auth string, i.e. `my:pass` - `__host` The incoming host:port string, i.e. `example.com:3000` - `__port` The requested port, i.e. `3000` - `__hostname` The requested domain name, i.e. `example.com` - `__search` The requested query string including `?`, i.e. `?blah=1&foo=bar` - `__query` The requested query string, excluding `?` i.e. `blah=1&foo=bar` - `__pathname` The requested path, excluding query string, i.e. `/some/path` - `__path` The requested path, including query string, i.e. `/some/path?blah=1&foo=bar` - `__href` The requested absolute URL, i.e. `http://my:pass@localhost:3000/some/path?blah=1&foo=bar` - `__ip` The remote IP address, i.e. `127.0.0.1` ## TODO - path rewriting, i.e. proxy `http://test.dev/myapp/*` to `http://127.0.0.1:3000/*` - option for redirect status code, 302 or 301 - custom error pages - redundant targets + load balancing strategy