The FastCgiAccessChecker directive is used to define a FastCGI application as a per-directory access validator. The Apache Access phase precedes user authentication and thus the decision to (dis)allow access to the requested resource is based on the HTTP headers submitted with the request. FastCGI based authorizers are useful primarily when there is a dynamic component to the access validation decision such as a time of day or whether or not a domain's account is up to date.
If the FastCGI application filename does not have a corresponding static or external server definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot.
FastCgiAccessChecker is used within Directory
or Location
containers.
<Directory htdocs/protected>
FastCgiAccessChecker fcgi-bin/access-checker
</Directory>
mod_fastcgi sends nearly all of the standard environment variables typically available to CGI/FastCGI request handlers. All headers returned by a FastCGI access-checker application in a successful response (Status: 200) are passed to subprocesses (CGI/FastCGI invocations) as environment variables. All headers returned in an unsuccessful response are passed on to the client. FastCGI specification compliant behavior can be obtained by using the "-compat" option.
mod_fastcgi sets the environment variable "FCGI_APACHE_ROLE" to "ACCESS_CHECKER" to indicate which (Apache specific) authorizer phase is being performed.
Custom failure responses from FastCGI authorizer applications are not supported. See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).
Setting the FastCgiAccessCheckerAuthoritative directive explicitly to Off allows access checking to be passed on to lower level modules (as defined in the Configuration and modules.c files) if the FastCGI application fails to allow access.
By default, control is not passed on and a failed access check will result
in a Forbidden reply. Disabling the default should be carefully considered.
The FastCgiAuthenticator directive is used to define a FastCGI application as a per-directory authenticator. Authenticators verify the requester is who he says he is by matching the provided username and password against a list or database of known users and passwords. FastCGI based authenticators are useful primarily when the user database is maintained within an existing independent program or resides on a machine other than the web server.
If the FastCGI application filename does not have a corresponding static or external server definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot.
FastCgiAuthenticator is used within Directory or Location containers and must include an AuthType and AuthName directive. Only the Basic user authentication type is supported. It must be accompanied by a require or FastCgiAuthorizer directive in order to work correctly.
<Directory htdocs/protected>
AuthType Basic
AuthName ProtectedRealm
FastCgiAuthenticator fcgi-bin/authenticator
require valid-user
</Directory>
mod_fastcgi
sends nearly all of the standard environment variables
typically available to CGI/FastCGI request handlers. All headers returned by
a FastCGI authentication application in a successful response (Status: 200)
are passed to subprocesses (CGI/FastCGI invocations) as environment variables.
All headers returned in an unsuccessful response are passed on to the client.
FastCGI specification compliant behavior can be obtained by using the "-compat
"
option.
Mod_fastcgi
sets the environment variable "FCGI_APACHE_ROLE"
to "AUTHENTICATOR" to indicate which (Apache specific) authorizer
phase is being performed.
Custom failure responses from FastCGI authorizer applications are not supported. See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).
Setting the FastCgiAuthenticatorAuthoritative
directive explicitly to Off
allows authentication to be passed on to lower level modules (as defined in the Configuration
and modules.c
files) if the FastCGI application fails to authenticate the
user.
A common use for this is in conjunction with a well protected AuthUserFile
containing a few (administration related) users.
By default, control is not passed on and an unknown user will result in an Authorization Required reply. Disabling the default should be carefully considered.
The FastCgiAuthorizer
directive is used to define a FastCGI
application as a per-directory authorizer. Authorizers validate whether an
authenticated user is allowed access to a requested resource. FastCGI based
authorizers are useful primarily when there is a dynamic component to the authorization
decision such as a time of day or whether or not the user has paid his bills.
If the FastCGI application filename does not have a corresponding static or external server definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot.
FastCgiAuthorizer
is used within Directory
or Location
containers and must include an AuthType and AuthName directive. It must be accompanied by
an authentication directive such as FastCgiAuthenticator, AuthUserFile, AuthDBUserFile or
AuthDBMUserFile in order to work correctly.
<Directory htdocs/protected>
AuthType Basic
AuthName ProtectedRealm
AuthDBMUserFile conf/authentication-database
FastCgiAuthorizer fcgi-bin/authorizer
</Directory>
mod_fastcgi
sends nearly all of the standard environment variables
typically available to CGI/FastCGI request handlers. All headers returned by a
FastCGI authentication application in a successful response (Status: 200) are passed to
subprocesses (CGI/FastCGI invocations) as environment variables. All headers
returned in an unsuccessful response are passed on to the client. FastCGI
specification compliant behavior can be obtained by using the "-compat
"
option.
Mod_fastcgi
sets the environment variable "FCGI_APACHE_ROLE"
to "AUTHORIZER" to indicate which (Apache specific) authorizer
phase is being performed.
Custom failure responses from FastCGI authorizer applications are not supported. See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).
Setting the FastCgiAuthenticatorAuthoritative
directive explicitly to Off
allows authentication to be passed on to lower level modules (as defined in the Configuration
and modules.c
files) if the FastCGI application fails to authenticate the
user.
A common use for this is in conjunction with a well protected AuthUserFile
containing a few (administration related) users.
By default, control is not passed on and an unknown user will result in an Authorization Required reply. Disabling the default should be carefully considered.
The FastCgiConfig
directive defines the default parameters for
all dynamic FastCGI applications. This directive does not affect static
or external applications in any way.
Dynamic applications are not started at server initialization, but upon demand. If the demand is heavy, additional application instances are started. As the demand fades, application instances are killed off. Many of the options govern this process.
Option can be one of (case insensitive):
appConnTimeout n (0 seconds)
connect()
should be
used.
If the timeout expires, a SERVER_ERROR results. For non-zero
values, this is the amount of time used in a select()
to write
to the file descriptor returned by a non-blocking
connect().
Non-blocking connect()
s are troublesome on many
platforms. See also -idle-timeout, it produces similar results but in
a more portable manner.idle-timeout n (30 seconds)
error
LogLevel
).
The inactivity timer applies only as long as a connection is pending with
the FastCGI application. If a request is queued to an application, but
the application doesn't respond (by writing and flushing) within this
period, the request will be aborted. If communication is complete with
the application but incomplete with the client (the response is buffered),
the timeout does not apply.autoUpdate none
-restart
.gainValue n (0.5)
gainValue
), so
making it smaller weights them more heavily compared to the current value, which is scaled
by gainValue
.initial-env name[=value]
none
init-start-delay n (1
second)
killInterval n (300 seconds)
listen-queue-depth n (100)
maxClassProcesses n (10)
maxProcesses n (50)
minProcesses n (5)
multiThreshhold n (50)
singleThreshhold
is used instead.pass-header header none
priority n (0)
setpriority()
).processSlack n (5 seconds)
maxProcesses
- processSlack
, the process manager invokes the killing policy.
This is to improve performance at higher loads by killing some of
the most inactive application instances before reaching maxProcesses
.restart none
restart-delay n (5 seconds)
singleThreshhold n (0)
startDelay n (3 seconds)
startDelay
must be smaller than appConnTimeout
to be effective.updateInterval n (300 seconds)
appConnTimeout n (0 seconds)
connect()
should be
used.
If the timeout expires, a SERVER_ERROR results. For non-zero
values, this is the amount of time used in a select()
to write
to the file descriptor returned by a non-blocking
connect().
Non-blocking connect()
s are troublesome on many
platforms. See also -idle-timeout, it produces similar results but in
a more portable manner.idle-timeout n (30 seconds)
error
LogLevel
).
The inactivity timer applies only as long as a connection is pending with
the FastCGI application. If a request is queued to an application, but
the application doesn't respond (by writing and flushing) within this
period, the request will be aborted. If communication is complete with
the application but incomplete with the client (the response is buffered),
the timeout does not apply.flush none
mod_fastcgi
buffers data in order to free the application as quickly as possible.host hostname:port none
-socket
and -host
options
are mutually exclusive.Pass-header header none
socket filename none
FastCgiIpcDir
.
The -socket
and -port
options are mutually exclusive.
UNIX: The FastCgiIpcDir
directive specifies directory
as the place to store (and find, in the case of external FastCGI applications)
the UNIX socket files used for communication between the applications and the
web server. If the directory does not begin with a slash (/) then it is assumed
to be relative to the ServerRoot.
If the directory doesn't exist, an attempt is made to create it with appropriate
permissions. Do not specify a directory that is not on a local file system. If
you use the default directory (or another directory within /tmp
),
mod_fastcgi
will break if your system periodically deletes files
from /tmp
.
Windows NT: The FastCgiIpcDir directive specifies name as the root for the named pipes used for communication between the application and the Web server. The name must be in the form of \\.\pipe\pipename The pipename part can contain any character other than a backslash.
The FastCgiIpcDir
directive must precede any FastCgiServer
or FastCgiExternalServer
directives
(which make use of UNIX sockets). The directory must be readable, writeable,
and executable (searchable) by the web server, but otherwise should not be accessible
to anyone.
The FastCgiServer
directive defines filename as a static
FastCGI application. If the filename does not begin with a slash (/) then it
is assumed to be relative to the ServerRoot.
By default, the Process Manager will start one instance of the application
with the default configuration specified (in parenthesis) below. Should a static
application instance die for any reason mod_fastcgi
will spawn
another to replace it and log the event (at the warn LogLevel
).
Option can be one of (case insensitive):
appConnTimeout n (0 seconds)
connect()
should be
used. If the timeout expires, a SERVER_ERROR results. For
non-zero values, this is the amount of time used in a select()
to write to the file descriptor returned by a non-blocking
connect().
Non-blocking connect()
s are troublesome
on many platforms. See also -idle-timeout, it produces similar results
but in a more portable manner.idle-timeout n (30 seconds)
error
LogLevel
).
The inactivity timer applies only as long as a connection is pending with
the FastCGI application. If a request is queued to an application, but
the application doesn't respond (by writing and flushing) within this
period, the request will be aborted. If communication is complete with
the application but incomplete with the client (the response is buffered),
the timeout does not apply.initial-env name[=value] none]
none
init-start-delay n(1 second)
Flush none
mod_fastcgi
buffers data in order to free the application as quickly as possible.Listen-queue-depth n (100)
Pass-header header none
processes n (1)
Priority n (0)
setpriority()
).port n none
-socket
and -port
options are mutually exclusive.Restart-delay n (5 seconds)
Socket filename (gen'd)
FastCgiIpcDir
. This option
makes the application accessible to other applications (e.g. cgi-fcgi
)
on the same machine or via an external FastCGI application definition (FastCgiExternalServer
).
If neither the -socket
nor the -port
options are given,
the module generates a UNIX domain socket filename. The -socket
and -port
options are mutually exclusive.
The FastCgiSuexec
directive is used to enable support for a suexec-wrapper.
FastCgiSuexec
requires suexec be enabled in Apache (for CGI).
To use the same suexec-wrapper in use by Apache, set FastCgiSuexec
to On. To use a different suexec-wrapper, specify the filename
of the suexec-wrapper. If the filename does not begin with a slash (/)
then it is assumed to be relative to the ServerRoot.
When FastCgiSuexec
is enabled, the location of static or external
FastCGI application definitions is important. They inherit their user
and group from the User
and Group
directives in the
virtual server in which they were defined. User
and Group
directives should precede FastCGI application definitions. Note that
this does not limit the FastCGI application to the virtual server in
which they were defined, the application is allowed to service requests from
any virtual server with the same user and group. If a request is received
for a FastCGI application without an existing matching definition running with
the correct user and group, a dynamic instance of the application is started
with the correct user and group. This can lead to multiple copies of
the same application running with different user/group. If this is a problem,
preclude navigation to the application from other virtual servers or configure
the virtual servers with the same User and Group.
See the Apache documentation for more information about suexec (make sure you fully understand the security implications).