Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FCGI_SPAWN(1)	      User Contributed Perl Documentation	 FCGI_SPAWN(1)

NAME
       fcgi_spawn - FastCGI server for CGI-like	Perl applications effective
       multiprocessing,	the executable daemon of FCGI::Spawn

DESCRIPTION
       Daemon enables you to launch Perl applications originally written for
       CGI environment.	To accomplish POST input you should need to patch your
       CGI.pm with the patch supplied in the FCGI::Spawn distribution, or the
       application, in some rare cases (like the Bugzilla), the	both.  Daemon
       is intended to be launched  as a	root ( "uid = 0" ) user, although you
       may run it as a target user itself.  You	need the FastCGI-capable web
       server capable to work with other ('external') daemons by a FastCGI
       protocol: the 'FastCGI requester'.  Many	features supported like	the
       fine-tune on the	number of processes, maximum number of requests	served
       by the each process in its lifetime, more on this on FCGI::Spawn, also
       tested environments and comparison to the well-known Perl runtime
       environments.  Main focus of the	daemon is the system administration
       convinience and adaptation to the OS distribution(s), as	it is seen
       from:

SYNOPSIS
       The necessary configuration for fcgi_spawn is to	be located in the
       dedicated directory, specified by -c command line parameter (by default
       the /usr/local/etc for FreeBSD/Slackware	packages; /etc for FHS-
       compatible Linux/Cygwin packages	( RedHat, Debian, etc. ) . This
       includes	the configuration file "fcgi_spawn.conf", and optional preload
       scripts aimed similarly as the "startup.pl" of the mod_perl: to preload
       the modules before the process to fork, and perform necessary
       initialization steps like environment variables setup.

   Command line	options
       Consider	all of them to be mandatory:

	 -c <config_path> Full path to the directory of	configuration file, the
       fcgi_spawn.conf ( See 'Configuration File' below	);
	 -p <pid_file>	  Full path and	name of	the process ID file name;
	 -l <log_file>	  Full path and	name  of the log file name;
	 -u <user>	  Name of the system user to run the FastCGI applications;
	 -g <group>	  Name of the system group to run the FastCGI applications;
	 -s <socket>	  Name of the local UNIX socket	to be created by the daemon to
       listen for incoming connections.	You should try :number or address:number or
       host:number as a	value of this option in	teh case the TCP connectivity is
       wanted;

       Those are optional:

	 -e		  Redefine the exit() Perl builtin function to prevent the
       spawned persistent processes from exiting and starting again when your
       application(s) exit;
	 -pl		  Evaluate the:

   Preload Scripts from	the configuration directory
       You can use preload scripts for modules preload and initialization,
       similarly to the	what is	the apache's "startup.pl" is attended for in
       the mod_perl's world , although "fcgi_spawn" doesn't execute them from
       the root	( "uid = 0" ) user. ( while apache does	).  Typically, good
       results are achieved when you try to execute the	dummy index page of
       the web aplication in them, because it loads the	most necessary modules
       of the application. If you have no errors when execute that perl	script
       ( obviously "index.pl" or "index.cgi" depending on your application )
       as a "fcgi_spawn"'s target user and group ( specified with "-u" and
       "-g" options ), you should give it a try. Thing to beware at this point
       is: environment variables cause "fcgi_spawn" clears the all of the
       environment for security	purposes.

       Preload scripts are to be located in the	configuraion directory with
       the names "preload_nonprepared_XX.pl" and "preload_prepared_XX.pl",
       respectively. The "XX" here means a number of the execution sequence,
       as you may wish to "use SomeModule" on the followed of scripts and have
       its functionality on the	scripts	following after	those. The difference
       between non- and	prepared scripts is: the multi-processing occurs to
       happen in between of them ( "prepare" in	FCGI::Spawn ). That means that
       the 'nonprepared' scripts are the best place to pre-load	your
       applications' modules, but the handles like the data files, sockets,
       database	handles, etc. can exist	only per single	process	and therefore
       should be established in	the 'prepared' scripts.

       Predefined symbols for preload scripts are:

       $spawn
	   the FCGI::Spawn object.

	   It is useful	to do the trick	like this for your CGI app:

		   $FCGI::Spawn::fcgi =	new CGI;
		   $spawn->callout( '/path/to/your/CGI/app.pl',	$FCGI::Spawn::fcgi );
		   undef $FCGI::Spawn::fcgi;

	   ( "CGI.pm.patch" supplied in	the source package is required for
	   this	to work	best. )	This loads the most of your application's code
	   into	memory in the 'nonprepared' script before the daemon to	fork()
	   which is the	main to	know about what	the FCGI::Spawn's prepare is.

       CALLED_OUT
	   the label to	go to with the exit() Perl builtin redefined ( '-e'
	   command line	parameter ).

	   Should be contained in the code reference supplied as a callout
	   property of the $spawn, the "FCGI::Spawn object". This is to	keep
	   the exit()'ed CGI application from exiting the FastCGI connection
	   "accept()" loop before "max_requests" processed. The	code use this
	   label like this:

		   $spawn->{ callout } =  sub{ do shift;
		   CALLED_OUT: eval ' $Bugzilla::_request_cache	= { }; '
		     if	defined( $Bugzilla::_request_cache ) and scalar	keys %{	$Bugzilla::_request_cache };
		   };

       $OURS
	   Hash	reference to keep scalar variables in between preload eval()s.
	   Those are to	be restored in preload scripts like this:

					   map{	${ $main::{ $_ } }
							   = $OURS->{  $_ } ;
					   } qw/webguiRoot bugzillaRoot	skybillRoot/;

       All of the preload scripts, if any exist, are eval()'ed after the
       $spawn is initialized with the values from:

   Configuration File
       "fcgi_spawn.conf", to be	read from the configuration directory
       specified with "-c" command line	parameter, should contain the values
       of the FCGI::Spawn object constructor, method "new", if those need to
       differ from the defaults. The exception is the "callout"	parameter
       which is	not a constant but the CODE reference and should be set	up in
       the "preload_noprepared"	scripts.

       Syntax is: spaces and tabs at the begin of the line are ignored,	the
       "#" symbol before the rest means	this line is ignored as	a comment too,
       key and value are separated with	the space(s) or	tab(s) all on the same
       line, and if the	value is multiple ( same way separated ) values, it is
       treated as an array reference ( wanted for "sock_chown" parameter ).

       Sample configuration file, "fcgi_spawn.conf.sample", is provided	in the
       source distribution.

