DOCSEARCHbyAlgolia
Submit Docs

fcgi2 FastCGI Developer's Kit

repository·master·Indexed 42 days ago

https://github.com/fastcgi-archives/fcgi2

A FastCGI Developer's Kit providing tools and libraries for implementing the FastCGI protocol. It includes the cgi-fcgi utility for bridging CGI to FastCGI, a compatibility library with functions like FCGI_Accept and FCGI_Finish, and a FastCGI module for Perl.

Tokens
4K
Snippets
20
Records
24
Agent score
54%

What's inside fcgi2

  4. Build and install fcgi2 on Unix

    master

    To build fcgi2 from source on a Unix-like system, use the standard autotools workflow: generate the configuration files, run the configure script, compile the project with make, and install the binaries.

    ./autogen.sh
./configure
make
make install

  5. Use cgi-fcgi to bridge CGI to FastCGI

    master

    The cgi-fcgi utility acts as a bridge between a CGI/1.1 environment (like a Web server) and an existing FastCGI application. It forwards CGI environment variables and stdin to the FastCGI application, and forwards the application's stdout and stderr back to the CGI caller.

    When the FastCGI application signals the end of its response, cgi-fcgi flushes its buffers and exits, allowing the Web server to complete the HTTP response.

  6. Install the Perl FastCGI module

    master

    To install the FastCGI module for Perl, you must first ensure your system has the necessary build tools installed.

    Prerequisites

    You need the following packages installed on your system:

    • gcc
    • gnu make
    • m4
    • aclocal
    • autoconf
    • automake
    • libtool

    Standard Installation

    Run the following commands from the module root:

    ./distrib
perl Makefile.PL
make
make install

  7. Configure environment variables using envdir for Rails applications

    master

    You can inject environment variables into your FastCGI process by using envdir pointing to a local directory (e.g., ./env). Each file within that directory acts as an environment variable where the filename is the variable name and the file content is the value.

    For a standard Rails deployment, your ./env directory should contain:

    • RAILS_ROOT: The full path to your Rails root directory.
    • RAILS_ENV: The environment name (e.g., production or development).
    • RAILS_HOST: The IP address or FQDN of the host.

    Any additional files added to this directory will also be exported as environment variables to the application.

    # Example of running the process with envdir
exec envdir ./env \
  cgi-fcgi -supervise -start -connect $RAILS_HOST:$RAILS_PORT $RAILS_ROOT/public/dispatch.fcgi

  8. Run cgi-fcgi using a command file with -f

    master

    The -f flag allows you to pass arguments via a file. This is useful for Unix systems where you want to use a command interpreter file (like a shebang line).

    cgi-fcgi opens the file at cmdPath and reads arguments. It skips lines starting with #. The first non-comment line must contain valid arguments in one of the supported forms (-bind, -start, or -connect).

    Example file content (/path/to/cmdfile):

    # This is a comment
-connect /httpd/root/sock/app /httpd/root/bin/app

    Example execution:

    cgi-fcgi -f /path/to/cmdfile
    cgi-fcgi -f cmdPath

  9. Start FastCGI application processes using -start

    master

    The -start flag allows cgi-fcgi to spawn one or more FastCGI application processes.

    1. Socket Creation: cgi-fcgi creates the listening socket specified by connName.
      • If connName is a path, it creates a Unix domain socket.
      • If connName is localhost:NNN, it creates a TCP/IP listening socket on port NNN.
    2. Process Spawning: It forks nServers copies of the executable file at appPath.
    3. Concurrency: If nServers is omitted, it defaults to 1. All spawned processes share the single listening socket.

    Note: cgi-fcgi only creates processes on the local machine; it cannot start processes on remote machines.

    Example:

    # Start 4 server processes using a Unix socket
cgi-fcgi -start -connect /tmp/app.sock /usr/bin/app 4
    cgi-fcgi -start -connect connName appPath [nServers]

  10. Install the pure Perl version of the module

    master

    If you want to use the experimental pure Perl version, which does not require a C compiler, you can do so by passing the --pure-perl flag during the Makefile.PL execution.

    Note: This version currently only works on Unix and does not support Windows Named Pipes.

    perl Makefile.PL --pure-perl

  11. Handle environment variables safely with FCGI_Accept

    master

    When using FCGI_Accept, the library manages the memory for the environ array. To avoid memory leaks or crashes, follow these rules:

    1. Do not retain pointers: Never keep pointers to the environ array or any strings within it (e.g., results from getenv()), as they will be freed by the next call to FCGI_Finish or FCGI_Accept.
    2. Do not use setenv or putenv directly on the environ array: Modifying the array created by FCGI_Accept can cause storage leaks or lead to the library attempting to free memory it doesn't own.

    If you must use setenv or putenv, use the following pattern to preserve the original environment and safely manage the request-specific environment:

    char **savedEnviron, **requestEnviron;
int acceptStatus;

savedEnviron = environ;
acceptStatus = FCGI_Accept();
requestEnviron = environ;

/* Restore the original environment pointer */
environ = savedEnviron;

if(acceptStatus >= 0 && !FCGX_IsCGI()) {
    /* 
     * requestEnviron points to name-value pairs in storage 
     * allocated by FCGI_Accept. OK to read, but make copies 
     * instead of retaining pointers.
     */
}

/* Now it is safe to use setenv or putenv, but watch for leaks */

  12. Run cgi-fcgi in supervise mode

    master

    To enable supervision for a FastCGI process, use the -supervise option when calling the cgi-fcgi script. This is typically used in conjunction with -start and -connect to manage the lifecycle of a dispatch file.

    Example command structure: cgi-fcgi -start -supervise -connect $host:$port /path/to/dispatch.fcgi

    cgi-fcgi -start -supervise -connect 127.0.0.1:1791 /path/to/dispatch.fcgi