A helper script for managing a cluster of node worker servers
A module for taking advantage of the built-in
cluster module in node
v0.8 and above.
server.js file uses this module to fire up a cluster of
workers. Those workers then do the actual server stuff (using socket.io,
express, tako, raw node, whatever; any TCP/TLS/HTTP/HTTPS server would
This module provides some basic functionality to keep a server running. As the name implies, it should only be run in the master module, not in any cluster workers.
var clusterMaster =// most basic usage: just specify the worker// Spins up as many workers as you have CPUs//// Note that this is VERY WRONG for a lot of multi-tenanted// VPS environments where you may have 32 CPUs but only a// 256MB RSS cap or something.// more advanced usage. Specify configs.// in real life, you can only actually call clusterMaster() once.// methodsclusterMaster// graceful rolling restartclusterMaster// graceful shutdownclusterMaster// not so graceful shutdownclusterMaster
Set the cluster size to
n. This will disconnect extra nodes and/or
spin up new nodes, as needed. Done by default on restarts.
One by one, shut down nodes and spin up new ones. Callback is called when finished.
Gracefully shut down the worker nodes and then process.exit(0).
Forcibly shut down the worker nodes and then process.exit(1).
silent configs are passed to the
cluster.fork() call directly, and have the same meaning.
exec- The worker script to run
env- Envs to provide to workers
argv- Additional args to pass to workers.
silent- Boolean, default=false. Do not share stdout/stderr
size- Starting cluster size. Default = CPU count
signals- Boolean, default=true. Set up listeners to:
onMessage- Method that gets called when workers send a message to the parent. Called in the context of the worker, so you can reply by looking at
repl- where to have REPL listen, defaults to
replis null or false - REPL is disabled and will not be started
replis string path - REPL will listen on unix domain socket to this path
replis an integer port - REPL will listen on TCP 0.0.0.0:port
replis an object with
port, then REPL will listen on TCP address:PORT
Examples of configuring
var config = repl: false // disable REPLvar config = repl: '/tmp/cluster-master-sock' // unix domain socketvar config = repl: 3001 // tcp socket 0.0.0.0:3001var config = repl: address: '127.0.0.1' port: 3002 // tcp 127.0.0.1:3002
Note: be careful when using TCP for your REPL since anyone on the network can connect to your REPL (no security). So either disable the REPL or use a unix domain socket which requires local access (or ssh access) to the server.
Cluster-master provides a REPL into the master process so you can inspect
the state of your cluster. By default the REPL is accessible by a socket
written to the root of the directory, but you can override it with the
CLUSTER_MASTER_REPL environment variable. You can access the REPL with
nc or socat like so:
nc -U ./cluster-master-socket# ORsocat ./cluster-master-socket stdin
The REPL provides you with access to these objects or functions:
help- display these commands
repl- access the REPL
resize(n)- resize the cluster to
restart(cb)- gracefully restart workers, cb is optional
stop()- gracefully stop workers and master
kill()- forcefully kill workers and master
cluster- node.js cluster module
size- current cluster size
connections- number of REPL connections to master
workers- current workers
select(fld)- map of id to
pids- map of id to pids
ages- map of id to worker ages
states- map of id to worker states
a1to stdout and all REPLs
sock- this REPL socket'
.exit- close this connection to the REPL