From: Andrew McNab Date: Tue, 4 Oct 2005 11:04:52 +0000 (+0000) Subject: Reorganise docs X-Git-Tag: gridsite-core_R_1_1_12~27 X-Git-Url: http://scientific.zcu.cz/git/?a=commitdiff_plain;h=c16869f44847f682789261808cd1372225f4cb2a;p=jra1mw.git Reorganise docs --- diff --git a/org.gridsite.core/CHANGES b/org.gridsite.core/CHANGES index 02f6df6..c3e9507 100644 --- a/org.gridsite.core/CHANGES +++ b/org.gridsite.core/CHANGES @@ -1,3 +1,8 @@ +* Tue Oct 4 2005 Andrew McNab +- 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 - Fix to gsexec GRST_CRED_0/SSL_CLIENT_S_DN bug found by Ian Stokes-Rees diff --git a/org.gridsite.core/INSTALL b/org.gridsite.core/INSTALL index 3da6cde..4943047 100644 --- a/org.gridsite.core/INSTALL +++ b/org.gridsite.core/INSTALL @@ -1,10 +1,8 @@ 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 diff --git a/org.gridsite.core/README b/org.gridsite.core/README index 62730a6..784ee81 100644 --- a/org.gridsite.core/README +++ b/org.gridsite.core/README @@ -1,3 +1,5 @@ -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. diff --git a/org.gridsite.core/doc/admin.html b/org.gridsite.core/doc/admin.html deleted file mode 100644 index 1f7f422..0000000 --- a/org.gridsite.core/doc/admin.html +++ /dev/null @@ -1,103 +0,0 @@ -GridSite Admin Guide - -

GridSite Admin Guide

- -

-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. - -

- There is a separate -User Guide - 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. - -

- You may also find the -Config Guide - 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. - -

Groups and DN Lists

- -

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

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

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

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

Access Control Lists

- -

-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. - -

-The GridSite GACL Reference 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. - -

-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. - -

-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. - -

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

-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.) - - diff --git a/org.gridsite.core/doc/config.html b/org.gridsite.core/doc/config.html deleted file mode 100644 index 8c3811c..0000000 --- a/org.gridsite.core/doc/config.html +++ /dev/null @@ -1,195 +0,0 @@ -GridSite Config Guide - -

GridSite Config Guide

- -

-This Guide is intended for webmasters setting up -GridSite with an Apache 2.0 -webserver. We assume you have root access to the server machine to do this. -There is a separate Admin Guide 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. - -

Installation

- -

-We assume you have installed Apache 2.0 and GridSite, using the -Building and Installation Guide 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. - -

-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. - -

-GridSite also includes some commands and man pages in /usr/bin and -/usr/share/man/man1: urlencode and -htcp. - -

Certificates

- -

-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 -EU Grid PMA. - -

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

-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 UK e-Science -CA) 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 not /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. - -

-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: -

-openssl pkcs12 -in ck.p12 -clcerts -nokeys -out hostcert.pem
-openssl pkcs12 -in ck.p12 -nodes  -nocerts -out hostkey.pem
-
- -

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

-chown root.root hostkey.pem hostcert.pem
-chmod 400 hostkey.pem
-chmod 444 hostcert.pem
-
- -

httpd.conf

- -

-/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. - -

-The easiest way to get started is to examine the example httpd.conf files we -provide. - -

-Please note: this version of GridSite is not compatible with the -SHM SSL session cache - use the DBM or per-process caches instead. - - - -

httpd-fileserver.conf

- -

-httpd-fileserver.conf 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. - -

httpd-webserver.conf

- -

-httpd-webserver.conf 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. - -

GridSite Directives

- -

-The mod_gridsite reference lists all the GridSite -httpd.conf directives. - -

-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: - -

-GridSiteMethods GET PUT DELETE - -

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

GACL access control

- -

-The GACL reference 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. - -

-For example, to give all clients read and list permission: -

-

-<gacl>
-<entry>
-  <any-user/>
-  <allow><read/><list/></allow>
-</entry>
-</gacl>
-
- -

-To enable writing, add DN List, Person or VOMS entries to the file. -For example: - -

-

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

-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. - - - - diff --git a/org.gridsite.core/doc/findproxyfile.1 b/org.gridsite.core/doc/findproxyfile.1 index 9814d08..9de4d47 100644 --- a/org.gridsite.core/doc/findproxyfile.1 +++ b/org.gridsite.core/doc/findproxyfile.1 @@ -1,4 +1,4 @@ -.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 diff --git a/org.gridsite.core/doc/gacl.html b/org.gridsite.core/doc/gacl.html deleted file mode 100644 index 82be605..0000000 --- a/org.gridsite.core/doc/gacl.html +++ /dev/null @@ -1,84 +0,0 @@ -GridSite: Grid Access Control Language - -

GridSite: Grid Access Control Language

- -

-GACL is the authorization policy language used by -GridSite 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. - -

-GridSite both uses GACL policies and provides a GACL manipulation API for -C/C++ in the GridSite library. - -

