fib-runner

process manager developed using fibjs

fib-runner is a process manager developed using fibjs, it runs in client/server mode, it allows the server to run in a secure user, keeps the processes safe and secure, allows the client to manage the processes, view the output logs of the processes and monitor the process resource usage.

Install

fibjs --install fib-runner [--save]

Running runnerd

Execute the following command:

fibjs runnerd

will start the runnerd daemon. The daemon will run in the background and you can continue other work in the terminal or log out without suspending the daemon.

Run as a console

Runs in console mode:

fibjs runnerd --console

When running in console mode, runnerd will enter the runnerctl console immediately after startup, and you can manipulate child processes from the console. This is useful when starting runnerd within docker.

Install runnerd as a service

Using runnerctl, runnerd can be installed as a system service and run automatically at system startup.

sudo fibjs runnerctl install
sudo fibjs runnerctl uninstall

Configuration File

The configuration file name is runner.json and needs to be stored in the current directory of the operating system when running runnerd. runnerd will automatically load the configuration file and start the specified process according to the configuration file.

The configuration file is a json formatted file that must contain an array of fields named "apps" that specify the configuration of the process.

The basic format of the configuration file is as follows:

{
    "name": "fib-runner",
    "description": "fibjs service runner",
    "listen": {
        "address": "127.0.0.1",
        "port": 1123
    },
    "apps": [
        {
            "name": "exec_name",
            "exec": "/path/to/app"
        },
        {
            "name": "script_name",
            "script": "/path/to/app.js"
        },
        {
            "name": "prj_name",
            "runner": "/project/path/to"
        },
    ]
}

Each process is configured with the following parameters:

Name	Description	Default
name	process name	undefined
description	description of the process	'app_description'
exec	exec file, runnerd will start the program directly	undefined
script	script file, runnerd will use fibjs to start the script program	undefined
runner	external runner folder, runnerd will load runner.json from this directory as a subproject	undefined
cwd	the working directory when the process starts	undefined
arg	the list of parameters when the process is started	[]
env	the environment variables when the process starts	{}
autostart	If true, this program will start automatically when runnerd is started.	true
startsecs	Number of seconds between retries	1
startretries	Number of consecutive failures allowed before abandonment, set to -1 for unlimited retries	3
autorestart	Specify whether to automatically restart	true
savelog	Automatically save logs when a process exits abnormally	false
signal	SIGTERM, SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGUSR1, or SIGUSR2	"SIGTERM"

The simplest process configuration must contains at least name and one of exec and script. When both exec and script are specified, runnerd will ignore the script configuration.

Sub project

By configuring the property runner in runner.json , runnerd can manage external projects. For example, we have a runner project, which is stored under the directory ext-app, and the content of runner.json is as follows:

{
    "apps": [
        {
            "name": "app5",
            "script": "app5.js"
        }
    ]
}

In the main runner.json configuration, add the sub project as follows:

{
    "apps": [
        {
            "name": "ext",
            "runner": "ext-app"
        }
    ]
}

After running runnerd we will get a process list like this:

(index)	pid	status	retries	uptime	user	sys	rss
ext.app5	50026	RUNNING	0	5.8s	0.02%	0.01%	28.41 MB

Remote management

By default, runnerd does not allow remote control, and the control interface is bound to ip 127.0.0.1. If you want to control the runnerd service remotely, you need to manually modify runner.json to enable remote management.

step 1, you need to allow external ip access control interface:

{
    "listen": {
        "address": "0.0.0.0",
        "port": 1123
    }
}

step 2, check runner.json in an admin node to find your public key, if runner.json does not exist, you can run runnerctl to generate it automatically:

{
    "key": {
        "pub": "AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ",
        "key": "wHo9IdgYD-XattkLC8uj85T0G1a-ZPob0PELQVUv2aE",
        "admin": []
    },
}

step 3, add your public key "AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ" to the admin list of runner.json in the worker node::

{
    "key": {
        "pub": "A8Vw0C1U0nEkXLQBQ0GzC8WIPZyyt-UtNsVMvnMuSJaX",
        "key": "6u3vfP8yRMgePxcDqPBZVNrOKD2iSAKKdN8SA6iKCXk",
        "admin": [
            "AmqJ_fkfQxKnuoG3-fkgNs51jVMj6oS9-XvPGw7Np4ZJ"
        ]
    }
}

Now you can control the runnerd service in the worker node from the admin node:

fibjs runnerctl -s ip:port

Running runnerctl

To start runnerctl, run:

fibjs runnerctl [-s ip:port] [command] [...args]

A shell will be presented that will allow you to control the processes that are currently managed by runnerd. Type “help” at the prompt to get information about the runnerd commands. runnerctl supports the following commands:

Command	Description
help	Print this help message
install	Install runnerd as a service
uninstall	Uninstall runnerd service
list	Display all processes status
reload	Reload runner.json
stop name	Stop specific process name
start name	Start specific process name
restart name	Restart specific process name
log name [80]	Monitor output log of specific process name
attach name [80]	Attach output log of specific process name, ctrl+z to exit
.{stat} name [1]	Monitor {stat} statistics of specific process name {stat} will be rss, cpu, user, sys etc.
exit	Exit runnerctl

The runnerctl command can also be executed from the command line, such as:

fibjs runnerctl list

Security control

In order to avoid security issues caused by illegal users using runnerd to elevate runtime privileges, only control and monitor operations are allowed in runnerctl, and there is no permission to modify or add processes. If you want to modify or add processes, you need to modify runner.json manually and reload the processes using the reload command. The administrator needs to ensure that runner.json is not allowed to be modified by anyone.

Unexpected exit log

When the managed child process exits, if runnerd detects that this is an unexpected termination, it will automatically save the output of the child process to a log file named log_${pid}.txt.

Used as a module

You can also use fib-runner as a module, allowing more flexibility to customize process management to your needs by programming the fib-runner api directly.