Vf

18.4.0 released Sep 25, 2023

Purpose: Run and manage FastCGI programs.

vf <options> <app name>

vf is a FastCGI (FCGI) program manager. An FCGI program is started as a number of concurrent processes serving application requests, typically from reverse-proxy servers such as Apache or Nginx. Use vf to create Vely applications, including both FCGI and command-line.

A number of options are available to setup and manage the execution of a FCGI program as an application server, which can be accessed either via TCP/IP or a Unix domain socket.

vf is a part of Vely package. You can, however, use vf in any case, whether your FCGI programs are created by Vely or otherwise.

<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.

vf 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>. You must supply a valid FCGI program to run. When vf starts your FCGI program, its current directory is set to /var/lib/vv/<app name>. 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.

vf will re-start FCGI processes that exited or died, keeping the number of processes as specified, unless -n option is used. The number of worker FCGI 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.

Your FCGI program must handle SIGTERM signal and gracefully exit, meaning exit by completing the request that may be executing when SIGTERM was received. See plain-C-FCGI example.

<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; vf will create file ".velyapp" which identifies the application so vv can run in the directory. You must run as root when using this option (and must not run as root otherwise). The directory structure is setup in /var/lib/vv/<app name>, and is the same directory structure used by Vely.
-u <user>
The owner of your application. This is only used when initializing directory structure used by vf (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 vf (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 FCGI program will listen on (and accept connections), if you are using TCP/IP. You typically need to specify ProxyPass, "location" or similar FCGI directives in your proxy web server so it can connect to your application. If you are using FastCGI-API or call-server, 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 assumed to be used. 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 vf and its full path name is "/var/lib/vv/<app name>/sock/sock" (you can connect to it via FastCGI-API, call-server etc.). When using a proxy web server (like Apache or Nginx), you typically need to specify ProxyPass, "location" or similar FCGI directives so it can connect to your application. If you specify neither -x nor -p (TCP/IP socket), then -x (unix domain socket) is assumed to be used.
-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 number of FCGI processes ("worker" processes) to match the request load (adaptive mode). Used 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 FCGI processes. If no such connections are detected (i.e. existing FCGI 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 FCGI 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 FCGI processes that run in adaptive mode (-d option). The default is 0. This option can be used only with -d option.
--max-worker=<max workers>
Maximum number of FCGI 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 FCGI 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 FCGI 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 vf daemon serving an application. <command> can be "start" (to start FCGI processes), "stop" (to stop FCGI processes), "restart" (to restart FCGI processes), "quit" (to stop vf daemon altogether) or "status" (to display status of vf).
-n
Do not restart FCGI processes if they exit or die. However, in adaptive mode (-d option), this option has no effect.
-g
Do not restart FCGI 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 (typically retrieved by argc/argv arguments to main()). The <args> should be double-quoted as a whole, while use of single quotes to quote arguments that contain whitespaces is permitted.
-s <sleep millisecs>
The basis time period (in milliseconds) that vf will sleep before checking for commands (specified by -m option), or check for dead FCGI 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 nicely, and should not be changed without due consideration.
-e
Display verbose messages.
-c <program>
Full absolute path to your FCGI program. If omitted, the executable /var/lib/vv/bld/<app name>/<app name>.fcgi is assumed, which is the standard Vely FCGI 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/vv/bld/<app name>/<program>.
-v
Display vf version (which matches Vely version) as well as copyright and license.
-h,--help
Display help.

vf writes log file at /var/lib/vv/<app name>/vflog/log file. This file is overwritten when vf starts, so it contains the log of the current daemon instance only.

Exit code

When starting, vf exits with 0 if successful and 1 if it is already running. If FastCGI executable cannot run, the exit code is -1. When creating application, vf exits with 0 if successful, and -1 if not.

Process control

When vf is told to stop the application (with "-m stop" arguments), it will send SIGTERM signal to all its children. All children processes must complete the current request before exiting, assuming they are currently processing a request; otherwise they must exit immediately. Vely will always do so; if you are using non-Vely FastCGI application, you should make sure this requirement is met to avoid interrupted requests.

If vf 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.

Platforms and requirements

vf is a part of Vely package.

Examples

To begin using vf for a specific application, you must initialize it first. For example, if your application name is "myapp", the user who will run application is "myuser" and the primary group of your proxy server (Apache, Nginx, or some other) is "www-data" (optional):
```
sudo vf -i -u myuser -r www-data -- myapp
```
The initialization needs to be done only once. Following the above, you can start your FCGI application:
```
vf -c "/path/to/your/fcgi/program" -x -w 3 -a "--opt1 val1 --opt2 val2" -- myapp
```
In this example, you would use Unix domain sockets (-x option), start 3 process to server requests in parallel (-w option), and your program accepts input parameters (-a option). If you used -p option instead of -x, you could specify TCP/IP port (in which case proxy web server can be on a different host).
To stop your FCGI processes:
```
vf -m stop -- myapp
```
To restart them:
```
vf -m restart -- myapp
```
To stop the server entirely (meaning to stop the resident vf daemon serving your particular application):
```
vf -m quit -- myapp
```
To view status of vf daemon for your application:
```
vf -m status -- myapp
```

Running your application server on startup

If you want your application to run on 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=Vely FastCGI Program Manager for [<app name>] application.
After=network.target

[Service]
Type=forking
ExecStart=/usr/bin/vf <app name>
ExecStop=/usr/bin/vf -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.