Credentials

- -

-In GridSite 1.1.x, four credential types are supported: - -

-<person> -<dn>/O=Grid/CN=Name</dn> -</person> - -

-<voms> -<fqan>/vo.dom.ain/group</fqan> -</voms> - -

-<dn-list> -<url>https://www.vo.dom.ain/dn-lists/group</url> -</dn-list> - -

-<dns> -<hostname>host*.dom.ain</hostname> -</dns> - -

Permissions

- -

-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. - -

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

-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>. - -

Entries

- -

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

Access Control Lists

- -

-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.) - - diff --git a/org.gridsite.core/doc/gsexec.8 b/org.gridsite.core/doc/gsexec.8 index fbc5a62..e229663 100644 --- a/org.gridsite.core/doc/gsexec.8 +++ b/org.gridsite.core/doc/gsexec.8 @@ -1,56 +1,134 @@ -.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 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) diff --git a/org.gridsite.core/doc/htcp.1 b/org.gridsite.core/doc/htcp.1 index c9e0a23..ef9ef98 100644 --- a/org.gridsite.core/doc/htcp.1 +++ b/org.gridsite.core/doc/htcp.1 @@ -1,4 +1,4 @@ -.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 diff --git a/org.gridsite.core/doc/index.html b/org.gridsite.core/doc/index.html index a93f2cb..d182ead 100644 --- a/org.gridsite.core/doc/index.html +++ b/org.gridsite.core/doc/index.html @@ -11,29 +11,35 @@ the associated verified credentials are available to all technologies supported by Apache, including static file serving, SSI, CGI, PHP, JSP and mod_perl. -

Guides

+

+The GridSite Wiki includes +guides and cookbook examples about using GridSite, along with up to date +information about the APIs. + +

Reference

-

-
User Guide -
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. +

+

-
Admin Guide -
For people administering areas of GridSite websites or fileservers, or - managing GridSite's support for DN List groups. +
htcp(1) +
A command line tool for copying files to or from HTTP(S) servers.

-

Building and Installation -
Instructions for building GridSite from source, and installing from - binaries or RPMs. +
mod_gridsite(8) +
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.

-

Config Guide -
For webmasters setting up Apache 2.0 and GridSite, and writing the - Apache httpd.conf file. +
gsexec(8) +
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.

httpd-fileserver.conf and @@ -42,22 +48,21 @@ mod_perl. webservers, with explanatory comments.

-

- -

Reference

- -

-

-
Grid Access Control Lists -
Syntax and usage of the XML Grid Access Control Lists used by GridSite. +
urlencode(1) +
A command for URL-encoding strings.

-

htcp and - urlencode man pages -
Command line tools for copying files to or from HTTP(S) servers, and - for URL-encoding strings. +
findproxyfile(1) +
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.

+

delegation-1.wsdl +
A WSDL description of a delegation Web Service including the Delegation + portType. +

+ -

mod_gridsite -
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. -

- - - -

gridsite.h API reference +
gridsite.h API reference
A detailed description of the C API provided by libgridsite, generated from the sources by doxygen.

diff --git a/org.gridsite.core/doc/install.html b/org.gridsite.core/doc/install.html deleted file mode 100644 index a5845de..0000000 --- a/org.gridsite.core/doc/install.html +++ /dev/null @@ -1,158 +0,0 @@ -GridSite: Building and Installation Guide - -

GridSite: Building and Installation Guide

- -

-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 Config Guide 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. - -

Installing with RPM

- -

-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. - - - -

-RedHat 9, Fedora, RHEL, Scientific Linix: -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. - -

-Earlier, eg RedHat 7.3: -This is more complicated because you must also install a back-ported Apache -2.0 RPM or build it from source. - - -

-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. - -

-With the RPMs installed, you can proceed to the -Config Guide. - -

Requirements for building GridSite from source

- -

-GridSite is currently only supported on Linux, but should be -straightforwardly -portable to other Unix platforms where the GNU build tools are available. - -

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

-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. - - -

Building GridSite with Make

- -

-Our download area at - -https://www.gridsite.org/download/ 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.) - -

-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 -MYCFLAGS=-I/usr/local/include/httpd 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. - -

-

-make 
-make install
-
- -

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

Building GridSite with RPM

- -

-For RedHat Linux and derivatives, building with RPM is recommended. -The command make rpm 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. - - - -

-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. - -

Building Apache 2.0

- -

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

-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 -GridSite -Discussion List, although -www.apache.org is a better starting -point for purely Apache problems. - - diff --git a/org.gridsite.core/doc/library.html b/org.gridsite.core/doc/library.html deleted file mode 100644 index 28458ae..0000000 --- a/org.gridsite.core/doc/library.html +++ /dev/null @@ -1 +0,0 @@ -library docs diff --git a/org.gridsite.core/doc/mod_gridsite.8 b/org.gridsite.core/doc/mod_gridsite.8 new file mode 100644 index 0000000..f359d7d --- /dev/null +++ b/org.gridsite.core/doc/mod_gridsite.8 @@ -0,0 +1,280 @@ +.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 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 + tags; footer files in place of . (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 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) +

