Ubuntu Manpage: mgrg - (service-manager)

NAME

       mgrg -  (service-manager)

PURPOSE

       Run and manage services.

SYNTAX

           mgrg <options> <app name>

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:

mgrg -w 3 myapp

• To stop your service processes:

mgrg -m stop -- myapp

• To restart them:

mgrg -m restart -- myapp

• To stop the server entirely (meaning to stop the resident mgrg daemon serving your particular
application):

mgrg -m quit -- myapp

• To view status of mgrg daemon for your application:

mgrg -m status -- myapp

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.

NAME

PURPOSE

SYNTAX

DESCRIPTION

SEE ALSO