Provided by: gridsite_3.0.0~20180202git2fdbc6f-3build5_amd64 bug

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