MOD_GRIDSITE(8)

💖 MOD_GRIDSITE — the manual page 💖

okay bestie, welcome to the GridSite manual page for mod_gridsite, section 8. pull up a chair, grab a boba, we're doing this 🧋✨

---

🌸 NAME 🌸

mod_gridsite — Grid extensions to Apache httpd. that's it, that's the name, she's giving "I extend Apache with Grid stuff" 💅

---

✨ SYNOPSIS ✨

LoadModule gridsite_module mod_gridsite.so

literally one line. slay. 🫶

---

🦋 DESCRIPTION 🦋

okay so mod_gridsite is an Apache 2.0 module that enforces access control via Grid Access Control Lists, plus X.509, GSI or VOMS credentials. she's the bouncer at the club fr fr 💪

and that's not all — 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. multi-talented queen 👑

the way that mod_gridsite does access control inside Apache itself means that 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. everybody eats at this table 🍽️

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. per-directory vibes, we love to see it 🌈

---

👑 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. no more cut-off filenames, we stan a full-length name 💅

(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. glow-up for your HTML fr ✨

(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. it walks up the tree like it's looking for its mom in the mall 😭

(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. double-checking, because she does not play 💀

(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. main character energy, no cap 💅

(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. it's giving "how far down the proxy chain are we trusting" 🧵

(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. no GACL permission, no writing, periodt 🔥

(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. fallback queen 🫶

(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. illusion magic ✨

(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. secret passage, iykyk 🙈

(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. she's a ghost, she's everywhere and nowhere 🫥

(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. do NOT touch it, bestie 😤

(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. put it up top, she needs the whole building 💅

(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. rude but valid 🙈

(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.) she reads both, she just has a favourite 💅

(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 — how we're running our CGI scripts and executables, bestie. If you pick literally anything other than nosetuid, you need suexec installed (or gsexec renamed to suexec, we love a rebrand 💅). And if you're going X509DN or directory, then gsexec has to be installed as suexec, periodt. The whole lore behind these strategies lives in gsexec(8). (Default: nosetuid)
• GridSiteUserGroup user group — the Unix user and group to use when you're running under suexec (or gsexec pretending to be suexec). It's the same energy as suexec's own SuexecUserGroup directive, except you can set it per-directory. (Default: none)
• GridSiteDiskMode GroupNone|GroupRead|GroupWrite WorldNone|WorldRead — the file creation permissions mode, and it takes two arguments: one for group perms, one for world perms. The CGI user themselves always gets read and write, no matter what. (Default: GroupNone WorldNone)
• GridSiteCastUniPort port — the UDP unicast port we listen on for HTCP queries, and the one we reply from for both unicast and multicast HTCP queries. Ideally this is a privileged port below 1024, if you can swing it. Heads up: this directive may not appear within a virtual server. (Default: 777)
• GridSiteCastGroup group[:port] — a UDP multicast group to listen on for HTCP queries, plus an optional port. No port given? Then 777 it is. You can stack multiple GridSiteCastGroup directives so the UDP responder listens to more than one multicast group, because why choose. Also: this one may not appear within a virtual server.
• GridSiteCastAlias URL-prefix path-prefix — maps SiteCast generic URLs onto the local filesystem. When we're chewing through HTCP queries, any matching SiteCast URL gets its URL-prefix stripped off, and whatever's left gets glued onto path-prefix to build a local path and filename. Find a file there? Boom, a SiteCast HTCP response goes back to the querying host. No file? The query just gets ignored, respectfully. This one may appear inside virtual servers, and the virtual server's servername plus its first port decide the host and port used to build the transfer URL.

---

🌸 ENVIRONMENT 🌸

These variables are chillin' in the environment of CGI programs and other dynamic content systems when the GridSiteEnvs on directive is in effect. (Yes, <pink>on</pink>. It has to be on. 😭)

• GRST_PERM — the numerical value of the permission bit-map you get by comparing the user against the GACL currently in force. Test these using the GRSTgaclPermHasXXXX functions from GACL, iykyk.
• GRST_PASSCODE_COOKIE — the value of the GRIDHTTP_PASSCODE cookie, the one you send back when you're doing a double-submit cookie procedure to guard against Cross Site Request Forgery (CSRF) attacks. It's only set if a valid passcode file was actually found in the server's sessions directory.
• GRST_ADMIN_LIST — the URI of the DN List, listing the people with full admin and write access to the entire site. The whole thing. 👑
• GRST_GSIPROXY_LIMIT — the 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 came in with the request containing a local URL. It holds the translation of that URL into an absolute path in the local filesystem.
• GRST_HELP_URI — URI of the website help pages, set by the GridSiteHelpURI directive.
• GRST_ADMIN_FILE — filename of the per-directory ghost gridsite-admin.cgi program. (This is what real-gridsite-admin.cgi uses to build links in its pages.)
• GRST_EDITABLE — a space-separated list of extensions that can safely be edited with a Text/HTML editor. Go off.
• GRST_HEAD_FILE and GRST_FOOT_FILE — filenames of the standard header and footer files.
• GRST_DN_LISTS — the 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 it's set, do not include credit links to GridSite in page footers. (Rude but valid. 🙈)
• GRST_ACL_FORMAT — the format to use when writing .gacl files: either GACL or XACML.
• GRST_EXEC_METHOD — specified by GridSiteExecMethod, and it'll be either suexec, X509DN or directory.
• GRST_EXEC_DIRECTORY — the directory containing the CGI script or executable. (This is what gsexec peeks at to figure out which pool account to use in directory mapping mode.)
• GRST_DISK_MODE — the Apache disk permission modes bit pattern, in hexadecimal, starting with 0x. It's similar to the Unix bit pattern, except it's hexadecimal instead of octal values: for example 0x600 (Apache) vs 0600 (Unix) are both read/write for user only. Cute little crossover episode. ✨

---

🫶 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)

---

And that's the whole page, bestie, no notes. 💖 This one's from mod_gridsite, dated October 2005, and it lives at MOD_GRIDSITE(8) — go forth and configure responsibly, mwah 💅✨