Mgrg

Purpose: Run and manage services.

mgrg <options> <app name>

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 Gliimly applications, including both service and command-line.

A number of options are available to setup and manage the execution of a Gliimly 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 ".gliimapp" 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), 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. See SELinux if you are using it, as additional steps may be required.
-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.
-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 Gliimly 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 Gliimly 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 Gliimly 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=Gliimly 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.