Config Guide
From GridSiteWiki
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 Administration 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.
| Table of contents |
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 1.1.x also includes some commands and man pages in /usr/bin and /usr/share/man/man1 (urlencode, htcp and other ht* commands.)
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 with GridSite, in the doc directory.
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.
