Easy to setup, convenient, universal, parallel, http/https proxy daemon. Setup in 1 minute, run, configure, adapt. Proxying based on excellent node-http-proxy.

npm install http-master
100 downloads in the last week
120 downloads in the last month


Build Status Code Climate


http-master is a front end http service/reverse-proxy with easy setup of proxying/redirecting/other-actions logic. It can run as a module or as a standalone application. Your average use case could be having several web applications running on different internal ports and Apache running on port 8080. http-master allows you to easily define rules which domain should target which server and if no rules match, everything else could go to the Apache server. This way you setup your SSL in one place, in http-master and even non-SSL compatible http server can be provided with HTTPS.

Some of the features:

  • Automatic loading of certificates from specific directory. Zero-effort HTTPS configuration.
  • Support SNI extension - multiple SSL certificates on the same IP.
  • Easy all in one place configuration for every listening port (eg. 80 and 443 together)
    • Setup reverse proxy with optional URL rewriting and optional regexp matching of host and/or path.
    • Setup redirect with optional regexp matching to construct final URL.
    • Setup basic static files server for a given route.
    • Setup Basic-AUTH for a given route (sponsored feature)
  • Multi-core/cpu friendly. Runs multiple instances/workers which will serve connections in a round-robin fashion. You of course choose to run in the same process without any workers if you use http-master as a module.
  • SSL tweaked to reasonable security level supporting TLS session resumption.
  • Automatically watches for config changes and reloads the logic without any downtime (*). Simply start the deamon and add new rules while having the http-master online.
  • Asynchronous logging module. Logs either to stdout or to file.
  • Possibility to load config from Redis/etcd or another remote resource. (**)
  • May drop privileges to user/group once started.

Ongoing development on:

  • Easier and easier configuration format.
  • Automatic management of time expiration of certificates.
  • Request/response filters. (including ability to add headers, modify data)

(*) Zero downtime is possible, currently downtime may be few milliseconds. (**) Needs writing a custom config loader.

Installation and usage

Refer to section Usage as a module if you are interested in that use-case.

To install, Node.JS is required to be installed and in your PATH: npm install -g http-master (may be needed to run as root depending on your setup)

To run: http-master --config http-master.conf

Config files may be written in either JSON or YAML. For the sake of documentation all examples will be written in YAML.

Simple example config (more advanced features are convered elsewhere):

watchConfig: true # watch config file for changes
logging: false # See "Logging" section on details
ports: { # each port gets a separate configuration
  80 {
    proxy: {
      # Proxy all traffic at domain to port 8099
      '' : 8099,
      # Proxy all traffic for any subdomains of to IP and port 8099
      '*' : '', 
      # Proxy remaning traffic to port 8080, for example Apache could run there
      '*' : 8080
    redirect: {
      # redirect .net requests to .com
      '': '[path]',
      # redirect http to https
      '': '[path]'
    static: {
      # Serve static files from specific directory
      '': '/var/www/code2flow/assets'
  443: {
    proxy: {
      '': '',
       # choose application depending on path
      '*': 10443,
       # choose application depending on path
      '*': 15000,
      # all remaining https traffic goes to port 4443, for example apache
      "*": ""
    redirect: {
       # redirect .net requests to .com
      '': '[path]' 
    ssl: {
      # needs to be provided for non-SNI browsers
      primaryDomain: "",
      # simply put certificates inside this dir, run with --debug=config to see what was read
      certDir: "/etc/http-master/certificates" 

Usage as a module

npm install --save http-master
var HttpMaster = require('http-master');
var httpMaster = new HttpMaster();
 // your config in here
}, function(err) {
 // listening

Class: HttpMaster

Event: 'allWorkersStarted'

function() Emitted after succesful .init()

Event: 'allWorkersReloaded'

function() Emitted after succesful .reload()

Event: 'logNotice'

function(msg) Helpful logging information in case something got wrong.

Event: 'logError'

function(msg) Information about errors that could be logged.

Event: 'error'

function(err) Emitted on failure to listen on any sockets/routes or failure to use given configuration.

httpMaster.init(config, [callback])

Initialize http master with a given config. See the section about config to learn about acceptable input. Callback if given will call function(err). This function should be called only once.

httpMaster.reload(config, [callback])

Perform a zero-downtime reload of configuration. Should be very fast and ports will not stop listening. Stopping httpMaster may be done using httpMaster.reload({}). Which should close all servers.

Note: Changing workerCount is the only thing that may not change.

Watch config for changes

Add --watch or add to config "watchConfig": true.

You may also trigger reload manually by sending USR1 signal to the master process. (only on *nix)

If you run via systemd then you may use the following systemctl reload http-master.service

Use custom config loader

See this repository for an example

URL rewrite

TODO (open an issue if you need info now)

URL rewrite

TODO (open an issue if you need info now)


TODO (open an issue if you need info now)


TODO (open an issue if you need info now)


Sample logging entry:



  • timestamp - time when request started
  • method - HTTP method
  • httpVersion - protocol version
  • url - URL from the request
  • headers - all HTTP headers
  • statusCode - code that application sent
  • responseTime - time taken to finish the response

Log to stdout:

logging: true,
ports: {
  # port configuration goes here

Log all requests to file:

logging: {
  accessLog": "/var/log/http-master-access.log"
ports: {
  # port configuration goes here

Log to file and move existing standard output to separate file:

logging: {
  accessLog": "/var/log/http-master-access.log"
  appLog": "/var/log/http-master.log"
ports: {
  # port configuration goes here

If you wish to have a specific formatting of access log, please open an issue with your request.


We provide an example systemd unit file. The config file is set to /etc/http-master/http-master.conf by default. Copy the http-master.service to /etc/systemd/system to use it.

  • systemctl start/stop/restart http-master
  • systemctl enable http-master - auto-start
  • systemctl reload http-master - reload config with kill -USR1



eeGeo - basic HTTP authentication against htpasswd file #32

Please open an issue if you would like a specific feature to be implemented and sponsored.


Copyright (c) 2013-2014 Code Charm Ltd

Licensed under the MIT license, see LICENSE for details.

npm loves you