1MOD_GRIDSITE(8) GridSite Manual MOD_GRIDSITE(8)
2
3
4
6 mod_gridsite - Grid extensions to Apache httpd
7
9 LoadModule gridsite_module mod_gridsite.so
10
12 mod_gridsite is an Apache 2.0 module which enforces access control via
13 Grid Access Control Lists, and X.509, GSI or VOMS credentials.
14 mod_gridsite also gives Apache built-in support for the HTTP PUT and
15 DELETE methods, and formatting of HTML pages with standard headers and
16 footers.
17
18 Since mod_gridsite access control within Apache itself, Grid authoriza‐
19 tion and the associated verified credentials are available to all tech‐
20 nologies supported by Apache, including static file serving, SSI, CGI,
21 PHP, mod_perl and Java servlets via a connector to Tomcat.
22
23 Operation of mod_gridsite can be configured using runtime directives in
24 Apache's standard httpd.conf configuration file. The module must first
25 be loaded with a LoadModule directive:
26
27 LoadModule gridsite_module /PATH/TO/MODULES/mod_gridsite.so
28
29 The module's behaviour is then controlled by GridSite... directives
30 within Apache <Directory ...> sections, allowing different directories
31 to use GridSite features in different ways.
32
33
35 GridSiteIndexes on|off
36 Determines whether GridSite generates HTML directory listings.
37 These have some advantages over standard Apache directory list‐
38 ings (eg the displayed filenames are never truncated) and will
39 include standard headers and footers if GridSiteHtmlFormat is
40 on. (Default: GridSiteIndexes off)
41
42
43 GridSiteIndexHeader file
44 If the named file is found in the directory being listed, the
45 file is included verbatim at the top of the listing and excluded
46 from the file-by-file listing. The file can either be HTML or
47 plain text (in which case browsers will be treat it as one HTML
48 paragraph.) (Default: none)
49
50
51 GridSiteHtmlFormat on|off
52 Determines where HTML pages receive additional formatting before
53 being sent to the client. This includes the "Last modified",
54 "View page history", "Switch to HTTP(S)", "Print View" and
55 "Built with GridSite" footer elements. If header and footer
56 files are found, they will be used too. (Default: GridSiteHtml‐
57 Format off)
58
59
60 GridSiteHeadFile file
61
62 GridSiteFootFile file
63 Set the filenames to be used for as standard headers and footers
64 for HTML pages. If the file name begins with "/" then this is
65 used as the absolute path to that file to be used. Otherwise,
66 for each HTML page, the directory of that page is tried first,
67 and then parent directories in ascending order until a header /
68 footer file is found. Header files are inserted in place of HTML
69 <body[ ...]> tags; footer files in place of </body>. (These
70 standard files should each include the appropriate body tag as a
71 replacement.) (Defaults: GridSiteHeadFile gridsitehead.txt,
72 GridSiteFootFile gridsitefoot.txt)
73
74
75 GridSiteAuth on|off
76 Enables GridSite access control features, using GACL files. The
77 files are named .gacl and are per-directory. The current direc‐
78 tory is tried and then parent directories in ascending order
79 until a .gacl file is found. (Default: GridSiteAuth off)
80
81
82 GridSiteAutoPasscode on|off
83 Whether to automatically issue passcodes in response to HTTPS
84 requests made using a full X.509 certificate (not a GSI proxy.)
85 (Default: GridSiteAutoPasscode on)
86
87
88 GridSiteRequirePasscode on|off
89 Whether to require passcode cookies when processing HTTPS
90 requests made using a full X.509 certificate (not a GSI proxy.)
91 (Default: GridSiteRequirePasscode off)
92
93
94 GridSiteZoneSlashes number
95 How many slashes to include in passcode paths. The path is the
96 prefix of REQUEST_URI that includes that number of slashes.
97 Path matching is checked by mod_gridsite in addition to any
98 selection of cookies by path made by the browser. (Default:
99 GridSiteZoneSlashes 1)
100
101
102 GridSiteAdminList uri
103 All members of the DN List with name "uri" receive the full set
104 of permissions, irrespective of per-directory .gacl files. Peo‐
105 ple in this group have full control over the whole site.
106 (Default: none)
107
108
109 GridSiteGSIProxyLimit limit
110 When using GSI Proxy credentials, proxies with delegation depth
111 greater than "limit" will be ignored by mod_gridsite authoriza‐
112 tion decisions. A limit of zero implies only full X.509 certifi‐
113 cates (and no proxies) will be accepted. A limit of 1 implies
114 that only the initial proxy, usually created on the user's own
115 machine, is acceptable. Higher levels lead to proxies on remote
116 machines, eg used by running jobs, being accepted. (Default:
117 GridSiteGSIProxyLimit 1)
118
119
120 GridSiteMethods [GET] [PUT] [DELETE] [MOVE]
121 Specifies which HTTP methods are supported by GridSite. GET (and
122 HEAD) are always supported. PUT and DELETE support is turned on
123 by this directive, subject to a positive statement that write
124 permission is allowed for the directory in question, by a GACL
125 file. (Default: GridSite GET)
126
127
128 GridSiteDNlists directory1[:directory2[:directory3]...]
129 Sets up the DN List path used by GACL for evaluating <dn-list>
130 credentials. If this directive is not used, then GACL will use
131 the GRST_DN_LISTS variable from Apache's own environment. If
132 that is not set either, then /etc/grid-security/dn-lists is
133 searched. (Default: none)
134
135
136 GridSiteDNlistsURI uri
137 If GridSiteDNlistsURI is used, then the URI given appears to be
138 populated with all the DN lists on the current DN lists path
139 which match the current server. That is, for server
140 https://example.org/ with DN lists URI /dn-lists/, all DN lists
141 with URLs starting https://example.org/dn-lists/ will appear to
142 be present in /dn-lists/, irrespective of where in the path they
143 are stored. (Default: none) <p>
144
145
146 GridSiteAdminURI uri
147 GridSiteAdminURI gives the absolute URI on the server of the
148 GridSite Admin CGI program, which is used for file management,
149 HTML and GACL editing. This should be used in conjunction with
150 the standard Apache directive ScriptAlias to map that URI to the
151 real-gridsite-admin.cgi executable. For example:
152
153 ScriptAlias /real-gridsite-admin.cgi /PATH/TO/real-gridsite-
154 admin.cgi
155
156 This URI is always reached by an internal redirection from the
157 value set by GridSiteAdminFile, and is never visible to users.
158 (Default: none)
159
160
161 GridSiteAdminFile cgifilename
162 If GridSiteAdminURI is set, then the cgifilename of GridSiteAd‐
163 minFile appears to be present in all directories when explicitly
164 requested (it does not appear in directory listings.) Requests
165 for these ghost CGI URIs are internally redirected to the value
166 set by GridSiteAdminURI. (Default: GridSiteAdminFile gridsite-
167 admin.cgi)
168
169
170 GridSiteEnvs on|off
171 This makes mod_gridsite export several variables into the envi‐
172 ronment of CGI programs and other dynamic content systems. The
173 variable names are listed below. For gridsite-admin.cgi mecha‐
174 nism to work, this switch must be left in its default state of
175 on. (Default: GridSiteEnvs on)
176
177
178 GridSiteEditable [ext1 [ext2 [ext3] ...]]]
179 A space-separated list of file extensions which can safely be
180 edited by the GridSite Text/HTML editor. The extensions are
181 given without the initial dot. This directive must apply to the
182 gridsite-admin.cgi executable, rather than just to the files it
183 manages. This is most easily achieved by placing GridSiteEd‐
184 itable in the main section of the virtual host, outside any
185 Directory or Location containers. (Default: GridSiteEditable
186 txt shtml html htm css js php jsp)
187
188
189 GridSiteHelpURI uri
190 If set, gives the URI to use for "Website Help" links in HTML
191 page footers. (Default: none)
192
193
194 GridSiteLoginURI uri
195 If set, gives the URI prefix to use for login/logout links in
196 page footers. The text "Login/Logout" will be a link to the pre‐
197 fix followed by the value of REQUEST_URI for the page in ques‐
198 tion. (Default: none)
199
200
201 GridSiteLink on|off
202 Turns off the link in the HTML page footers which gives credit
203 to GridSite. (Default: GridSiteLink on)
204
205
206 GridSiteUnzip path
207 If "path" is set by this directive, then real-gridsite-admin.cgi
208 will offer to list the contents of .zip archives on the server.
209 Users with write access are able to unpack the contents into the
210 same directory as the .zip file. The value of "path"
211 must point to the location of the unzip binary. (Default: none)
212
213
214 GridSiteGridHTTP on|off
215 Enable GridHTTP for this server, virtual server or directory:
216 HTTPS requests made with the header Upgrade: GridHTTP/1.0 will
217 be redirected to an HTTP version of the file. (Default: off)
218
219
220 GridSiteGridHTTPport port
221 Sets the port to use for the unencrypted HTTP component of Grid‐
222 HTTP HTTPS->HTTP transfers. The same setting will be used for
223 all virtual hosts which support GridHTTP. (Default: 777)
224
225
226 GridSiteSessionsDir path
227 Location of authentication cookies and SSL session credentials
228 directory, relative to ServerRoot. Used by GridHTTP to record
229 the credentials obtained via HTTPS, and available to the corre‐
230 sponding HTTP request or subsequent HTTPS requests following a
231 session restart. (Default: /var/www/sessions)
232
233
234 GridSiteACLFormat GACL|XACML
235 Format to use when writing .gacl files. (Both formats are auto‐
236 matically recognised when reading.) (Default: GACL)
237
238
239 GridSiteACLPath path
240 Specify the absolute or relative (to ServerRoot) path of the ACL
241 file governing this section of the server's URL space. This can
242 be applied to virtual URL spaces provided by other modules, such
243 as DAV or SVN, using the Apache <Location> container. If the
244 path contains %0, it is replaced by this virtual server's host‐
245 name. If it contains %1, %2, ... it is replaced with the 1st,
246 2nd, ... component of the request's URI, separated by slashes
247 and counting from immediately after the initial slash.
248
249
250 GridSiteExecMethod nosetuid|suexec|X509DN|directory
251 Execution strategy for CGI scripts and executables. For options
252 other than nosetuid, suexec (or gsexec renamed suexec) must
253 installed. For X509DN and directory, gsexec must be installed,
254 as suexec. See gsexec(8) for an explanation of the different
255 execution strategies. (Default: nosetuid)
256
257
258 GridSiteUserGroup user group
259 Unix user and group when using suexec (or gsexec as suexec.)
260 This is equivalent to the suexec SuexecUserGroup directive, but
261 can be specified on a per-directory basis. (Default: none)
262
263
264 GridSiteDiskMode GroupNone|GroupRead|GroupWrite WorldNone|WorldRead
265 The file creation permissions mode, taking two arguments to
266 specify the group and other permissions. The mode always
267 includes read and write permission for the CGI user itself.
268 (Default: GroupNone WorldNone)
269
270
271 GridSiteCastUniPort port
272 The UDP unicast port to listen on for HTCP queries, and from
273 which to send replies to HTCP unicast and multicast queries.
274 Ideally, this should be a privileged port below 1024. This
275 directive may not appear within a virtual server. (Default: 777)
276
277
278 GridSiteCastGroup group[:port]
279 A UDP multicast group on which to listen for HTCP queries, plus
280 an optional port. If no port is given, then 777 is used. Multi‐
281 ple GridSiteCastGroup directives can be given to cause the UDP
282 responder to listen to more than one multicast group. This
283 directive may not appear within a virtual server.
284
285
286 GridSiteCastAlias URL-prefix path-prefix
287 Maps SiteCast generic URLs to the local filesystem. When pro‐
288 cessing HTCP queries, matching SiteCast URLs will have URL-pre‐
289 fix stripped off and the remaining portion of the URL added to
290 path-prefix to construct a local path and filename. If a file is
291 found with that name, a SiteCast HTCP response will be returned
292 to the querying host. Otherwise the queries are ignored. This
293 directive may appear within virtual servers, and the virtual
294 server's servername and first port will determine the host and
295 port name used to construct the transfer URL.
296
297
299 The following variables are present in the environment of CGI programs
300 and other dynamic content systems if the GridSiteEnvs on directive is
301 in effect.
302
303
304 GRST_PERM
305 Numerical value of the permission bit-map obtained by comparing
306 the user with the GACL in force. (These should be tested using
307 the GRSTgaclPermHasXXXX functions from GACL.)
308
309
310 GRST_PASSCODE_COOKIE
311 Value of GRIDHTTP_PASSCODE cookie that should be returned when
312 using a double-submit cookie procedure to guard against Cross
313 Site Request Forgery (CSRF) attacks. This is only set if a valid
314 passcode file was found in the server's sessions directory.
315
316
317 GRST_ADMIN_LIST
318 URI of the DN List, listing people with full admin and write
319 access to the whole site.
320
321
322 GRST_GSIPROXY_LIMIT
323 Maximum valid delegation level for GSI Proxies.
324
325
326 GRST_DIR_PATH
327 Absolute path in the local filesystem to the directory holding
328 the file being requested.
329
330
331 GRST_DESTINATION_TRANSLATED
332 Present if a WebDAV Destination: header was given in the request
333 with a local URL. Contains the translation of the URL given into
334 an absolute path in the local filesystem.
335
336
337 GRST_HELP_URI
338 URI of website help pages set by GridSiteHelpURI directive.
339
340
341 GRST_ADMIN_FILE
342 Filename of per-directory ghost gridsite-admin.cgi program.
343 (This is used by real-gridsite-admin.cgi to construct links in
344 its pages.)
345
346
347 GRST_EDITABLE
348 Space-separated list of extensions which can safely be edited
349 with a Text/HTML editor.
350
351
352 GRST_HEAD_FILE and GRST_FOOT_FILE
353 Filenames of standard header and footer files.
354
355
356 GRST_DN_LISTS
357 DN lists search path.
358
359
360 GRST_DN_LISTS_URI
361 Directory of virtual URIs used to publish this site's DN Lists.
362
363
364 GRST_UNZIP
365 Full path to the unzip(1) binary, used to list and unpack .zip
366 files.
367
368
369 GRST_NO_LINK
370 If set, do not include credit links to GridSite in page footers.
371
372
373 GRST_ACL_FORMAT
374 Format to use when writing .gacl files: either GACL or XACML.
375
376
377 GRST_EXEC_METHOD
378 Specified by GridSiteExecMethod either suexec, X509DN or direc‐
379 tory.
380
381
382 GRST_EXEC_DIRECTORY
383 The directory containing the CGI script or executable (used by
384 gsexec to determine which pool account to use in directory map‐
385 ping mode.)
386
387
388 GRST_DISK_MODE
389 The Apache disk permission modes bit pattern, in hexadecimal,
390 starting with 0x. (Similar to the Unix bit pattern, except with
391 hexadecimal rather than octal values: eg 0x600 [Apache] vs 0600
392 [Unix] are both read/write for user only.)
393
394
396 Andrew McNab <Andrew.McNab@manchester.ac.uk>
397
398 mod_gridsite is part of GridSite: http://www.gridsite.org/
399
401 htcp(1), httpd(8), gsexec(8)
402
403
404
405mod_gridsite October 2005 MOD_GRIDSITE(8)