Wondering what’s next for npm?Check out our public roadmap! »

    boss-cli

    2.0.0 • Public • Published
    Control your processes like a boss

    boss

    Discuss Build Status Dependency Status

    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

    Install

    npm i boss-cli

    DownloadsWeekly Downloads

    7

    Version

    2.0.0

    License

    none

    Last publish

    Collaborators

    • avatar