DESCRIPTION¶
mgrg (pronounced "em-greg") is a service manager. A
service is started as a number of concurrent processes serving application
requests, typically from reverse-proxy servers such as Apache, Nginx,
HAProxy or others. Use mgrg to create Golf applications, including both
service and command-line.
A number of options are available to setup and manage the
execution of a Golf program as an application server, which can be accessed
either via TCP/IP or a Unix domain socket.
<app name> specifies the name of your application. Each
application must have a unique name. <app name> may contain
alphanumeric characters and an underscore, must start with a character and
its maximum length is 30.
mgrg runs as a light-weight daemon (often requiring only 100-150K
of resident RAM), with a separate instance for each application specified by
the <app name>. When mgrg starts your service, its current directory
is set to /var/lib/gg/<app name>/app. The permissions context is
inherited from the caller, so the effective user ID, group ID and any
supplemental groups are that of the caller. You can use tools like runuser
to specifically set the permissions context.
mgrg will re-start service processes that exited or died, keeping
the number of processes as specified, unless -n option is used. The number
of worker processes can be specified with a fixed (-w) option, or it can
dynamically change based on the load (-d option), including none at all.
Hence, it is possible to have no worker processes at all, and they will be
started when incoming request(s) come in, and stay up as determined by the
request load.
<options> are:
• -i Initialize the directory and file structure
for application <app name>. If you are building application from source
code, this must be executed in the source code directory; mgrg will create
file ".golfapp" which identifies the application so
gg can
run in the directory. You must run as root when using this option (and must
not run as root otherwise) - this is the only mgrg option requiring sudo. The
directory structure is setup in /var/lib/gg/<app name> (see
directories).
• -u <user> The owner of your application.
This is only used when initializing directory structure used by mgrg (see -i
option). Do not use it otherwise. It cannot be root.
• -r <proxy group> The group of proxy web
server (such as Apache or Nginx). This is only used when initializing
directory structure used by mgrg (see -i option). Do not use it otherwise. It
restricts the ability to connect to your application only to the members of
said group (in addition to the user who owns your server) when a Unix socket
is used, otherwise anyone can connect.
• -f Run in the foreground. The process does not
return to the command line prompt until it is stopped. Useful for debugging
and where foreground processing is required.
• -p <port number> TCP/IP port number your
service program will listen on (and accept connections), if you are using
TCP/IP. You typically need to specify ProxyPass, "location" or
similar FastCGI directives in your proxy web server so it can connect to your
application. If you are using
Client-API or
call-remote, you
would use "<host name>:<port number>", for instance
"127.0.0.1:2301" if the server is local and <port number> is
2301. You can either use TCP/IP or Unix domain sockets (-x option). Typically,
you would use Unix domain sockets if proxy web server runs on the same
computer as your application server. If you specify neither -x nor -p, -x
(unix domain socket) is the default.
• -x Use Unix domain socket to connect from proxy
web server to your application server. This socket is automatically created by
mgrg and its full path name is "/var/lib/gg/<app
name>/sock/sock" (you can connect to it via
Client-API,
call-remote etc.). When using a proxy web server (like Apache or
Nginx), you typically need to specify ProxyPass, "location" or
similar FastCGI directives so it can connect to your application. If you
specify neither -x nor -p (TCP/IP socket), then -x (unix domain socket) is the
default.
• -l <backlog size> The size of socket
listening backlog for incoming connections. It must be a number between 10 and
SOMAXCONN-1, inclusive. The default is 400. Increase it if your system is very
busy to improve performance.
• -d Dynamically change the number of service
processes ("worker" processes) to match the request load (adaptive
mode). Use with "max-worker" and "min-worker" options. You
cannot use -w with this option. The number of processes needed is determined
based on any pending connections that are not answered by any running
processes. If there are more incoming connections than processes, the number
of processes will grow. If no such connections are detected (i.e. existing
processes are capable of handling any incoming requests), the number of
processes does not grow and will decrease to the point of minimum necessary
number of workers. In that case, given release time (-t option), the number of
processes will slowly decline until the incoming requests warrant otherwise.
The number of running processes thus will fluctuate based on the actual load,
these options, as well as --min-worker and --max-worker options. If neither -d
nor -w is specified, -d is the default.
• --min-worker=<min workers> Minimum number
of service processes that run in adaptive mode (-d option). The default is 5.
You can set this to 0 if needed to save memory. This option can be used only
with -d option.
• --max-worker=<max workers> Maximum number
of service processes that run in adaptive mode (-d option). The default is 20.
This option can be used only with -d option.
• -t <release time> Timeout before the
number of service processes is reduced to meet the reduced load. The default
is 30 seconds, and it can be a value between 5 seconds and 86400 seconds (i.e.
a day).
• -w <worker processes> Number of parallel
service processes ("worker" processes) that will be started. These
processes do not exit; they serve incoming requests in parallel, one request
per process. The number of processes should be guided by the concurrent user
demand of your application. If neither -d nor -w is specified, -d is the
default.
• -m <command> Send a command to mgrg daemon
serving an application. <command> can be "start" (to start
service processes), "stop" (to stop them), "restart" (to
restart them), "quit" (to stop mgrg daemon altogether) or
"status" (to display status of mgrg).
• -n Do not restart service processes if they exit
or die. However, in adaptive mode (-d option), this option has no effect.
• -g Do not restart service processes when their
executable changes. By default, they will be automatically restarted, which is
useful when in development, or upgrading the server executable.
• -a <args> Specify any command-line
arguments for your application (see "arg-count" and
"arg-value" clauses in
get-req). The <args> should be
double-quoted as a whole, while use of single quotes to quote arguments that
contain whitespaces is permitted.
• -z Suppress HTTP headers in all
service
handlers in the application. This is equivalent to having
silent-header
implied at the beginning of each
service handler. Use this option only
if service is not used as a web service (i.e. the output will not have HTTP
headers), or for testing or elsewhere where such headers may not be needed.
Otherwise, you can use "--silent-header" option in
gg or
"GG_SILENT_HEADER" environment variable in
Client-API to
control from command-line or a client if headers are output or not.
• -s <sleep millisecs> The basis time period
(in milliseconds) that mgrg will sleep before checking for commands (specified
by -m option), or check for dead service processes that need restarting. It
can be between 100 and 5000 milliseconds. Smaller value will mean higher
responsiveness but also higher CPU usage. The default value usually suffices,
and should not be changed without due consideration.
• -e Display verbose messages.
• -c <program> Full absolute path to your
service program. If omitted, the executable /var/lib/gg/bld/<app
name>/<app name>.srvc is assumed, which is the standard Golf service
executable. If present, but without any slashes in it to indicate path
(including current directory as ./), then this executable is assumed to be
/var/lib/gg/bld/<app name>/<program>.
• -v Display mgrg version (which matches Golf
version) as well as copyright and license.
• -h,--help Display help.
mgrg writes log file at /var/lib/gg/<app name>/mgrglog/log
file. This file is overwritten when mgrg starts, so it contains the log of
the current daemon instance only.
EXIT CODE
When starting, mgrg exits with 0 if successful and 1 if it is
already running. If service executable cannot run, the exit code is -1. When
creating application, mgrg exits with 0 if successful, and -1 if not.
PROCESS CONTROL
When mgrg is told to stop the application (with "-m
stop" arguments), it will send SIGTERM signal to all its children. All
Golf processes will complete the current request before exiting, assuming
they are currently processing a request; otherwise they will exit
immediately.
If mgrg is terminated without "-m stop", (for example
with SIGKILL signal), then all its chidlren will immediately terminate with
SIGKILL as well, regardless of whether they are currently processing any
requests or not.
EXAMPLES
• To begin using mgrg for a specific application,
you must initialize it first. For example, if your application name is
"myapp" and the user who will run application is the currently
logged-on user:
sudo mgrg -i -u $(whoami) myapp
• The initialization needs to be done only once.
Following the above, you can start your service application with 3 server
processes:
• To stop your service processes:
• To stop the server entirely (meaning to stop the
resident mgrg daemon serving your particular application):
• To view status of mgrg daemon for your
application:
RUNNING YOUR APPLICATION SERVER ON SYSTEM STARTUP
If you want your application to run on system startup (so you
don't have to run it manually), you can add it to systemd configuration.
Here is an example (replace <app name> with your application name and
<app owner> with the name of the Operating System user under which
your application is installed):
[Unit]
Description=Golf Service Program Manager for [<app name>] application.
After=network.target
[Service]
Type=forking
ExecStart=/usr/bin/mgrg <app name>
ExecStop=/usr/bin/mgrg -m quit <app name>
KillMode=process
Restart=on-failure
User=<app owner>
[Install]
WantedBy=multi-user.target
The above should be saved in the directory given by the output of
the following system command:
pkg-config systemd --variable=systemdsystemunitdir
The file should be saved as <app name>.service (or similar).
Once saved, you can use standard systemctl commands to start, stop and
restart your service.
