1MOD_GRIDSITE(8)                 GridSite Manual                MOD_GRIDSITE(8)
2
3
4

NAME

6       mod_gridsite - Grid extensions to Apache httpd
7

SYNOPSIS

9       LoadModule gridsite_module mod_gridsite.so
10

DESCRIPTION

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

DIRECTIVES

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  &quot;path&quot;
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

ENVIRONMENT

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

AUTHOR

396       Andrew McNab <Andrew.McNab@manchester.ac.uk>
397
398       mod_gridsite is part of GridSite: http://www.gridsite.org/
399

SEE ALSO

401       htcp(1), httpd(8), gsexec(8)
402
403
404
405mod_gridsite                     October 2005                  MOD_GRIDSITE(8)
Impressum