NAME¶
mod_gridsite - Grid extensions to Apache httpd
SYNOPSIS¶
LoadModule gridsite_module mod_gridsite.so
DESCRIPTION¶
mod_gridsite is an Apache 2.0 module which enforces access control via
Grid Access Control Lists, and X.509, GSI or VOMS credentials. mod_gridsite
also gives Apache built-in support for the HTTP PUT and DELETE methods, and
formatting of HTML pages with standard headers and footers.
Since mod_gridsite access control within Apache itself, Grid authorization and
the associated verified credentials are available to all technologies
supported by Apache, including static file serving, SSI, CGI, PHP, mod_perl
and Java servlets via a connector to Tomcat.
Operation of mod_gridsite can be configured using runtime directives in Apache's
standard httpd.conf configuration file. The module must first be loaded with a
LoadModule directive:
LoadModule gridsite_module /PATH/TO/MODULES/mod_gridsite.so
The module's behaviour is then controlled by GridSite... directives within
Apache <Directory ...> sections, allowing different directories to use
GridSite features in different ways.
DIRECTIVES¶
- GridSiteIndexes on|off
- Determines whether GridSite generates HTML directory
listings. These have some advantages over standard Apache directory
listings (eg the displayed filenames are never truncated) and will include
standard headers and footers if GridSiteHtmlFormat is on. (Default:
GridSiteIndexes off)
- GridSiteIndexHeader file
- If the named file is found in the directory being listed,
the file is included verbatim at the top of the listing and excluded from
the file-by-file listing. The file can either be HTML or plain text (in
which case browsers will be treat it as one HTML paragraph.) (Default:
none)
- GridSiteHtmlFormat on|off
- Determines where HTML pages receive additional formatting
before being sent to the client. This includes the "Last
modified", "View page history", "Switch to
HTTP(S)", "Print View" and "Built with GridSite"
footer elements. If header and footer files are found, they will be used
too. (Default: GridSiteHtmlFormat off)
- GridSiteHeadFile file
- GridSiteFootFile file
- Set the filenames to be used for as standard headers and
footers for HTML pages. If the file name begins with "/" then
this is used as the absolute path to that file to be used. Otherwise, for
each HTML page, the directory of that page is tried first, and then parent
directories in ascending order until a header / footer file is found.
Header files are inserted in place of HTML <body[ ...]> tags; footer
files in place of </body>. (These standard files should each include
the appropriate body tag as a replacement.) (Defaults: GridSiteHeadFile
gridsitehead.txt, GridSiteFootFile gridsitefoot.txt)
- GridSiteAuth on|off
- Enables GridSite access control features, using GACL files.
The files are named .gacl and are per-directory. The current directory is
tried and then parent directories in ascending order until a .gacl file is
found. (Default: GridSiteAuth off)
- GridSiteAutoPasscode on|off
- Whether to automatically issue passcodes in response to
HTTPS requests made using a full X.509 certificate (not a GSI proxy.)
(Default: GridSiteAutoPasscode on)
- GridSiteRequirePasscode on|off
- Whether to require passcode cookies when processing HTTPS
requests made using a full X.509 certificate (not a GSI proxy.) (Default:
GridSiteRequirePasscode off)
- GridSiteZoneSlashes number
- How many slashes to include in passcode paths. The path is
the prefix of REQUEST_URI that includes that number of slashes. Path
matching is checked by mod_gridsite in addition to any selection of
cookies by path made by the browser. (Default: GridSiteZoneSlashes 1)
- GridSiteAdminList uri
- All members of the DN List with name "uri"
receive the full set of permissions, irrespective of per-directory .gacl
files. People in this group have full control over the whole site.
(Default: none)
- GridSiteGSIProxyLimit limit
- When using GSI Proxy credentials, proxies with delegation
depth greater than "limit" will be ignored by mod_gridsite
authorization decisions. A limit of zero implies only full X.509
certificates (and no proxies) will be accepted. A limit of 1 implies that
only the initial proxy, usually created on the user's own machine, is
acceptable. Higher levels lead to proxies on remote machines, eg used by
running jobs, being accepted. (Default: GridSiteGSIProxyLimit 1)
- GridSiteMethods [GET] [PUT] [DELETE] [MOVE]
- Specifies which HTTP methods are supported by GridSite. GET
(and HEAD) are always supported. PUT and DELETE support is turned on by
this directive, subject to a positive statement that write permission is
allowed for the directory in question, by a GACL file. (Default: GridSite
GET)
- GridSiteDNlists
directory1[:directory2[:directory3]...]
- Sets up the DN List path used by GACL for evaluating
<dn-list> credentials. If this directive is not used, then GACL will
use the GRST_DN_LISTS variable from Apache's own environment. If that is
not set either, then /etc/grid-security/dn-lists is searched. (Default:
none)
- GridSiteDNlistsURI uri
- If GridSiteDNlistsURI is used, then the URI given appears
to be populated with all the DN lists on the current DN lists path which
match the current server. That is, for server https://example.org/ with DN
lists URI /dn-lists/, all DN lists with URLs starting
https://example.org/dn-lists/ will appear to be present in /dn-lists/,
irrespective of where in the path they are stored. (Default: none)
<p>
- GridSiteAdminURI uri
- GridSiteAdminURI gives the absolute URI on the server of
the GridSite Admin CGI program, which is used for file management, HTML
and GACL editing. This should be used in conjunction with the standard
Apache directive ScriptAlias to map that URI to the
real-gridsite-admin.cgi executable. For example:
ScriptAlias /real-gridsite-admin.cgi /PATH/TO/real-gridsite-admin.cgi
This URI is always reached by an internal redirection from the value set by
GridSiteAdminFile, and is never visible to users. (Default: none)
- GridSiteAdminFile cgifilename
- If GridSiteAdminURI is set, then the cgifilename of
GridSiteAdminFile appears to be present in all directories when explicitly
requested (it does not appear in directory listings.) Requests for these
ghost CGI URIs are internally redirected to the value set by
GridSiteAdminURI. (Default: GridSiteAdminFile gridsite-admin.cgi)
- GridSiteEnvs on|off
- This makes mod_gridsite export several variables into the
environment of CGI programs and other dynamic content systems. The
variable names are listed below. For gridsite-admin.cgi mechanism to work,
this switch must be left in its default state of on. (Default:
GridSiteEnvs on)
- GridSiteEditable [ext1 [ext2 [ext3] ...]]]
- A space-separated list of file extensions which can safely
be edited by the GridSite Text/HTML editor. The extensions are given
without the initial dot. This directive must apply to the
gridsite-admin.cgi executable, rather than just to the files it manages.
This is most easily achieved by placing GridSiteEditable in the main
section of the virtual host, outside any Directory or Location containers.
(Default: GridSiteEditable txt shtml html htm css js php jsp)
- GridSiteHelpURI uri
- If set, gives the URI to use for "Website Help"
links in HTML page footers. (Default: none)
- GridSiteLoginURI uri
- If set, gives the URI prefix to use for login/logout links
in page footers. The text "Login/Logout" will be a link to the
prefix followed by the value of REQUEST_URI for the page in question.
(Default: none)
- GridSiteLink on|off
- Turns off the link in the HTML page footers which gives
credit to GridSite. (Default: GridSiteLink on)
- GridSiteUnzip path
- If "path" is set by this directive, then
real-gridsite-admin.cgi will offer to list the contents of .zip archives
on the server. Users with write access are able to unpack the contents
into the same directory as the .zip file. The value of
"path" must point to the location of the unzip binary.
(Default: none)
- GridSiteGridHTTP on|off
- Enable GridHTTP for this server, virtual server or
directory: HTTPS requests made with the header Upgrade:
GridHTTP/1.0 will be redirected to an HTTP version of the file.
(Default: off)
- GridSiteGridHTTPport port
- Sets the port to use for the unencrypted HTTP component of
GridHTTP HTTPS->HTTP transfers. The same setting will be used for all
virtual hosts which support GridHTTP. (Default: 777)
- GridSiteSessionsDir path
- Location of authentication cookies and SSL session
credentials directory, relative to ServerRoot. Used by GridHTTP to record
the credentials obtained via HTTPS, and available to the corresponding
HTTP request or subsequent HTTPS requests following a session restart.
(Default: /var/www/sessions)
- GridSiteACLFormat GACL|XACML
- Format to use when writing .gacl files. (Both formats are
automatically recognised when reading.) (Default: GACL)
- GridSiteACLPath path
- Specify the absolute or relative (to ServerRoot) path of
the ACL file governing this section of the server's URL space. This can be
applied to virtual URL spaces provided by other modules, such as DAV or
SVN, using the Apache <Location> container. If the path contains %0,
it is replaced by this virtual server's hostname. If it contains %1, %2,
... it is replaced with the 1st, 2nd, ... component of the request's URI,
separated by slashes and counting from immediately after the initial
slash.
- GridSiteExecMethod nosetuid|suexec|X509DN|directory
- Execution strategy for CGI scripts and executables. For
options other than nosetuid, suexec (or gsexec renamed suexec) must
installed. For X509DN and directory, gsexec must be installed, as suexec.
See gsexec(8) for an explanation of the different execution
strategies. (Default: nosetuid)
- GridSiteUserGroup user group
- Unix user and group when using suexec (or gsexec as
suexec.) This is equivalent to the suexec SuexecUserGroup directive, but
can be specified on a per-directory basis. (Default: none)
- GridSiteDiskMode GroupNone|GroupRead|GroupWrite
WorldNone|WorldRead
- The file creation permissions mode, taking two arguments to
specify the group and other permissions. The mode always includes read and
write permission for the CGI user itself. (Default: GroupNone WorldNone)
- GridSiteCastUniPort port
- The UDP unicast port to listen on for HTCP queries,
and from which to send replies to HTCP unicast and multicast queries.
Ideally, this should be a privileged port below 1024. This directive may
not appear within a virtual server. (Default: 777)
- GridSiteCastGroup group[:port]
- A UDP multicast group on which to listen for HTCP queries,
plus an optional port. If no port is given, then 777 is used. Multiple
GridSiteCastGroup directives can be given to cause the UDP responder to
listen to more than one multicast group. This directive may not appear
within a virtual server.
- GridSiteCastAlias URL-prefix path-prefix
- Maps SiteCast generic URLs to the local filesystem. When
processing HTCP queries, matching SiteCast URLs will have URL-prefix
stripped off and the remaining portion of the URL added to path-prefix to
construct a local path and filename. If a file is found with that name, a
SiteCast HTCP response will be returned to the querying host. Otherwise
the queries are ignored. This directive may appear within virtual servers,
and the virtual server's servername and first port will determine the host
and port name used to construct the transfer URL.
ENVIRONMENT¶
The following variables are present in the environment of CGI programs and other
dynamic content systems if the
GridSiteEnvs on directive is in effect.
- GRST_PERM
- Numerical value of the permission bit-map obtained by
comparing the user with the GACL in force. (These should be tested using
the GRSTgaclPermHasXXXX functions from GACL.)
- GRST_PASSCODE_COOKIE
- Value of GRIDHTTP_PASSCODE cookie that should be returned
when using a double-submit cookie procedure to guard against Cross Site
Request Forgery (CSRF) attacks. This is only set if a valid passcode file
was found in the server's sessions directory.
- GRST_ADMIN_LIST
- URI of the DN List, listing people with full admin and
write access to the whole site.
- GRST_GSIPROXY_LIMIT
- Maximum valid delegation level for GSI Proxies.
- GRST_DIR_PATH
- Absolute path in the local filesystem to the directory
holding the file being requested.
- GRST_DESTINATION_TRANSLATED
- Present if a WebDAV Destination: header was given in
the request with a local URL. Contains the translation of the URL given
into an absolute path in the local filesystem.
- GRST_HELP_URI
- URI of website help pages set by GridSiteHelpURI directive.
- GRST_ADMIN_FILE
- Filename of per-directory ghost gridsite-admin.cgi program.
(This is used by real-gridsite-admin.cgi to construct links in its pages.)
- GRST_EDITABLE
- Space-separated list of extensions which can safely be
edited with a Text/HTML editor.
- GRST_HEAD_FILE and GRST_FOOT_FILE
- Filenames of standard header and footer files.
- GRST_DN_LISTS
- DN lists search path.
- GRST_DN_LISTS_URI
- Directory of virtual URIs used to publish this site's DN
Lists.
- GRST_UNZIP
- Full path to the unzip(1) binary, used to list and
unpack .zip files.
- GRST_NO_LINK
- If set, do not include credit links to GridSite in page
footers.
- GRST_ACL_FORMAT
- Format to use when writing .gacl files: either GACL or
XACML.
- GRST_EXEC_METHOD
- Specified by GridSiteExecMethod either suexec,
X509DN or directory.
- GRST_EXEC_DIRECTORY
- The directory containing the CGI script or executable (used
by gsexec to determine which pool account to use in directory mapping
mode.)
- GRST_DISK_MODE
- The Apache disk permission modes bit pattern, in
hexadecimal, starting with 0x. (Similar to the Unix bit pattern, except
with hexadecimal rather than octal values: eg 0x600 [Apache] vs 0600
[Unix] are both read/write for user only.)
AUTHOR¶
Andrew McNab <Andrew.McNab@manchester.ac.uk>
mod_gridsite is part of GridSite:
http://www.gridsite.org/
SEE ALSO¶
htcp(1), httpd(8), gsexec(8)