--- name: "Plack::Handler::FCGI" section: "3pm" platform: "linux" package: "libplack-perl" version: "1.0051-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Plack::Handler::FCGI" --- # Plack::Handler::FCGI(3pm) FastCGI handler for Plack ## NAME Plack::Handler::FCGI - FastCGI handler for Plack ## SYNOPSIS ``` # Run as a standalone daemon plackup -s FCGI --listen /tmp/fcgi.sock --daemonize --nproc 10 # Run from your web server like mod_fastcgi #!/usr/bin/env plackup -s FCGI my $app = sub { ... }; # Roll your own my $server = Plack::Handler::FCGI->new( nproc => $num_proc, listen => [ $port_or_socket ], detach => 1, ); $server->run($app); ``` ## DESCRIPTION This is a handler module to run any PSGI application as a standalone FastCGI daemon or a .fcgi script. ### OPTIONS - listen ``` listen => [ '/path/to/socket' ] listen => [ ':8080' ] ``` Listen on a socket path, hostname:port, or :port. - port listen via TCP on port on all interfaces (Same as `"listen => ":$port""`) - leave-umask Set to 1 to disable setting umask to 0 for socket open - nointr Do not allow the listener to be interrupted by Ctrl+C - nproc Specify a number of processes for FCGI::ProcManager - pid Specify a filename for the pid file - manager Specify either a FCGI::ProcManager subclass, or an actual FCGI::ProcManager-compatible object. If you do not want a FCGI::ProcManager but instead run in a single process, set this to undef. ``` use FCGI::ProcManager::Dynamic; Plack::Handler::FCGI->new( manager => FCGI::ProcManager::Dynamic->new(...), ); ``` - daemonize Daemonize the process. - proc-title Specify process title - keep-stderr Send psgi.errors to STDERR instead of to the FCGI error stream. - backlog Maximum length of the queue of pending connections, defaults to 100. ### EXTENSIONS Supported PSGI::Extensions. - psgix.cleanup ``` push @{ $env->{'psgix.cleanup.handlers'} }, sub { warn "Did this later" } if $env->{'psgix.cleanup'}; ``` Supports the `"psgix.cleanup"` extension, in order to use it, just push a callback onto `"$env->{'psgix.cleanup.handlers'"`. These callbacks are run after the `"pm_post_dispatch"` hook. - psgix.harakiri ``` $env->{'psgix.harakiri.commit'} = 1 if $env->{'psgix.harakiri'}; ``` If there is a "manager", then `"psgix.harakiri"` will be enabled and setting `"$env->{'psgix.harakiri.commit'}"` to a true value will cause `"$manager->pm_exit"` to be called after the request is finished. ### WEB SERVER CONFIGURATIONS In all cases, you will want to install FCGI and FCGI::ProcManager. You may find it most convenient to simply install Task::Plack which includes both of these. *nginx* This is an example nginx configuration to run your FCGI daemon on a Unix domain socket and run it at the server's root URL (/). ``` http { server { listen 3001; location / { set $script ""; set $path_info $uri; fastcgi_pass unix:/tmp/fastcgi.sock; fastcgi_param SCRIPT_NAME $script; fastcgi_param PATH_INFO $path_info; fastcgi_param QUERY_STRING $query_string; fastcgi_param REQUEST_METHOD $request_method; fastcgi_param CONTENT_TYPE $content_type; fastcgi_param CONTENT_LENGTH $content_length; fastcgi_param REQUEST_URI $request_uri; fastcgi_param SERVER_PROTOCOL $server_protocol; fastcgi_param REMOTE_ADDR $remote_addr; fastcgi_param REMOTE_PORT $remote_port; fastcgi_param SERVER_ADDR $server_addr; fastcgi_param SERVER_PORT $server_port; fastcgi_param SERVER_NAME $server_name; } } } ``` If you want to host your application in a non-root path, then you should mangle this configuration to set the path to `"SCRIPT_NAME"` and the rest of the path in `"PATH_INFO"`. See \ for more details. *Apache mod\_fastcgi* After installing `"mod_fastcgi"`, you should add the `"FastCgiExternalServer"` directive to your Apache config: ``` FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/fcgi.sock ## Then set up the location that you want to be handled by fastcgi: # EITHER from a given path Alias /myapp/ /tmp/myapp.fcgi/ # OR at the root Alias / /tmp/myapp.fcgi/ ``` Now you can use plackup to listen to the socket that you've just configured in Apache. ``` $ plackup -s FCGI --listen /tmp/myapp.sock psgi/myapp.psgi ``` The above describes the "standalone" method, which is usually appropriate. There are other methods, described in more detail at "Standalone\_server\_mode" in Catalyst::Engine::FastCGI (with regards to Catalyst, but which may be set up similarly for Plack). See also \ for more details. *lighttpd* To host the app in the root path, you're recommended to use lighttpd 1.4.23 or newer with `"fix-root-scriptname"` flag like below. ``` fastcgi.server = ( "/" => (( "socket" => "/tmp/fcgi.sock", "check-local" => "disable", "fix-root-scriptname" => "enable", )) ``` If you use lighttpd older than 1.4.22 where you don't have `"fix-root-scriptname"`, mounting apps under the root causes wrong `"SCRIPT_NAME"` and `"PATH_INFO"` set. Also, mounting under the empty root (`""`) or a path that has a trailing slash would still cause weird values set even with `"fix-root-scriptname"`. In such cases you can use Plack::Middleware::LighttpdScriptNameFix to fix it. To mount in the non-root path over TCP: ``` fastcgi.server = ( "/foo" => (( "host" = "127.0.0.1", "port" = "5000", "check-local" => "disable", )) ``` It's recommended that your mount path does **NOT** have the trailing slash. If you *really* need to have one, you should consider using Plack::Middleware::LighttpdScriptNameFix to fix the wrong **PATH\_INFO** values set by lighttpd. ### Authorization Most fastcgi configuration does not pass `"Authorization"` headers to `"HTTP_AUTHORIZATION"` environment variable by default for security reasons. Authentication middleware such as Plack::Middleware::Auth::Basic or Catalyst::Authentication::Credential::HTTP requires the variable to be set up. Plack::Handler::FCGI supports extracting the `"Authorization"` environment variable when it is configured that way. Apache2 with mod\_fastcgi: ``` --pass-header Authorization ``` mod\_fcgid: ``` FcgidPassHeader Authorization ``` ### Server::Starter This plack handler supports Server::Starter as a superdaemon. Simply launch plackup from start\_server with a path option. The listen option is ignored when launched from Server::Starter. ``` start_server --path=/tmp/socket -- plackup -s FCGI app.psgi ``` ## SEE ALSO Plack