Typical	CGI Applications with "fcgi_spawn"
       "FCGI::Spawn", and therefore "fcgi_spawn", are able to work in Unix and
       Cygwin environments, with 'properly' written CGI	applications, which
       the most	of the well-known CGI applications are.	This means: no much
       assign of the global variables, incapsulation of	the code in the
       "Namespace::sub()"s at least, and so on.

       Care should be taken about file and database handles closing and
       networking sockets disconnection	because	the "END{}" block of your Perl
       application is unlikely to be executed automatically, like it does in
       true CGI	application. You should	refer to Mod_Perl code guides in
       Chapter 6 of Practical mod_perl book:
       <http://modperlbook.org/pdf/ch06.pdf> Commonly, if your CGI application
       runs well with the typical "PerlRun" and	"Registry" environments	of the
       Mod_Perl, it should with	the "fcgi_spawn" ( and "CGI.pm.patch" supplied
       ), too. At least	as the examples	below do:

   WebGUI.org
       Till version 6.9	supported CGI mode, requires the 'date'	system command
       to be present in	the PATH. Fix this in preload script. You should
       "preload_nonprepared" your "index.pl" with the $spawn's ->callout, too.
       Demo is:	<http://alpha.vereshagin.org>.

   Skybill
       Traffic accounting system was rewritten a bit, as you can see from
       <http://skybill.sf.net>.	It was ( and in	many aspects is	) my old dummy
       code but	it's to	show that even that is able to be
       "fcgi_spawn"-friendly. You may want to use the "FCGI::Spawn/xinc"
       feature not only	to cache the XSLT object between request but to	share
       it among	fork()ed processes, it is accomplished with callout of the
       index.pl	on your	"preload_nonprepared" script automatically. Demo is:
       <http://skybill.vereshagin.org>.

   Bugzilla
       Got to know satisfaction: this was probably a worst evil	code ever
       seen. Despite it	has no problems	with mod_perl, that required many
       tricks to perform and here is the scoop:

       Many exit()s on the blocks
	   Requires the	exit() to be redefined with "-e" command line switch
	   for "fcgi_spawn", and the "CALLED_OUT" label	to be crafted like it
	   is already described	here.

       CGI.pm ancesting
	   Requires the	both patches to	be applied, on "CGI.pm"	amd
	   "Bugzilla/CGI.pm" .

       Request caching
	   Bugzilla's own request cache	cleans only if the mod_perl is used
	   specifically. Same about the	"CALLED_OUT" here.

       Environment cleaning
	   As an evil of Date::Manip ( I myself	hate it	too, since the
	   "DateTime.pm" infrastructure	is much	better ), and thus the
	   WebGUI.org too, the Bugzilla	can make your system commands
	   unavailable from your applications on your PATH environment
	   variable. This is why you should also enable	the "save_env" feature
	   on "fcgi_spawn.conf", if it is not enabled in FCGI::Spawn by
	   default.

	   Also, in some cases the Bugzilla's CGI programs use to take $0
	   instead of $ENV{ SCRIPT_NAME	} which	makes the URLs generated
	   pointless.

       Demo is located at:

BUGS And TODOs
       <http://bugs.vereshagin.org/product/FCGI%3A%3ASpawn>

       Adequate	reports	are accepted.

Runtime	Control
       Daemon is supplied with POSIX signal handling: "USR1" makes it to
       reopen the log file, and	every other signal is passed as	is to the
       actual FCGI::ProcManager	process.

LICENSE
       LGPL, as	of the MANIFEST	file in	FCGI::Spawn's CPAN distribution. More
       info on fcgi_spawn at: <http://fcgi-spawn.sf.net>.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 92:
	   '=item' outside of any '=over'

perl v5.24.1			  2012-12-07			 FCGI_SPAWN(1)

NAME | DESCRIPTION | SYNOPSIS | Typical CGI Applications with "fcgi_spawn" | BUGS And TODOs | Runtime Control | LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fcgi_spawn&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help