+ +.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 + +mod_gridsite is part of GridSite: http://www.gridsite.org/ +.SH "SEE ALSO" +.BR htcp(1), +.BR httpd(8), +.BR gsexec(8) diff --git a/org.gridsite.core/doc/module.html b/org.gridsite.core/doc/module.html deleted file mode 100644 index f4a3acf..0000000 --- a/org.gridsite.core/doc/module.html +++ /dev/null @@ -1,356 +0,0 @@ -GridSite Apache module: mod_gridsite - -

GridSite Apache module: mod_gridsite

- -

-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. - -

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

- -

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

- -

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

- -

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. -
- (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) -

- -

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 "path" must point - to the location of the - unzip binary. -
- (Default: none) -

- -

GridSiteDowngrade on|off -
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. -
- (Default: off) -

- -

GridSiteAuthCookiesDir path -
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. -
- (Default: gridauthcookies) -

- -

GridSiteACLFormat GACL|XACML -
Format to use when writing .gacl files. (Both formats are automatically - recognised when reading.) -
- (Default: GACL) -

- -

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. -
- 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.) -
- 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. -
- (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) -

- -

- -

Environment variables

- -

-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_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 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.) -

- -

- - diff --git a/org.gridsite.core/doc/urlencode.1 b/org.gridsite.core/doc/urlencode.1 index 7f772cb..7cdfbc3 100644 --- a/org.gridsite.core/doc/urlencode.1 +++ b/org.gridsite.core/doc/urlencode.1 @@ -1,4 +1,4 @@ -.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 @@ -37,10 +37,7 @@ with the exception that + is converted to space. .SH EXIT CODES 0 is always returned. -.SH BUGS -Not enough beta testing (hint hint...) - .SH AUTHOR -Andrew McNab +Andrew McNab urlencode is part of GridSite: http://www.gridsite.org/ diff --git a/org.gridsite.core/doc/user.html b/org.gridsite.core/doc/user.html deleted file mode 100644 index ae37cdd..0000000 --- a/org.gridsite.core/doc/user.html +++ /dev/null @@ -1,302 +0,0 @@ -GridSite User Guide - -

GridSite User Guide

- -

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 -/usr/share/doc/gridsite-VERSION/) -to somewhere on your website like -/gridsite-doc/ and add GridSiteHelpURI /gridsite-doc/user.html -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. - -

-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 -Administration Guide - 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. - -

Reading from HTTP and HTTPS servers

- -

-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. - -

- 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, - - and to switch between HTTP and HTTPS versions of the page. Pages may also - have a link to the page History, - - showing the dates of changes to that page and names of its authors. - -

- 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 from their - website. - - -

Authenticating

- -

- 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, - from their website has links to - the procedure for applying for a certificate from within a web browser. - - -

-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" - -

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

-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: -

-openssl pkcs12 -in usercert.pem -inkey userkey.pem -export -out certkey.p12
-
- -

-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. - -

- 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 - GridPP HTTPS home page is set up - to recognise a good range of European and North American Grid CAs.) - - -

Authorization

- -

- 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 -GACL - access control files. (The -Administration Guide - 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.) - -

Managing Directories and Files

- -

-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. - -

-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. - -

-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. - -

-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. - -

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

HTML Formatting in GridSite

- -

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

- 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. - - -

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

-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. - -

-For example: - -

- - - - - - - - - -
SourceHTML
page.html<title>PAGE TITLE</title>
page.html
(replaced)		<body>
gridsitehead.txt<body text=blue>
- Heading text
- <table border=1>
<tr>
<td>Standard<br>
- sidebar</td>
<td>
page.html<p>
Page content...
page.html
(replaced)		</body>
gridsitefoot.txt</td>
</tr>
- </table>
Footer text
</body>
- -

-produces pages with a layout like: - -

- - - - -
Heading text
Standard
sidebar		Page content...
Footer text
- -

Command line use

- -

-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 -curl 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. - -

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

-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 id --u.) The GSI proxy contains a -temporary private key and certificate signed by your long-term user -certificate. - -

-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 - -https://datagrid.in2p3.fr/distribution/datagrid/security/ - -

-To upload a file with curl: -

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

-The equivalent htcp command is: -

-htcp /tmp/new.file.txt https://server/new.file.txt
-
-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 -htcp(1) man page. - -

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

-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. - -

-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: -

-htcp /tmp/new.*.txt https://server/
-
- - diff --git a/org.gridsite.core/src/Makefile b/org.gridsite.core/src/Makefile index bb72cc9..05349b2 100644 --- a/org.gridsite.core/src/Makefile +++ b/org.gridsite.core/src/Makefile @@ -56,7 +56,8 @@ endif # 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 @@ -196,6 +197,10 @@ showx509exts: showx509exts.c libgridsite.a 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. \ @@ -290,9 +295,6 @@ install: apidoc $(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 \ @@ -301,8 +303,6 @@ install: apidoc 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