+* Tue Oct 4 2005 Andrew McNab <Andrew.McNab@man.ac.uk>
+- Move User, Config, Admin and Install guides from
+ doc directory into GridSite Wiki.
+- Create/update man pages for htcp, mod_gridsite and
+ gsexec to be distributed with source/binaries.
* Mon Oct 3 2005 Andrew McNab <Andrew.McNab@man.ac.uk>
- Fix to gsexec GRST_CRED_0/SSL_CLIENT_S_DN bug found
by Ian Stokes-Rees <i.stokes-rees1@PHYSICS.OX.AC.UK>
BUILDING/INSTALLING GRIDSITE
============================
-For more detailed instructions, see the install.html file, either
-in the ./doc subdirectory in the sources, in the directory
-gridsite-VERSION/html of the docs directory when GridSite is
-installed, or http://www.gridsite.org/1.1.x/install.html
+For more detailed instructions, see the Installation and Build
+pages in the GridSite Wiki http://www.gridsite.org/wiki/
GridSite is currently only supported on Linux, but should be
trivially portable to other Unix platforms where the GNU build
-See INSTALL for build and installation instructions, and
-the Documentation section of http://www.gridsite.org/
-for configuration and usage guides.
+See INSTALL for build and installation instructions, and the
+man pages for reference information.
+
+The GridSite Wiki at http://www.gridsite.org/wiki/ has guides
+and cookbook examples.
+++ /dev/null
-<title>GridSite Admin Guide</title>
-<body>
-<h1 align=center>GridSite Admin Guide</h1>
-
-<p>
-This Guide is intended for people administrating areas of GridSite
-websites or fileservers, or managing GridSite's DN List groups - that is,
-how to use GridSite to manage other people's access to parts of the site -
-for example, people's write access to areas devoted to specific subprojects.
-
-<p>
- There is a separate
-<a href="user.html">User Guide</a>
- which explains how to authenticate to the server with X.509 certificates,
-and how to manage files via a standard web browser or with command-line
-HTTPS clients. You should be familiar with the User Guide to fully
-understand this Admin Guide.
-
-<p>
- You may also find the
-<a href="config.html">Config Guide</a>
- useful to understand how the Apache webserver is configured with GridSite
-extensions. If you are also the Apache webmaster for your site, you will
-definitely need to read the Config Guide to create the httpd.conf file.
-However, if you only need to manage webpages and files, then this Admin
-Guide and the User Guide should be sufficient.
-
-<h2>Groups and DN Lists</h2>
-
-<p>
-GridSite defines groups of people using plain text DN Lists - that is, lists
-of people's certificate DNs. Each DN List has a URL which uniquely
-identifies the list (and may also allow other sites to obtain the list and
-use it themselves.) For example, the list of all GridPP members is
-https://www.gridpp.ac.uk/dn-lists/gridpp (note that it's https:// not
-http:// - this means that other sites that download the list can check the
-certificate of www.gridpp.ac.uk and know they're talking to the
-authoritative source of the lists.)
-
-<p>
-The system can also have a number of other DN Lists which are associated with
-specific groups of people and perhaps with specific areas of responsibility
-of the website. If the DN List directory URI is /dn-lists/ then
-there is a full list of the DN Lists exported by the server at that URI
-(for example, https://www.gridpp.ac.uk/dn-lists/ )
-
-<p>
-If you have permission to modify a DN List, you can start changing it by
-going to /dn-lists/ (via HTTPS), using the "Manage directory"
-button and finding the URL of your DN List in the listings. You may
-need to go down into a subdirectory to find your list. For
-example, https://www.gridpp.ac.uk/dn-lists/atlas is in the atlas
-subdirectory of /dn-lists/ (You may wish to bookmark the listing of such
-a directory if you frequently work with one.)
-
-<p>
-DN List directories are managed by the ACLs described in the next section,
-and if you have write permission, you can edit the lists already there, and
-add new lists with the same prefix (this means you can readily create your
-own subgroups.)
-
-<h2>Access Control Lists</h2>
-
-<p>
-DN Lists appear in the Grid Access Control Lists (GACL) used by GridSite.
-These are stored as .gacl files in directories: if the .gacl file is
-present, it governs access to the directory; if it is absent, then the
-parent directories are searched upwards until a .gacl is found.
-
-<p>
-The GridSite <a href="gacl.html">GACL Reference</a> explains the XML format
-of these files, but they
-can be edited using the ACL editor built into the GridSite system by people
-who have the Admin permission within the ACL.
-
-<p>
-If you have this permission in a given directory, when you view directory
-listings or files in that directory you will see the option "Manage
-Directory" in the page footer. This allows you to get a listing of the
-directory and the .gacl file will appear at the top if it's present. If not,
-then there will be a button to create a new .gacl file with the same
-permissions as have been inherited by that directory from its parent.
-
-<p>
-GACL allows quite complex conditions to be imposed on access, but normally
-you can think of an ACL as being composed of a number of entries, each of
-which contains one condition (the required credential) and a set of allowed
-and denied permissions.
-
-<p>
-Credentials can be individual user's certificate names or whole groups of
-certificate names if a DN List is given. (You can also specifiy hostname
-patterns using Unix shell wildcards (eg *.ac.uk) or EDG VOMS attribute
-certificates - see the GACL Reference for details.)
-
-<p>
-Permissions can be Admin (edit the ACL), Write (create, modify or delete
-files), List (browse the directory) or Read (read files.) Permissions can be
-allowed or denied. If denied by any entry, the permission is not available
-to that user or DN List (depending on what credential type was associated
-with the Deny.)
-
-</body>
+++ /dev/null
-<title>GridSite Config Guide</title>
-<body>
-<h1 align=center>GridSite Config Guide</h1>
-
-<p>
-This Guide is intended for webmasters setting up
-<a href="http://www.gridsite.org/">GridSite</a> with an Apache 2.0
-webserver. We assume you have root access to the server machine to do this.
-There is a separate <a href="admin.html">Admin Guide</a> for
-people administrating areas of GridSite
-websites or fileservers, or managing GridSite's DN List groups. That is, for
-people managing files on the server rather than the server itself.
-
-<h2>Installation</h2>
-
-<p>
-We assume you have installed Apache 2.0 and GridSite, using the
-<a href="install.html">Building and Installation Guide</a> where necessary.
-This Config Guide assumes installation has been done under /usr. For an
-alternative tree like /usr/local, the relative paths should be the same.
-
-<p>
-Installation should have given you an Apache 2.0 httpd binary at
-/usr/sbin/httpd and a set of standard Apache 2.0 modules in
-/usr/lib/httpd/modules/ including the standard mod_ssl
-and our mod_gridsite.so module.
-
-<p>
-GridSite also includes some commands and man pages in /usr/bin and
-/usr/share/man/man1: <a href="urlencode.1.html">urlencode</a> and
-<a href="htcp.1.html">htcp</a>.
-
-<h2>Certificates</h2>
-
-<p>
-You must also install the CA root certificates of the CA's
-used by the users you wish to talk to. These should be installed in
-/etc/grid-security/certificates as files like 01621954.0, and RPMs and tar
-files for many common European and North American CAs are available via the
-<a href="http://www.eugridpma.org/">EU Grid PMA</a>.
-
-<p>
-This location also has VOMS server certificate RPMs which install into
-the /etc/grid-security/vomsdir directory. You may also manually install VOMS
-server certificates into that directory with any filename. (GridSite
-currently parses the certificate itself when looking for a match, rather
-than checking the filename.)
-
-<p>
-The server itself needs a certificate to supply to clients that use HTTPS
-connections. You should apply for this from your Certification Authority
-(for example, the <a href="http://ca.grid-support.ac.uk/">UK e-Science
-CA</a>) and your request must use the advertised hostname of your server
-(the one that appears in URLs and not, for instance, the canonical name of
-the host itself.) This advertised hostname should appear in the
-Distinguished Name of your request. (For example
-/C=UK/O=eScience/OU=Manchester/L=HEP/CN=www.gridpp.ac.uk) For compatability
-with standard browsers, the /CN= component should not include any
-Globus-style service name (so <b>not</b> /CN=host/www.gridpp.ac.uk) If
-possible, you should also include the advertised hostname as a DNS Subject
-Alternative Name. Consult your CA first if you're in any doubt about how to
-compose your certificate request.
-
-<p>
-Once you've got your certificate,
-Apache uses the certificate and private key in PEM format. If you obtained
-your certificate and key in PKCS#12 or .p12 format (eg by exporting from a web
-browser), you can convert the .p12 file to .pem with the following commands:
-<pre>
-openssl pkcs12 -in ck.p12 -clcerts -nokeys -out hostcert.pem
-openssl pkcs12 -in ck.p12 -nodes -nocerts -out hostkey.pem
-</pre>
-
-<p>
-Copy the PEM files to /etc/grid-security/ as hostcert.pem (which
-should be world readable) and hostkey.pem (which should only be readable by
-root):
-
-<pre>
-chown root.root hostkey.pem hostcert.pem
-chmod 400 hostkey.pem
-chmod 444 hostcert.pem
-</pre>
-
-<h2>httpd.conf</h2>
-
-<p>
-/etc/httpd/conf/httpd.conf is the key to configuring the Apache 2.0
-webserver. The directives in this file determine which files the server will
-publish, how they are handled, which areas are writeable and who can access
-them. Through mod_gridsite.so, the GridSite system itself is configured by
-directives in this file.
-
-<p>
-The easiest way to get started is to examine the example httpd.conf files we
-provide.
-
-<p>
-<b>Please note: this version of GridSite is <b>not</b> compatible with the
-SHM SSL session cache - use the DBM or per-process caches instead.
-
-<!--
-virtual servers
-directory sections
-order of loadable modules
--->
-
-<h2>httpd-fileserver.conf</h2>
-
-<p>
-<a href="httpd-fileserver.conf">httpd-fileserver.conf</a> is an example
-configuration file to use Apache/GridSite as a read/write HTTP(S)
-fileserver, including comments on how to get the server up and running.
-
-<h2>httpd-webserver.conf</h2>
-
-<p>
-<a href="httpd-webserver.conf">httpd-webserver.conf</a> is an example
-configuration file to use Apache/GridSite as a Web Server
-(that is, primarily for interactive use with a browser)
-including comments on how to get the server up and running.
-
-<h2>GridSite Directives</h2>
-
-<p>
-The <a href="module.html">mod_gridsite reference</a> lists all the GridSite
-httpd.conf directives.
-
-<p>
-To start serving files, make a directory /var/www/htdocs owned by
-nobody.nobody, including the .gacl access control file described below,
-and add the following directive to the HTTPS <Directory> section:
-
-<p>
-GridSiteMethods GET PUT DELETE
-
-<p>
-If you wish to accept Globus GSI Proxies as well as full X.509 user
-certificates, set GridSiteGSIProxyLimit to the depth of proxy you
-wish to accept. (As a _rough_ guide: 0=No Proxies; 1=Proxy on user's
-machine; 2=Proxy owned by running Globus job; 3=Proxy delegated by a
-Globus job.)
-
-<h2>GACL access control</h2>
-
-<p>
-The <a href="gacl.html">GACL reference</a> explains the XML access
-control files used by GridSite. These allow flexible policies to be written,
-in terms of X.509 user certificates, GSI proxies, VOMS attribute
-certificates, DN List groups and DNS hostnames.
-
-<p>
-For example, to give all clients read and list permission:
-<p>
-<pre>
-<gacl>
-<entry>
- <any-user/>
- <allow><read/><list/></allow>
-</entry>
-</gacl>
-</pre>
-
-<p>
-To enable writing, add DN List, Person or VOMS entries to the file.
-For example:
-
-<p>
-<pre>
-<gacl>
-<entry>
- <any-user/>
- <allow><read/><list/></allow>
-</entry>
-<entry>
- <person>
- <dn>/C=UK/O=eScience/OU=Manchester/L=HEP/CN=Andrew McNab</dn>
- </person>
- <allow><write/></allow>
-</entry>
-</gacl>
-</pre>
-
-<p>
-The GACL file that governs a directory is stored as .gacl in that directory.
-If no .gacl is present, then GridSite will search the parent directories in
-ascending order until one is found.
-
-<!--
-<h2>DN Lists</h2>
-<h2>gridsite-admin.cgi</h2>
-<h2>Other CGI</h2>
--->
-
-</body>
-.TH findproxyfile 1 "October 2004" "findproxyfile" "FINDPROXYFILE Manual"
+.TH findproxyfile 1 "October 2004" "findproxyfile" "GridSite Manual"
.SH NAME
.B findproxyfile
\- returns full path to GSI Proxy file
+++ /dev/null
-<title>GridSite: Grid Access Control Language</title>
-<body>
-<h1 align=center>GridSite: Grid Access Control Language</h1>
-
-<p>
-GACL is the authorization policy language used by
-<a href="http://www.gridsite.org/">GridSite</a> GACL allows
-policies to be written in terms of common Grid credentials: X.509
-identities, GSI proxies, VOMS attribute certificates and lists of X.509
-identities.
-
-<p>
-GridSite both uses GACL policies and provides a GACL manipulation API for
-C/C++ in the GridSite library.
-
-<h2>Credentials</h2>
-
-<p>
-In GridSite 1.1.x, four credential types are supported:
-
-<p>
-<person>
-<dn>/O=Grid/CN=Name</dn>
-</person>
-
-<p>
-<voms>
-<fqan>/vo.dom.ain/group</fqan>
-</voms>
-
-<p>
-<dn-list>
-<url>https://www.vo.dom.ain/dn-lists/group</url>
-</dn-list>
-
-<p>
-<dns>
-<hostname>host*.dom.ain</hostname>
-</dns>
-
-<h2>Permissions</h2>
-
-<p>
-Five permissions are supported: Admin, Write, List, Exec and Read. Admin is
-permission to modify the authorization policy itself, but applications can
-map the other permissions to local methods as appropriate to their
-environment. For filesystems and fileservers, Write, List and Read have
-their usual meanings: creating or modifying files or directories; browsing
-directories; reading files. Exec is not used by GridSite itself, and
-applications are free to give it a meaning within their own contexts.
-
-<p>
-In 1.0.x, only per-directory GACL files are supported, and the file is stored
-in the directory in question, or in one of its parent directories. (GridSite
-searches upwards until it finds one.)
-
-<p>
-In GACL files, the permissions are represented by single tags:
-<admin/>, <write/>, <list/>, <exec/>, <read/>.
-Permission
-tags are contained within Allow or Deny blocks. For example:
-<allow><read/><list/></allow> or
-<deny><admin/></deny>.
-
-<h2>Entries</h2>
-
-<p>
-Entries associate credentials with permission statements. Entries consist of
-one or more credential blocks, and either an Allow or a Deny block, or both.
-If multiple credentials are present in one entry, they must all be held by a
-user to receive the association permissions. (So Entries provide logical AND
-of credentials.)
-
-<h2>Access Control Lists</h2>
-
-<p>
-ACLs consist of a list of one or more Entry blocks. When a user's credentials
-are compared to the ACL, the permissions given to the user by Allow blocks
-are recorded, along with those forbidden by Deny blocks. When all entries
-have been evaluated, any forbidden permissions are removed from those
-granted. (So Deny always wins over Allow, even between different Entries,
-but otherwise ACLs provide logical OR of credentials.)
-
-</body>
-.de Sh \" Subsection
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Ip \" List item
-.br
-.ie \\n(.$>=3 .ne \\$3
-.el .ne 3
-.IP "\\$1" \\$2
-..
-.TH "GSEXEC" 8 "2005-05-27" "GridSite Apache Extensions" "gsexec"
-
+.TH GSEXEC 8 "October 2005" "gsexec" "GridSite Manual"
.SH NAME
-gsexec \- Switch user before executing external programs
+.B gsexec
+\- Switch user before executing external programs
.SH "SYNOPSIS"
-.PP
-\fBgsexec\fR -\fBV\fR
+.BR gsexec
+[-V]
-
.SH "SUMMARY"
-
-.PP
+
gsexec is used by the Apache HTTP Server to switch to another user before
executing CGI programs\&. In order to achieve this, it must run as root\&.
Since the HTTP daemon normally doesn't run as root, the gsexec executable
needs the setuid bit set and must be owned by root\&. It should never be
writable for any other person than root\&.
-.PP
-gsexec is based on Apache's suexec.
-For further information about the concepts and the security model of
-the original suexec
-please refer to the suexec documentation:
+gsexec is based on Apache's suexec, and its behaviour is controlled with
+the Apache configuration file directives
+.BR GridSiteExecMethod
+and
+.BR GridSiteUserGroup
+added to Apache by
+.BR mod_gridsite(8)
+Four execution methods are supported: nosetuid, suexec, X509DN and directory,
+and these may be set on a per-directory basis within the Apache configuration
+file.
+
+.SH "NOSETUID METHOD"
+
+This is the default behaviour, but can also be produced by giving
+.BR "GridSiteExecMethod nosetuid"
+
+CGI programs will then be executed without using gsexec, and will
+run as the Unix user given by the User and Group Apache directives (normally
+apache.apache on Red Hat derived systems.)
+
+.SH "SUEXEC METHOD"
+
+If
+.BR "GridSiteExecMethod suexec"
+is given for this virtual host or directory, then CGI programs will be
+executed using the user and group given by the
+.BR "GridSiteUserGroup user group"
+directive, which may also be set on a per-directory basis (unlike suexec's
+.BR SuexecUserGroup
+which is per-server only.) The CGI program must either be owned by root,
+the Apache user
+and group specified at gsexec build-time (normally apache.apache) or by
+the user and group given with the
+.BR GridSiteUserGroup
+directive.
+
+.SH "X509DN METHOD"
+
+If
+.BR "GridSiteExecMethod X509DN"
+is given, then the CGI program runs as a pool user, detemined using lock
+files in the exec mapping directory chosen as build time of gsexec.
+The pool user is chosen according
+to the client's full certificate X.509 DN (ie with any trailing GSI proxy
+name components stripped off.) Subsequent requests by the same X.509
+identity will be mapped to the same pool user. The CGI program must either be
+owned by root, the Apache user
+and group specified at gsexec build-time (normally apache.apache) or by
+the pool user selected.
+
+.SH "DIRECTORY METHOD"
+
+If
+.BR "GridSiteExecMethod directory"
+is given, then the CGI program runs as a pool user chosen according
+to the directory in which the CGI is located: all CGIs in that directory
+run as the same pool user. The CGI program must either be
+owned by root, the Apache user
+and group specified at gsexec build-time (normally apache.apache) or by
+the pool user selected.
-(http://httpd\&.apache\&.org/docs-2\&.0/suexec\&.html)\&.
-
+
+.SH "EXECMAPDIR"
+
+The default exec mapping directory is /var/www/execmapdir and this is fixed
+when the gsexec executable is built. The exec mapping directory and all
+of its lock files must be owned and only writable by root. To initialise the
+lock files, create an empty lock file for each pool user, with the pool
+username as the filename (eg user0001, user0002, ...) As the pool users are
+leased to X.509 identities or directories, they will become hard linked to
+lock files with the URL-encoded X.509 DN or full directory path.
+
+You can recycle pool users by removing the corresponding URL-encoded
+hard link.
+.BR stat(1)
+and
+.BR "ls(1)"
+with option
+.BR "-i"
+can be used to print the inodes of lock files to match up the hard links.
+
+.BR "However, you must ensure that all files and processes owned by the pool"
+.BR "user are deleted before recycling!"
.SH "OPTIONS"
-
.TP
-V
If you are root, this option displays the compile options of gsexec\&.
For security reasons all configuration options are changeable only at
compile time\&.
+.SH "MORE INFORMATION"
+For further information about the concepts and the security model of
+the original Apache suexec
+please refer to the suexec documentation:
+
+http://httpd\&.apache\&.org/docs-2\&.0/suexec\&.html
+
+For examples using the gsexec extensions, please see the GridSite gsexec
+page:
+
+http://www.gridsite.org/wiki/Gsexec
+
+.SH AUTHORS
+
+Apache project, for original suexec
+
+Andrew McNab <Andrew.McNab@manchester.ac.uk> for gsexec modifications.
+
+gsexec is part of GridSite: http://www.gridsite.org/
+
+.SH "SEE ALSO"
+.BR httpd(8),
+.BR suexec(8),
+.BR mod_gridsite(8)
-.TH htcp 1 "September 2005" "htcp" "HTCP Manual"
+.TH HTCP 1 "October 2005" "htcp" "GridSite Manual"
.SH NAME
.B htcp, htmv, htrm, htls, htll, htmkdir, htfind, htping
\- file transfers and queries via HTTP/HTTPS/SiteCast
supported by Apache, including static file serving, SSI, CGI, PHP, JSP and
mod_perl.
-<h2>Guides</h2>
+<p>
+The <a href="http://www.gridsite.org/wiki/">GridSite Wiki</a> includes
+guides and cookbook examples about using GridSite, along with up to date
+information about the APIs.
+
+<h2>Reference</h2>
<p>
-<dl>
-<dt><b><a href="user.html">User Guide</a></b>
-<dd>End-user documentation for people managing webpages and files on
- GridSite servers, either through the web interface or with command
- line clients like htcp.
+The following reference documents and man pages are put in
+/usr/share/doc/gridsite-VERSION when GridSite is installed.
+
<p>
+<dl>
-<dt><b><a href="admin.html">Admin Guide</a></b>
-<dd>For people administering areas of GridSite websites or fileservers, or
- managing GridSite's support for DN List groups.
+<dt><b><a href="htcp.1.html">htcp(1)</a></b>
+<dd>A command line tool for copying files to or from HTTP(S) servers.
<p>
-<dt><b><a href="install.html">Building and Installation</a></b>
-<dd>Instructions for building GridSite from source, and installing from
- binaries or RPMs.
+<dt><b><a href="mod_gridsite.8.html">mod_gridsite(8)</a></b>
+<dd>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.
<p>
-<dt><b><a href="config.html">Config Guide</a></b>
-<dd>For webmasters setting up Apache 2.0 and GridSite, and writing the
- Apache httpd.conf file.
+<dt><b><a href="gsexec.8.html">gsexec(8)</a></b>
+<dd>A modified version of suexec(8), for use with mod_gridsite(8). gsexec
+ allows CGI programs to be run as pool users, depending on the client's
+ X.509 identity or the directory in which the CGI is located.
<p>
<dt><b><a href="httpd-fileserver.conf">httpd-fileserver.conf</a></b> and
webservers, with explanatory comments.
<p>
-</dl>
-
-<h2>Reference</h2>
-
-<p>
-<dl>
-<dt><b><a href="gacl.html">Grid Access Control Lists</a></b>
-<dd>Syntax and usage of the XML Grid Access Control Lists used by GridSite.
+<dt><b><a href="urlencode.1.html">urlencode(1)</a></b>
+<dd>A command for URL-encoding strings.
<p>
-<dt><b><a href="htcp.1.html">htcp</a></b> and
- <b><a href="urlencode.1.html">urlencode</a></b> man pages
-<dd>Command line tools for copying files to or from HTTP(S) servers, and
- for URL-encoding strings.
+<dt><b><a href="findproxyfile.1.html">findproxyfile(1)</a></b>
+<dd>The finxproxyfile command returns full path to a GSI Proxy file,
+ either in the proxy cache maintained by the GridSite G-HTTPS and
+ delegation portType functions, or in other standard places.
<p>
+<dt><b><a href="delegation-1.wsdl">delegation-1.wsdl</a></b>
+<dd>A WSDL description of a delegation Web Service including the Delegation
+ portType.
+<p>
+
<!--
<dt><b><a href="gridsite-admin.html">gridsite-admin.cgi</a></b>
<dd>A CGI program providing site administration functions for users with
<p>
-->
-<dt><b><a href="module.html">mod_gridsite</a></b>
-<dd>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.
-<p>
-
-<!--
-<dt><b><a href="library.html">libgridsite</a></b>
-<dd>The GridSite library provides common functions for other components of
- the GridSite system, and utilities for programs using CGI, X.509, GSI,
- VOMS and HTTP.
-<p>
--->
-
-<dt><b><a href="gridsite_8h.html">gridsite.h API reference</a></b>
+<dt><b><a href="doxygen/gridsite_8h.html">gridsite.h API reference</a></b>
<dd>A detailed description of the C API provided by libgridsite, generated
from the sources by doxygen.
<p>
+++ /dev/null
-<title>GridSite: Building and Installation Guide</title>
-<body>
-<h1 align=center>GridSite: Building and Installation Guide</h1>
-
-<p>
-This Guide explains how to build GridSite from source, and how to install
-the server components alongside an Apache 2.0 webserver. There is a
-separate <a href="config.html">Config Guide</a> which explains how to modify
-the httpd.conf file, and how to set up other files and directories used by
-the system. You should look through all of this Building and Installation
-Guide to decide which is the easiest route for your system.
-
-<h2>Installing with RPM</h2>
-
-<p>
-If you are installing on Linux with a binary RPM release, you can skip
-most of this Guide, install the binary rpm(s) and go straight
-to the Config Guide.
-
-<!--
-<p>
-We currently distribute GridSite RPMs for RedHat Linux versions 9 and 7.3
-from our download area at
-<a href="https://www.gridsite.org/download/">
-https://www.gridsite.org/download/</a>
--->
-
-<p>
-<b>RedHat 9, Fedora, RHEL, Scientific Linix</b>:
-This is the simpler case, since the standard release includes a suitable
-version of Apache 2.0: just install the gridsite-...-1.i386.rpm to get the
-various GridSite components.
-
-<p>
-<b>Earlier, eg RedHat 7.3</b>:
-This is more complicated because you must also install a back-ported Apache
-2.0 RPM or build it from source.
-<!--
-We distribute RPMs built on 7.3 aimed at RedHat 7.3
-machines with updates, from our download area. These are built from the
-tar.gz and .spec files distributed by the
-Apache Foundation itself, using the
-<a href="build-apache2.sh">build-apache2.sh</a> script in the GridSite
-/usr/share/doc/gridsite directory. The Apache RPMs install in /usr, and you
-should at least install the httpd and mod_ssl RPMs.
-You must also install the gridsite-...-1.i386.rpm as above.
--->
-
-<p>
-GridSite also depends on shared libraries from libcurl and libxml2, and the
-RPMs distributed as part of the standard RedHat, from 7.3 onwards, are
-sufficient.
-
-<p>
-With the RPMs installed, you can proceed to the
-<a href="config.html">Config Guide</a>.
-
-<h2>Requirements for building GridSite from source</h2>
-
-<p>
-GridSite is currently only supported on Linux, but should be
-straightforwardly
-portable to other Unix platforms where the GNU build tools are available.
-
-<p>
-GridSite consists of a core library (libgridsite[.so|.a]), an Apache module
-(mod_gridsite.so), a CGI utility (gridsite-admin.cgi) and some command line
-tools (htcp, urlencode.)
-
-<p>
-All of the components use the GridSite library, and this in turn depends on
-libcurl and libxml2. You will need the development versions of these
-packages installed before you can proceed.
-<!--
-(They are available as part of
-RedHat Linux releases 7.x onwards, for instance.)
--->
-
-<h2>Building GridSite with Make</h2>
-
-<p>
-Our download area at
-<a href="https://www.gridsite.org/download/">
-https://www.gridsite.org/download/</a> includes a tar-ball
-distribution of the sources, which can be unpacked and used to build
-GridSite from source. (Bleeding-edge developers can get the current snapshot
-of the same files from our CVS area.)
-
-<p>
-GridSite needs a copy of the Apache 2.0 include files to build, and the
-location of this is set by the MYCFLAGS variable in the top-level Makefile.
-For manual builds, the default
-<b>MYCFLAGS=-I/usr/local/include/httpd</b> is used.
-If you wish to use the GridSite module with Apache
-2.0 installed elsewhere, you should change the MYCFLAGS variable to point to
-the includes directory installed by the development part of that Apache 2.0
-distribution.
-
-<p>
-<pre>
-make
-make install
-</pre>
-
-<p>
-will build all components and install them all under the default
-locations of /usr/local/[lib|bin|include|sbin] The default prefix for manual
-builds is
-/usr/local, as set by the prefix variable in the top level Makefile
-(/usr is the default for RPMs.)
-
-<h2>Building GridSite with RPM</h2>
-
-<p>
-For RedHat Linux and derivatives, building with RPM is recommended.
-The command <b>make rpm</b> in the top level of the source tree
-will build the GridSite and htcp binary RPMs in the
-directory ../RPMTMP/RPMS/i386 relative to the working directory. An SRPM is
-put into ../RPMTMP/SRPMS
-This build assumes the Apache 2.0 includes are in /usr/include/httpd.
-
-<!--
-<p>
-<b>If you make RPMs on a RedHat 9 system (or a 7.3 system with a 2.0 httpd RPM
-installed), you can install the resulting GridSite
-RPM alongside the standard Apache 2.0 RPM without having to
-modify shared library or Apache module paths.</b>
--->
-
-<p>
-For other configurations,
-you can modify the assumed location of the Apache 2.0 includes
-by changing the MYCFLAGS variable in the rpm target near the
-foot of the top level Makefile.
-
-<h2>Building Apache 2.0</h2>
-
-<p>
-If it is not possible to use binary RPMs of Apache 2.0,
-then it can be built from source using the build-apache2.sh script
-found in the GridSite docs directory.
-The script includes instructions on how to build from the tarballs
-distributed by the Apache Foundation.
-(it removes the -C option from "configure -C" in the .spec file
-and builds the RPMs under the current directory.)
-
-<p>
-If these targets do not work on your build platform,
-the Makefile and the scriptlets in the included SPEC files are a good
-starting point for building Apache by hand yourself. The complexities of
-this are outside of the scope of this Guide, but you are welcome to ask for
-assistance on the
-<a href="http://www.gridsite.org/discuss.html">GridSite
-Discussion List</a>, although
-<a href="http://www.apache.org/">www.apache.org</a> is a better starting
-point for purely Apache problems.
-
-</body>
+++ /dev/null
-library docs
--- /dev/null
+.TH MOD_GRIDSITE 8 "October 2005" "mod_gridsite" "GridSite Manual"
+.SH NAME
+.B mod_gridsite
+\- Grid extensions to Apache httpd
+.SH SYNOPSIS
+.B LoadModule gridsite_module mod_gridsite.so
+.SH DESCRIPTION
+.B 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.
+
+.SH DIRECTIVES
+
+.IP "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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "GridSiteHeadFile file"
+.IP "GridSiteFootFile file"
+Set the filenames to be searched for as standard headers and footers
+for HTML pages. 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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "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>
+
+.IP "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)
+
+.IP "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)
+
+.IP "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)
+
+.IP "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.
+(Default: GridSiteEditable txt shtml html htm css js php jsp)
+
+.IP "GridSiteHelpURI uri"
+If set, gives the URI to use for "Website Help" links in HTML
+page footers. (Default: none)
+
+.IP "GridSiteLink on|off"
+Turns off the link in the HTML page footers which gives credit to GridSite.
+(Default: GridSiteLink on)
+
+.IP "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)
+
+.IP "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)
+
+.IP "GridSiteOnetimesDir path"
+Location of authentication cookies directory, relative to ServerRoot.
+Used by GridHTTP to record the credentials obtained via HTTPS,
+and available to the corresponding HTTP request. (Default: /var/www/onetimes)
+
+.IP "GridSiteACLFormat GACL|XACML"
+Format to use when writing .gacl files. (Both formats are automatically
+recognised when reading.) (Default: GACL)
+
+.IP "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
+.BR "gsexec(8)"
+for an explanation of the different execution strategies.
+(Default: nosetuid)
+
+.IP "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)
+
+.IP "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)
+
+.SH ENVIRONMENT
+
+The following variables are present in the environment of CGI programs and
+other dynamic content systems if the
+.BR "GridSiteEnvs on"
+directive is in effect.
+
+.IP 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.)
+
+.IP GRST_ADMIN_LIST
+URI of the DN List, listing people with full admin and write access
+to the whole site.
+
+.IP GRST_GSIPROXY_LIMIT
+Maximum valid delegation level for GSI Proxies.
+
+.IP GRST_DIR_PATH
+Absolute path in the local filesystem to the directory holding the
+file being requested.
+
+.IP GRST_DESTINATION_TRANSLATED
+Present if a WebDAV
+.BR "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.
+
+.IP GRST_HELP_URI
+URI of website help pages set by GridSiteHelpURI directive.
+
+.IP 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.)
+
+.IP GRST_EDITABLE
+Space-separated list of extensions which can safely be edited with a
+Text/HTML editor.
+
+.IP "GRST_HEAD_FILE and GRST_FOOT_FILE"
+Filenames of standard header and footer files.
+
+.IP GRST_DN_LISTS
+DN lists search path.
+
+.IP GRST_DN_LISTS_URI
+Directory of virtual URIs used to publish this site's DN Lists.
+
+.IP GRST_UNZIP
+Full path to the
+.BR "unzip(1)"
+binary, used to list and unpack .zip files.
+
+.IP GRST_NO_LINK
+If set, do not include credit links to GridSite in page footers.
+
+.IP GRST_ACL_FORMAT
+Format to use when writing .gacl files: either GACL or XACML.
+
+.IP GRST_EXEC_METHOD
+Specified by
+.BR GridSiteExecMethod
+either suexec, X509DN or directory.
+
+.IP 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.)
+
+.IP GRST_DISK_MODE
+The
+.BR 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.)
+
+.SH AUTHOR
+Andrew McNab <Andrew.McNab@manchester.ac.uk>
+
+mod_gridsite is part of GridSite: http://www.gridsite.org/
+.SH "SEE ALSO"
+.BR htcp(1),
+.BR httpd(8),
+.BR gsexec(8)
+++ /dev/null
-<title>GridSite Apache module: mod_gridsite</title>
-<body>
-<h1 align=center>GridSite Apache module: mod_gridsite</h1>
-
-<p>
-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.
-
-<p>
-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.
-
-<p>
-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:
-
-<p>
-<b>LoadModule gridsite_module /PATH/TO/MODULES/mod_gridsite.so</b>
-
-<p>
-The module's behaviour is then controlled by GridSite... directives within
-Apache <Directory ...> sections, allowing different directories to use
-GridSite features in different ways.
-
-<h2>GridSite directives</h2>
-
-<dl>
-<dt><b>GridSiteIndexes on|off</b>
-<dd>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.
- <br>
- (Default: GridSiteIndexes off)
-<p>
-
-<dt><b>GridSiteIndexHeader file</b>
-<dd>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.)
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteHtmlFormat on|off</b>
-<dd>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.
- <br>
- (Default: GridSiteHtmlFormat off)
-<p>
-
-<dt><b>GridSiteHeadFile file</b><br>
- <b>GridSiteFootFile file</b>
-<dd>Set the filenames to be searched for as standard headers and footers
- for HTML pages. 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.)
- <br>
- (Defaults: GridSiteHeadFile gridsitehead.txt,
- GridSiteFootFile gridsitefoot.txt)
-<p>
-
-<dt><b>GridSiteAuth on|off</b>
-<dd>Enables GridSite access control features, using
- <a href="gacl.html">GACL</a> 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.
- <br>
- (Default: GridSiteAuth off)
-<p>
-
-<dt><b>GridSiteAdminList uri</b>
-<dd>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.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteGSIProxyLimit limit</b>
-<dd>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.
- <br>
- (Default: GridSiteGSIProxyLimit 1)
-<p>
-
-<dt><b>GridSiteMethods [GET] [PUT] [DELETE]</b>
-<dd>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.
- <br>
- (Default: GridSite GET)
-<p>
-
-<dt><b>GridSiteDNlists directory1[:directory2[:directory3]...]</b>
-<dd>Sets up the DN List path used by <a href="gacl.html">GACL</a> 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.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteDNlistsURI uri</b>
-<dd>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.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteAdminURI uri</b>
-<dd>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:
- <br>
- <b>ScriptAlias /real-gridsite-admin.cgi
- /PATH/TO/real-gridsite-admin.cgi</b>
- <br>
- This URI is always reached by an internal redirection from the value
- set by GridSiteAdminFile, and is never visible to users.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteAdminFile cgifilename</b>
-<dd>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.
- <br>
- (Default: GridSiteAdminFile gridsite-admin.cgi)
-<p>
-
-<dt><b>GridSiteEnvs on|off</b>
-<dd>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.
- <br>
- (Default: GridSiteEnvs on)
-<p>
-
-<dt><b>GridSiteEditable [ext1 [ext2 [ext3] ...]]]</b>
-<dd>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.
- <br>
- (Default: GridSiteEditable txt shtml html htm css js php jsp)
-<p>
-
-<dt><b>GridSiteHelpURI uri</b>
-<dd>If set, gives the URI to use for "Website Help" links in HTML
- page footers.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteLink on|off</b>
-<dd>Turns off the link in the HTML page footers which gives credit to
- GridSite.
- <br>
- (Default: GridSiteLink on)
-<p>
-
-<dt><b>GridSiteUnzip path</b>
-<dd>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
- <a href="http://www.info-zip.org/UnZip.html">unzip</a> binary.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteDowngrade on|off</b>
-<dd>Enable HTTPS Downgrade for this server, virtual server or directory:
- HTTPS requests made with the header HTTP-Downgrade-Size:
- will be redirected to an HTTP version of the file, unless the file is
- smaller than the given size.
- <br>
- (Default: off)
-<p>
-
-<dt><b>GridSiteAuthCookiesDir path</b>
-<dd>Location of authentication cookies directory, relative to ServerRoot.
- Used by HTTPS Downgrade to record the credentials obtained via HTTPS,
- and available to the corresponding HTTP request.
- <br>
- (Default: gridauthcookies)
-<p>
-
-<dt><b>GridSiteACLFormat GACL|XACML</b>
-<dd>Format to use when writing .gacl files. (Both formats are automatically
- recognised when reading.)
- <br>
- (Default: GACL)
-<p>
-
-<dt><b>GridSiteExecMethod nosetuid|suexec|X509DN|directory</b>
-<dd>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.
- <br>
- With X509DN, the CGI process runs as a pool user, detemined using lock
- files in the pool mapping directory chosen as build time of gsexec.
- (/var/www/execmapdir by default.) The pool user is chosen according
- to the client's full certificate X.509 DN (ie without any GSI proxy
- name components.)
- <br>
- With directory, the CGI process runs as a pool user chosen according
- to the directory in which the CGI is located: all CGIs in that directory
- run as the same pool user.
- <br>
- (Default: nosetuid)
-<p>
-
-<dt><b>GridSiteUserGroup user group</b>
-<dd>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.
- <br>
- (Default: none)
-<p>
-
-<dt><b>GridSiteDiskMode GroupNone|GroupRead|GroupWrite WorldNone|WorldRead</b>
-<dd>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.
- <br>
- (Default: GroupNone WorldNone)
-<p>
-
-</dl>
-
-<h2>Environment variables</h2>
-
-<p>
-The following variables are present in the environment of CGI programs and
-other dynamic content systems if the <b>GridSiteEnvs on</b> directive is
-in effect.
-
-<p>
-<dl>
-<dt><b>GRST_PERM</b>
-<dd>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.)
-<p>
-
-<dt><b>GRST_ADMIN_LIST</b>
-<dd>URI of the DN List, listing people with full admin and write access
- to the whole site.
-<p>
-
-<dt><b>GRST_GSIPROXY_LIMIT</b>
-<dd>Maximum valid delegation level for GSI Proxies.
-<p>
-
-<dt><b>GRST_DIR_PATH</b>
-<dd>Absolute path in the local filesystem to the directory holding the
- file being requested.
-<p>
-
-<dt><b>GRST_DESTINATION_TRANSLATED</b>
-<dd>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.
-<p>
-
-<dt><b>GRST_HELP_URI</b>
-<dd>URI of website help pages set by GridSiteHelpURI directive.
-<p>
-
-<dt><b>GRST_ADMIN_FILE</b>
-<dd>Filename of per-directory ghost gridsite-admin.cgi program. (This is
- used by real-gridsite-admin.cgi to construct links in its pages.)
-<p>
-
-<dt><b>GRST_EDITABLE</b>
-<dd>Space-separated list of extensions which can safely be edited with a
- Text/HTML editor.
-<p>
-
-<dt><b>GRST_HEAD_FILE</b> and <b>GRST_FOOT_FILE</b>
-<dd>Filenames of standard header and footer files.
-<p>
-
-<dt><b>GRST_DN_LISTS</b>
-<dd>DN lists search path.
-<p>
-
-<dt><b>GRST_DN_LISTS_URI</b>
-<dd>Directory of virtual URIs used to publish this site's DN Lists.
-<p>
-
-<dt><b>GRST_UNZIP</b>
-<dd>Full path to the unzip binary, used to list and unpack .zip files.
-<p>
-
-<dt><b>GRST_NO_LINK</b>
-<dd>If set, do not include credit links to GridSite in page footers.
-<p>
-
-<dt><b>GRST_ACL_FORMAT</b>
-<dd>Format to use when writing .gacl files: either GACL or XACML.
-<p>
-
-<dt><b>GRST_EXEC_METHOD</b>
-<dd>Specified by GridSiteExecMethod, either suexec, X509DN or directory.
-<p>
-
-<dt><b>GRST_EXEC_DIRECTORY</b>
-<dd>The directory containing the CGI script or executable (used by gsexec
- to determine which pool account to use in directory mapping mode.)
-<p>
-
-<dt><b>GRST_DISK_MODE</b>
-<dd>The <b>Apache</b> 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.)
-<p>
-
-</dl>
-
-</body>
-.TH urlencode 1 "November 2003" "urlencode" "URLENCODE Manual"
+.TH URLENCODE 1 "November 2003" "urlencode" "GridSite Manual"
.SH NAME
.B urlencode
\- convert strings to or from URL-encoded form
.SH EXIT CODES
0 is always returned.
-.SH BUGS
-Not enough beta testing (hint hint...)
-
.SH AUTHOR
-Andrew McNab <Andrew.McNab@man.ac.uk>
+Andrew McNab <Andrew.McNab@manchester.ac.uk>
urlencode is part of GridSite: http://www.gridsite.org/
+++ /dev/null
-<title>GridSite User Guide</title>
-<body>
-<h1 align=center>GridSite User Guide</h1>
-
-<p><i>If you are setting up a GridSite-based website you may wish to use this
-file as the basis of your end-user documentation. If so, copy all of the
-files from the GridSite doc directory (probably
-<small>/usr/share/doc/gridsite-VERSION/</small>)
-to somewhere on your website like
-<b>/gridsite-doc/</b> and add <b>GridSiteHelpURI /gridsite-doc/user.html</b>
-to the virtual server configuration in
-httpd.conf - you should also look through the rest of the HTML source since
-there are some comments you may find helpful.</i>
-
-<p>
-This Guide is intended for people using GridSite websites with conventional
-web browsers, especially people with write access to areas of the site.
- There is a separate
-<a href="admin.html">Administration Guide</a>
- with additional information for people managing access control and group
-membership. This Guide assumes you are familiar with basic Web and HTML
-concepts. Towards the end we discuss how to access servers with command
-line tools like curl and htcp.
-
-<h2>Reading from HTTP and HTTPS servers</h2>
-
-<p>
-GridSite servers are usually accessible both via HTTP and via HTTPS. You can
-always tell which version you are using by looking at whether the URL in your
-browser's location window starts with "http://" or
-"https://" HTTPS means that the connection to the server is
-encrypted, that you can verify you're talking to the real server and not an
-imposter, and gives you the option to authenticate to the site and perhaps
-gain write access.
-
-<p>
- Simple browsing of the website via HTTP or HTTPS is reasonably
- self-explanatory. If configured, additional links may appear in the footer
- of each webpage with links to this help,
-<!-- if GridSiteHelpURI uri is set -->
- and to switch between HTTP and HTTPS versions of the page. Pages may also
- have a link to the page History,
-<!-- GridSiteAdminURI uri must be set and gridsite-admin.cgi working for
- the history-viewing mechanism to work -->
- showing the dates of changes to that page and names of its authors.
-
-<p>
- When looking at HTTPS pages, you may find your browser reports it cannot
- verify the server's certificate since it does not recognise the
- Certification Authority (CA) it uses. You should attempt to load the CA's
- root certificate into your browser to stop these warnings. (This means your
- browser will be able to identify any servers using fake certificates which
- you shouldn't trust.) How you obtain the CA Root Certificate from a
- trust-worthy source depends on the CA. For example, the UK e-Science CA
- lets you download it <a href="http://ca.grid-support.ac.uk/">from their
- website</a>.
-<!-- if most of your users use one or two CAs, you could add a link to their
-CA root cert loading instructions here -->
-
-<h2>Authenticating</h2>
-
-<p>
- To go beyond reading pages you need to obtain a user certificate and load it
- into your web browser. How you do this again depends on the Certification
- Authority you have access to (for most Grid projects, CAs are organised
- on a national basis.) To use the UK e-Science CA example again,
- <a href="http://ca.grid-support.ac.uk/">from their website</a> has links to
- the procedure for applying for a certificate from within a web browser.
-<!-- again, a link to your CA would be good here -->
-
-<p>
-A user certificate usually has a version of your name and affiliation as its
-Distinguished Name (DN) - for example,
-"/C=UK/O=eScience/OU=Manchester/L=HEP/CN=Andrew McNab"
-
-<p>
-Once you've obtained a user certificate in your name from your CA, you need
-to make sure it is loaded into the browser you normally use to browse the
-web. How you do this is different for different browsers and to some extent
-for different CAs (but if you applied
-for the CA through your browser, you may already have it there.)
-
-<p>
-Browsers want the certificate and private key in the PKCS#12 format, which
-is normally a single file with the extension ".p12".
-Many programs which are based on OpenSSL, such as Globus and curl, prefer
-the PEM (".pem") format for certificates, with separate
-certificate and key files ("usercert.pem" and
-"userkey.pem", for example.) If you only have the files in .pem
-format and have access to openssl, you
-can use its command line tools to convert PEM to PKCS#12:
-<pre>
-openssl pkcs12 -in usercert.pem -inkey userkey.pem -export -out certkey.p12
-</pre>
-
-<p>
-<b>Be very careful not to accidentally overwrite .pem or .p12 files when
-doing this kind of thing! In particular, if you lose your private key, you
-cannot retrieve it from your CA.</b>
-
-<p>
- Once your user certificate is loaded, you should be able to see your
- certificate name appear when you look at an HTTPS GridSite page which has
- the page footers enabled - for example, the "Switch to HTTP" link
- present. If GridSite understands your user certificate, it displays a
- "You are ..." line in the footer. (However, the Apache webserver
- must also be set up with your CAs root certificate for this to work. The
- <a href="https://www.gridpp.ac.uk/">GridPP HTTPS home page</a> is set up
- to recognise a good range of European and North American Grid CAs.)
-<!-- the CA root certificates normally go somewhere like
-/etc/grid-security/certificates and httpd.conf should reflect this with the
-directive SSLCACertificatePath /etc/grid-security/certificates -->
-
-<h2>Authorization</h2>
-
-<p>
- Once users can prove their identity to the web server, it then becomes
- possible to give them appropriate rights depending on that identity.
- GridSite allows site administrators to specify these rights for individuals
- and groups using
-<a href="gacl.html">GACL</a>
- access control files. (The
-<a href="admin.html">Administration Guide</a>
- explains how to manage these files.) GACL defines who can
- read files, who can list directories,
- who can write or create files and who can modify the GACL policy files. To
- get increased access to an area of a site, you need to contact the
- administrator for that area and give the DN of your certificate (it's not
- necessary to send any certificate files.)
-
-<h2>Managing Directories and Files</h2>
-
-<p>
-If you have list permission for the directory containing a page, you should
-see an extra link "Manage Directory" in the page's set of footer
-links, which allows you to browse the directory even if the normal
-index.html is present. If page histories are available, this listing view
-also has links to them.
-
-<p>
-The real power of GridSite becomes available if you have write access to a
-directory. In that case, the "Manage Directory" page has
-additional links to Delete or Rename pages and other files, and to Edit HTML
-and plain text files. An Edit link also appears in the footer links of HTML
-pages.
-
-<p>
-If you use the Edit function, you are presented with an HTML form containing
-the current filename and the full HTML or plain text of the page for you to
-edit. This allows you to maintain the content of the site "in
-place" and to see the result of your changes immediately, in context.
-
-<p>
-If you modify the filename in the form before saving, GridSite will make a
-new file with that name, and the old file will still be present, unmodified.
-(However, you cannot use this feature for creating a file in a different
-directory.)
-As you make changes, the history of the changes and your certificate DN are
-recorded, and available in the history page for that file.
-
-<p>
- For people with write access, the "Manage Directory" page also has
- options to upload a file from the computer your browser is running on, and to
- create files and directories. If it's enabled, you can also view the
- contents of WinZIP / PKZIP / .zip files, and unpack their contents into the
- current directory. (This feature is very useful if you have several files
- to upload at one time.)
-<!-- This needs the GridSiteUnzip path directive in httpd.conf -->
-
-<h2>HTML Formatting in GridSite</h2>
-
-<p>
-As well as providing access control and file management, GridSite provides
-some simple formatting of HTML pages by adding standard headers and footers.
-(If this isn't sufficient, GridSite will happily coexist with HTML
-preprocessor languages like SSI, PHP and JSP.)
-
-<p>
- If HTML formatting is enabled
- for the current directory, GridSite looks for the files gridsitehead.txt and
- gridsitefoot.txt in that directory, or goes up through the parent
- directories until they are found.
-<!-- GridSiteHtmlFormat on turns this on and GridSiteHeadFile file and
-GridSiteFootFile file can change the names of the header and footer. If
-you change from the defaults, you need to change this paragraph. -->
-
-<p>
-The <body> and </body> tags from the HTML file are replaced with
-the contents of the gridsitehead.txt and gridsitefoot.txt files, which
-should normally be chunks of HTML including a replacement <body>
-or </body> tag. If either tag is absent from the original page, then
-the header or footer is just added rather than being inserted in place of
-the tag. (One consequence of this absence is that HTML header tags like
-<title> can end up after a <body> tag, and can get ignored by
-browsers - so always include <body> ... </body> in your pages.)
-
-<p>
-This simple system is suprisingly flexible, and allows a variety of top and
-bottom, or sidebar navigation layouts of pages. Since the <body ...>
-tag is under full control of the author of the gridsitehead.txt file,
-backgrounds, colour schemes and style sheets can easily be specified.
-
-<p>
-For example:
-
-<p>
-<table border=1 cellpadding=3>
-<tr><th>Source</th><th>HTML</th></tr>
-<tr><td>page.html</td><td><title>PAGE TITLE</title></td></tr>
-<tr><td>page.html<br>(replaced)</td><td><body></td></tr>
-<tr><td>gridsitehead.txt</td>
- <td><body text=blue><br>
- Heading text<br>
- <table border=1><br><tr><br><td>Standard<br><br>
- sidebar</td><br><td></td></tr>
-<tr><td>page.html</td><td><p><br>Page content...</td></tr>
-<tr><td>page.html<br>(replaced)</td><td></body></td></tr>
-<tr><td>gridsitefoot.txt</td><td></td><br></tr><br>
- </table><br>Footer text<br></body></td></tr>
-</table>
-
-<p>
-produces pages with a layout like:
-
-<p>
-<table border=1 cellpadding=3>
-<tr><td colspan=2>Heading text</td></tr>
-<tr><td>Standard<br>sidebar</td><td>Page content...</td><tr>
-<tr><td colspan=2>Footer text</td></tr>
-</table>
-
-<h2>Command line use</h2>
-
-<p>
-GridSite adds support for the HTTP PUT and DELETE methods, and this makes it
-easy to create or delete files from within programs and commands without
-using a web browser and HTML forms. It is straightforward, although slightly
-awkward, to use a standard HTTPS-aware client like
-<a href="http://curl.haxx.se/">curl</a> to upload files, but GridSite
-provides htcp as a more convenient client program, which is easier to use
-with GSI Proxies and X.509 user certificates, and has a syntax closer to the
-familiar scp command.
-
-<p>
-The following examples assume the GridSite server has GSI support and use a
-GSI proxy as the client certificate. For non-GSI use, just skip the
-grid-proxy-init stage, and replace the proxy
-filename with $HOME/.globus/usercert.pem and $HOME/.globus/userkey.pem (or
-wherever your PEM format certificate and key are stored.)
-
-<p>
-First generate a GSI proxy with grid-proxy-init. This will create a proxy file
-in /tmp/x509up_uXXXXX where XXXXX is your Unix UID (also given by <b>id
--u</b>.) The GSI proxy contains a
-temporary private key and certificate signed by your long-term user
-certificate.
-
-<p>
-You should make sure you have a copy of the CA root certificates of the CA's
-used by the servers you wish to talk to. These are usually installed in
-/etc/grid-security/certificates as files like 01621954.0, and RPMs and tar
-files for many common European and North American CAs are available from
-<a href="https://datagrid.in2p3.fr/distribution/datagrid/security/">
-https://datagrid.in2p3.fr/distribution/datagrid/security/</a>
-
-<p>
-To upload a file with curl:
-<pre>
-curl --cert /tmp/x509up_u`id -n` --key /tmp/x509up_u`id -n` \
- --capath /etc/grid-security/certificates \
- --upload-file /tmp/new.file.txt https://server/new.file.txt
-</pre>
-
-<p>
-The equivalent htcp command is:
-<pre>
-htcp /tmp/new.file.txt https://server/new.file.txt
-</pre>
-since htcp looks for the GSI proxy and CA certificates automatically. htcp
-can also be used to copy remote files to the local machine by reversing the
-arguments. For more details, see the
-<a href="htcp.1.html">htcp(1)</a> man page.
-
-<p>
-htcp also has options for deleting files, and doing short or long listings,
-and these can also be accessed using the htrm, htls and htll commands (which
-are normally symbolic links to htcp.)
-
-<p>
-Directory indexes are based on parsing the index returned by the web server
-and by using the HTTP HEAD method to obtain the file size and modification
-times.
-
-<p>
-All of the ht** commands can accept multiple source file arguments, and this
-allows you to copy multiple files to or from the server. Shell wildcard
-expansion on the local machine is especially useful:
-<pre>
-htcp /tmp/new.*.txt https://server/
-</pre>
-
-</body>
# Build
#
-build: libgridsite.so.$(VERSION) libgridsite.a htcp mod_gridsite.so \
+build: apidoc \
+ libgridsite.so.$(VERSION) libgridsite.a htcp mod_gridsite.so \
urlencode findproxyfile real-gridsite-admin.cgi gsexec \
# gridsite-delegation.cgi # htproxyput
apidoc:
doxygen Doxyfile
+ mkdir -p ../doc/doxygen
+ cp -f doxygen/*.html doxygen/*.css doxygen/*.png ../doc/doxygen
+ cd ../doc ; for i in *.1 *.8 ; do ../src/roffit < $$i \
+ > $$i.html ; done
gaclexample: gaclexample.c libgridsite.a
gcc -g -o gaclexample gaclexample.c -I. -L. \
$(prefix)/lib/libgridsite_globus.so.$(MAJOR_VERSION)
ln -sf libgridsite_globus.so.$(PATCH_VERSION) \
$(prefix)/lib/libgridsite_globus.so.$(MINOR_VERSION)
- cp -f doxygen/index.html \
- $(prefix)/share/doc/gridsite-$(PATCH_VERSION)/doxygen-index.html
- cp -f doxygen/* $(prefix)/share/doc/gridsite-$(PATCH_VERSION)
cp -f ../CHANGES ../README ../INSTALL ../LICENSE ../VERSION \
$(prefix)/share/doc/gridsite-$(PATCH_VERSION)
cp -f ../doc/*.html ../doc/*.conf ../doc/*.1 ../doc/*.8 ../doc/*.sh \
cp -f ../doc/*.8 $(prefix)/share/man/man8
gzip -f $(prefix)/share/man/man1/*.1
gzip -f $(prefix)/share/man/man8/*.8
- cd ../doc ; for i in *.1 *.8 ; do ../src/roffit < $$i \
- > $(prefix)/share/doc/gridsite-$(VERSION)/$$i.html ; done
cp -f htcp $(prefix)/bin
ln -sf htcp $(prefix)/bin/htls
ln -sf htcp $(prefix)/bin/htll
git://scientific.zcu.cz / jra1mw.git / commitdiff