boss-cli
v2.0.0
Published
A node process manager that isn't spanners all the way down
Downloads
21
Maintainers
Readme
boss
A node process manager that isn't spanners all the way down.
Features
- Monitoring in console
- Configure user/group to run processes as
- Auto process restart on crash
- Log redirection to per process out/err files
- Web interface with support for monitoring multiple hosts
- Cluster support
Install
npm install -g process-boss
## Usage
Comprehensive help is available on the command line:
bs --help
and with more detail for each subcommand, e.g.:
bs start --help
The first time you invoke a boss command, the daemon will start in the background. Because boss can run processes as different users, it needs to be able to switch to those users. Consequently you should run boss as root or another privileged user.
list
bs list
Display a list of processes boss has started.
start
bs start [options] <script>
Start a new process.
args
-h, --help output usage information
-u, --user <user> The user to start a process as
-g, --group <group> The group to start a process as
-i, --instances <instances> How many instances of the process to start (e.g. cluster mode)
-n, --name <name> What name to give the process
-a, --argv <argv> A space separated list of arguments to pass to a process
-e, --execArgv <execArgv> A space separated list of arguments to pass to the node executable
-d, --debug Pause the process at the start of execution and wait for a debugger to be attached
-v, --verbose Prints detailed internal logging output
e.g.
To start http-server.js
as a cluster with two workers, running as alex:staff
and with two command line arguments -a foo
and -b bar
$ bs start -u alex -g staff -i 2 -argv '-a foo -b bar' http-server.js
restart
Restart a running process
bs restart <pid>
stop
Stop a running process.
bs stop <pid>
kill
Stop all processes and kill the daemon. By default all currently running processes will be saved and restarted when boss restarts.
bs kill
cluster
After starting a process with -i $num
(e.g. start ``$num` instances of a script), adjust the number of cluster workers.
bs cluster <pid> <workers>
e.g.
Make process 49308 (previously started with -i 2
) run with 4 workers:
$ bs cluster 49308 4
The maximum workers you can set is dependent on your system as num_cpus - 1
send
Send an event to a process
bs send <pid> <event> [args...]
e.g.
In my script
process.on('my:custom:event', function(arg1, arg2) {
console.info(arg1 + arg2)
})
$ bs send 39823 my:custom:event 1 2
// process 39823 then prints '3' to the logs
heapdump
Make a process dump a heap snapshot for analysis in Chrome's debug tools.
bs heapdump <pid>
gc
Force a process to do garbage collection
bs gc <pid>
signal
Send a signal to a process (n.b. unless you have a listener for that signal, your process will most likely exit)
bs signal <pid> <signal>
e.g.
$ bs signal 3984 SIGINT
logs
Show live logs for a process (or all processes if <pid>
is omitted) in the console
bs logs [pid]
dump
Dump a processes.json
file of running processes to $CONFIGDIR
for use with bs restore
bs dump
restore
Restore running processes from $CONFIGDIR/processes.json
bs restore
remoteconfig
For use with boss-web - see boss-web's setup for more information
bs remoteconfig
useradd
To add a user for boss-web - see boss-web's setup for more information. If you specify [hostname]
the configuration output is more likely to be correct.
bs useradd [options] <username> [hostname]
rmuser
To remove a user for boss-web - see boss-web's setup for more information.
bs rmuser <username>
lsuser
To list users for boss-web - see boss-web's setup for more information.
bs lsusers
reset
To reset the secret for a boss-web user - see boss-web's setup for more information.
bs reset <username>
Configure
Boss uses rc so it looks for configuration files in sensible places. The default configuration file looks like:
[boss]
; The user the daemon will run as - this user should have sufficient
; privileges to spawn new processes and then drop their privileges to
; that of other users
user = root
; The group the daemon will run as - if you wish to interact with boss
; you should be in this group
group = staff
; Where boss puts log files. Will be created on first run.
logdir = /var/log/boss
; Where the dnode sockets are stored. Will be created on first run.
rundir = /var/run/boss
; Where remote user configuration is stored - should only be accessible
; to ${boss.user}
confdir = /etc/boss
; How long we should wait for remote processes to respond
timeout = 10000
; If true, when boss is killed it will dump process info to
; ${boss.rundir}/processes.json then, the next time it is started, read
; that file in and restart those processes
autoresume = true
[remote]
; If true, Boss will start an https server on ${remote.host}:${remote.port}
; to listen for incoming boss-remote connections
enabled = true
; The port Boss will listen on for incoming boss-remote connections
port = 57483
; The host Boss will list on for incoming boss-remote connections
host = 0.0.0.0
[remote.inspector]
; If true, Boss will start an instance of node-inspector in order to debug
; processes running on this host
enabled = true
; The port to use for the instance of node-inspector
port = 0
; The host to listen on for the instance of node-inspector
host = 0.0.0.0
[debug]
; Three possible options:
;
; 1. boolean - false (default) - the daemon process will run as normal
; 2. boolean - true - the daemon process will choose a random port and
; wait for a debugger to connect to it
; 3. int - the daemon will pause on startup and wait for a debugger to
; connect to the specified port
;
; n.b. if you change this option you will need to kill and restart the
; daemon for it to take effect.
; Unless you are debugging Boss itself, you probably want to leave this
; as false.
daemon = false
; If true, cluster managers will be started in debug mode when the -d
; flag is passed when starting a clustered process, otherwise just the
; cluster workers will be started in debug mode. Unless you are debugging
; Boss itself, you probably want to leave this as false.
cluster = false
See the default config file for more information on the various options.
Discuss: gitter.im/tableflip/boss