HAProxy management and orchestration module
Here be deamons, this module is still under heavy development not all parsersare hooked up on the API's yet. Feel free to contribute and build the bestHAProxy orchestration module out there.
HAProxy is an amazing proxy, it has support for many different algorithms for
load balancing, it can handle HTTP, TCP, WebSocket connects, does SSL
termination and much much more. But managing these proxies can be a bit of
a pain. That's where
haproxy comes in, it provides a access to the stat socket
of HAProxy which allows you to enable, disable servers and front-ends, read out
stats and much more. In addition to that it's also capable of hot reloading
configuration changes and starting, stopping your HAProxy, even when it's
running as a daemon.
The package is released in
npm, the Node.js package registry:
npm install haproxy --save
Tests can be executed after installation by running
npm test. For test to run
properly Haproxy 1.5.1 or greater is required. See commands below:
sudo apt-get install -qq build-essential libssl-dev libev-devwgettar xzvf haproxy-1.5.1.tar.gzcd haproxy-1.5.1sudo make installnpm test
- For Linux run:
make TARGET=linux26 USE_OPENSSL=1
- For Solaris/Smart OS:
make TARGET=solaris USE_OPENSSL=1
- For Mac:
make TARGET=generic USE_OPENSSL=1
And finally run:
sudo make installnpm test
In order to make your HAProxy installation work with this module you need to
stats socket interface of HAProxy. If you don't have this specified
in your configuration please add the following to the
global section of your
global# Exposes the stat socket so we can manage the proxy through node.jsstats socket /tmp/haproxy.sock level admin
Reload you configuration to make this change active and you should be ready to rock.
'use strict';var HAProxy = require'haproxy';var haproxy = '/optional/socket/path.sock' /* options */ ;
An alternate interface is:
var haproxy = socket: 'path' /*, the rest of the options */;
I personally prefer the first interface as a correct socket path is required for a functioning module. The options are not required, but the following options are supported:
pid: The process id
pidFile: The location of the pid file
config: The location of the configuration file
discover: Tries to find your HAProxy instance if you don't know the pid
socket: The location of the unix socket
which: The location of the HAProxy
prefix: Prefixes the HAProxy commands. Useful for
There's a lot of freedom in this module, callbacks are always optional so you can do fire and forget management as well as how you add the callbacks.
haproxymethod'value' ;//// Is the same as//haproxymethod'value'call ;
It also supports a chaining API:
haproxymethodandmethod2'value'andmethod3'value'// woop woop;//// The example above will call method() and method() as fire and forget and// method3() is called with a callback. It doesn't maintain order so it could be// that method() is called after method3() as it could take longer to complete.//
The following methods are available:
Start a new HAProxy instance with the given configuration. It will verify the
configuration before it attempts to start HAProxy. The process will
automatically be daemonized and the pidFile will be stored in the supplied
pidFile location or default to
Please note that it does not check if there are any HAProxy processes running.
haproxystartyay it's started ..});
Stops the currently running HAProxy process, even if it's not started using
HAProxy.start it will find the process using the supplied pidFile argument or
scans the process list for a running process.
all boolean is supplied it will kill all running HAProxy processes
instead of the first one it found.
haproxystopthe proxy is stopped;
This executes a softstop on all running HAProxy installations. So instead of termining all active connections it will wait for them to finish and then, kill the process.
Hot reload the configuration without any downtime. If the
hard boolean is
given it will terminate the process forcefully and kill all active connections.
Before it reloads it will again, verify the configuration so we don't create any broken mess.
haproxyreloadthe proxy has reloaded;
Verify the given configuration to see if it's all in working order.
HAProxyverifyfailed to do thingsif working yay configuration is working;
Scans the system for running HAProxy instances. It's mostly used internally but it might be useful for you as well.
HAProxyrunningif running yup process running;
Clear the max values of the statistic counts in the proxy for each front-end and
backend. When the
all boolean is supplied it will clean all the stats. This
has the same effect as restarting.
haproxyclear// stats cleared
Mark the given server a down for maintenance, in this mode no checks will be preformed on the server until it leaves maintenance.
haproxydisable'realtime' 'server1'// server out of the pool;
If the server was previously marked as down for maintenance, it will mark the server as up again and all checks will be re-enabled.
haproxyenable'realtime' 'server1'// server enabled again;
Mark the frontend as temporarily stopped. This corresponds to the mode which is used during a softrestart. The frontend releases the port it was bound on but it can be enabled again when needed.
haproxypause'frontend'// disable the frontend;
Resume the front-end that you previously paused.
haproxyresume'frontend'// enable the frontend;
Show the server errors or the errors for the given session id. The session id is optional.
Get the assigned weight for the server from the given backend.
weight argument is set, it will automatically set the weight for this
haproxyweight'backend' 'server1' 10// woop;
Please note that the weight should be between 0 and 255
Update the maxconnection setting for the frontend.
haproxymaconn'public' 809809// handle failures.;
If no frontend is supplied it will apply this configuration globally
haproxymaconn809809// handle failures.;
Change the process-wide rate limit. Setting this value to 0 will disable the rate-limitter.
haproxyconnections4242// handle errors ._.;
Change the maximum input compression rate.
haproxycompression3// oh noes. error handling, but this is optional, if you don't care about// errors;
Retrieve some information about the HAProxy
haproxy.info// do something with the info..;
Dump all know session if no session id is provided.
Dump all statistics, if you want everything, supply -1 for all values.
haproxystat'-1' '-1' '-1';
Copyright (c) 2013 Observe.it (http://observe.it) email@example.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.