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:
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.
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):
Description=Vely FastCGI Program Manager for [<app name>] application.

ExecStart=/usr/bin/vf <app name>
ExecStop=/usr/bin/vf -m quit <app name>
User=<app owner>


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.
See also
See all

You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a link back to this page (dofollow) - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind.