User, Admin and Installation Guide

for GridSite version 0.2.1

Andrew McNab <[email protected]> 7 February 2002

Most of the sections of this document are still in skeleton form, although I have tried to include key hard-to-find and hard-to-guess information.

Introduction

This document describes how to use, administer and install the GridSite website management system.

GridSite allows the collaborative authoring of websites, with authentification provided by the X509 certificates commonly used by Grid projects.

This Guide consists of three parts, each of which assumes you are familiar with the concepts introduced in previous sections: first, the features seen by users are described; then the steps administrator's need to take to provide those features; and then the process required to install GridSite and make the necessary tools available to administrators.

The homepage of GridSite is http://www.gridpp.ac.uk/gridsite/ and has more information, including source and binary distributions, and details of the gridsite-discuss and gridsite-announce mailing lists.

User Guide

http vs https.

There are usually two versions of a GridSite website: http (normal) and https (secure.) For example, http://www.gridpp.ac.uk/ and https://www.gridpp.ac.uk/ You can easily switch between the two versions using the "Switch to HTTP(S)" in link in the page footers of GridSite pages.

When using the secure version, starting with https://, your browser will attempt to verify that the server's host certificate matches the domain name in its URL. If your browser is configured correctly, this offers strong protection against malicious impersonation of the server, and means you can trust software, certificates etc you subsequently download from it.

If you have a recognised user certificate loaded into your web browser, the secure version will allow you to authenticate with the server, and possibly gain access to restricted areas, write pages, and carry out administration tasks (depending on the permissions you have been granted.)

For your browser to be able to verify the server's host certificate, you should obtain the public root certificate of your Certificate Authority (CA). This file is usually available from your CA's website as a .cacert or .pem file. If their webserver is suitably configured, following a link to the certificate will load it into your web browser directly. For example, this link https://www.gridpp.ac.uk/ca/0ed6468a.cacert will load the root UK HEP CA certificate into recent versions of Netscape or Internet Explorer. (If a link like this is available for your CA, then you can procede directly to the next subsection of this guide after using it to install the certificate.)

Root certificates are also often included in distributions of Grid software (eg the EDG TB1 distribution RPM's include the root certificate files for many European CA's: http://datagrid.in2p3.fr/distribution/data/security/)

If you were not able to load the root certificate directly from a web server or you obtained it another way, you should load it through your browser's security options:

For Internet Explorer: go to Tools | Internet Options | Content | Certificates | Trusted Root Certificate Authorities | Import, and then load the cacert or pem file with the resulting file browser.

It doesn't appear to be possible to do this with Netscape. In this case, you should make sure the certificate is available from a webserver, which reports its MIME type as application/x-x509-ca-cert

Converting user certificates to pkcs12

To load PEM format (Globus-style) user certificates into Netscape or Internet Explorer, you first need to convert them into pkcs#12 format. This is most easily done with openssl version 0.9.3 or later.

If you have used your certificate with Globus, the conversion is most easily done on the machine with the .globus directory where your working Globus certificates are stored. (You can run grid-proxy-init to check they are installed correctly if you are in any doubt.)

That machine must have openssl installed for the following procedure to work. If you are using Redhat Linux 7.x then you have probably got openssl installed already. Typing openssl version will verify it is installed and tell you what version. (For Redhat 6.x, you can download a suitable OpenSSL RPM from http://datagrid.in2p3.fr/distribution/external/)

Once you have a working installation of openssl, you need to check that the certificate you have is valid for use in a web browser, by issuing the command: openssl x509 -in usercert.pem -text

The output should include these lines (possibly with the SSL Server and S/MIME references absent):

Netscape Cert Type: 
   SSL Client, SSL Server, S/MIME

If SSL Client is missing, you will need to have your certificate reissued by your certificate authority, with the additional Cert Type "SSL Client"

Once you have an SSL-Client valid certificate, generate a pkcs12 version of your certificate and key by issuing the following command (NB the .p12 file includes a copy of your private key from userkey.pem, protected by the passphrase you are prompted for. You should treat the .p12 file with the same care as your userkey.pem private key.)

openssl pkcs12 \
 -export -in ~/.globus/usercert.pem \
         -inkey ~/.globus/userkey.pem \
         -out ~/.globus/uskycert.p12

The resulting file uskycert.p12 can then be loaded into Netscape or Internet Explorer, either on the Unix machine with your .globus directory or by copying the file to a Windows machine and loading it there.

For Netscape: Communicator | Tools | Security Info | Certificates | Yours | Import a Certificate

For Internet Explorer: Tools | Internet Options | Content | Certificates | ?Personal? | Import

Once you have the Personal Certificate loaded, you should be able to see your DN displayed on the secure (https) version of your GridSite website. Go to the main page of your site and look for your Certificate DN (eg "/O=Grid/O=UKHEP/OU=hep.man.ac.uk/CN=Andrew McNab") in the page footer.

The first time you use your user certificate each session, you will be prompted for the passphrase you gave when you loaded it into your browser (this may not be the same passphrase as your PEM encoded key.) This prevents other people from using your credentials if they have physical access to your machine and can start your browser when you are not present. Your browser may repeatedly prompt for which user certificate to use. This can be disabled with the "choose certificate automatically" and "do not prompt me again" options.

Accessing Protected Pages

GridSite controls access to pages and files using per-directory Access Control Lists (ACL's.) These specify which groups of users may read or write to a directory, or who can in turn modify the directory's ACL.

If you have been given read access to a private area of a GridSite website, then it is sufficient that you have loaded your certificate into your browser by following the instructions above.

Members and Groups

You can find a list of all the members of the website using the "List All Members" page. By default this is located at /website/members/. To be added to groups, you must first be listed on that page as a member of the website.

You can find a list of the groups defined for your website using the "List All Groups" page. By default, this is located at /website/groups/ on the server, and there is a link to it from the footer of the "List All Members" page.

Follow the link to a group's name to get a list of all the people in that group. Individuals listed as having admin access to the group are able to add members to that group, and should be contacted with any requests to join.

Each member of the website also has a member page, with a URL based on their certificate DN. For example, with certificate DN "/O=Grid/O=UKHEP/OU=hep.man.ac.uk/CN=Andrew McNab" the corresponding member page URL is http://www.gridpp.ac.uk/website/members/O=Grid/O=UKHEP/OU=hep.man.ac.uk/CN=Andrew%20McNab

If authenticated, the user can modify the personal details listed on their page, such as email address and homepage URL. (By default, these details can also be modified by administrators in the group with webadmin - these are likely to be people involved with the administration of the website itself; and by the administrator in the addmembers group that added you to the website initially - this is likely to be the administrator of your local organisation or working group.)

Creating and Editing pages

Once you have authenticated with the website, and become a member of the appropriate groups, you will be able to create and edit pages in any directories your groups have write access to.

If you have greater access to a directory than just read, pages will now include extra links in the footer of each page.

List allows you to get a listing of all files in the current directory, including images, ppt talks etc. Each file's size and modification time are shown, along with a link to its History page which shows who modifed the file in the past. (View History also appears as a link in the footer of HTML webpages.)

The next section of the listing shows which groups have specified access levels for this directory. Each level also grants the privileges associated with lower access levels. The levels are, in increasing order: read - the group can read files in this directory; list - the group can also see a listing of the directory; write - the group can create, edit and upload files and make new subdirectories with the parent's ACL inherited as the default; admin - the group can modify the ACL for this directory, add or remove groups or change their access level.

If your group has write or admin access to the directory, the listing will also show forms to create new webpages, subdirectories and upload files from the machine on which your browser is running. From links embedded in the listing, you can also edit or delete files. (An Edit link also appears as a link in the footer of HTML webpages if you have write access to their directory.)

Edit allows you to edit the page you are currently looking at: it takes you to a form including the page text and the filename. You can use this to edit the current page or use it as a template for a new page and save it with a new name.

HTML Page Format

HTML pages uploaded or written on the website are not displayed in their raw form, as they would be with most webservers. Instead, the system replaces the <BODY> and </BODY> tags with a standard page header and a footer containing links to information and management pages. (NB if no BODY tags are present, the header and footer material will be placed at the start and end of the file, and any title tags will fail to work properly.)

The header and footer are taken from the files gridsitehead.txt and gridsitefoot.txt in the same directory as the HTML file; if they are absent, parent directories are searched in turn, up to the root directory of the whole website. (This means versions of these files can be shared by sub-hierarchies of the website without having to place a copy of them in every directory.) If the header or footer file is completely absent, a plain <body> or </body> tag is used respectively.

The footer also contains sections provided by GridSite itself, which contains the date of the page's last modification, and links to its History log, and links to management pages which are appropriate to the viewer's access level for the current directory.

Other than the above, the system imposes no requirements on web page authors. This means it should be possible to author pages using plain text editors, specialised HTML editors, MS FrontPage and To-HTML conversion programs (eg from MS Word) as long as the pages our created with BODY tags.

Admin Guide

Adding members to the system

If you are a member of the webadmin or addmembers group, you can use the form at the foot of the "List all website members" page (by default at /website/members/) to add new members: just put their certificate DN in the box and click Add. Once they've been added, you can fill in additional details about them.

Adding members to groups

Do this from the member's page: a pull down list of groups to which you can add them appears (depending on the groups they are not in and the groups you have admin access to.)

Creating new groups

If you are in the webadmin group, you can create new groups using the box at the bottom of the "List all groups" page (by default at /website/groups/)

Installation Guide

This assumes you are familiar with the website use and administration concepts described in the the previous sections. (Please check back if necessary.)

If you need to build from source, just do make in the GridSite source directory. However, it should almost always be possible to get what you want using the binary distribution.

To make use of the certificate-based authentification features of GridSite, you must configure your web server's SSL support. (For Apache, this is normally done with the mod_ssl module's options.) Before trying to get GridSite working, you should verify that you can see https:// URL's on your server.

Some Apache/mod_ssl directives to check:

SSLEngine on
SSLCertificateFile /etc/httpd/conf/ssl.crt/www.crt
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/www.key
SSLCertificateChainFile /etc/httpd/conf/ssl.crt/ca.crt
SSLCACertificateFile /etc/httpd/conf/ssl.crt/ca.crt
SSLVerifyClient optional
SSLVerifyDepth 10
SSLOptions +ExportCertData +CompatEnvVars +StdEnvVars

Configuration

Copy the nph-gridsite.cgi executable to somewhere secure like the default RPM cgi installation location: /var/www/cgi-bin/nph-gridsite.cgi (You MUST retain nph- at the start of the filename.) If the web pages are to be owned by the web server account, then nph-gridsite.cgi just needs to have world execute permission. However, if the pages are to be owned by another user, then you should change the ownership of nph-gridsite.cgi to that user and set its setuid bit: chmod u+s nph-gridsite.cgi

Add a line like ScriptAliasMatch ^/.* /var/www/cgi-bin/nph-gridsite.cgi to the correct virtual server section in /etc/httpd/conf/httpd.conf and, if not already present, a Directory entry like:

<Directory "/var/www/cgi-bin">
 AllowOverride None
 Options ExecCGI   
 Order allow,deny  
 Allow from all    
</Directory>

Any MIME types you want GridSite to be able to handle must be included in /etc/mime.types Most common ones will already be there, but you will need to add any Grid or application specific ones. Some examples:

text/plain                    txt    # plain text file
text/html                     html   # HTML page
text/css                      css    # (HTML) Cascading Style Sheet
application/postscript        ps     # Postscript
application/pdf               pdf    # Portable Document Format
#
text/plain                    pem    # PEM encoded certificates etc
application/x-x509-ca-cert    cacert # CA root certificate
#
application/x-tar             tar    # tar archive
application/x-tar-gz          tgz    # gzip compressed tar archive
application/x-gzip            gz     # gzip compressed file
application/x-rpm             rpm    # RedHat Linux package
text/plain                    spec   # RPM specification (source) file 
#
application/vnd.ms-powerpoint ppt    # MS Powerpoint presentation
application/msword            doc    # MS Word document
application/vnd.ms-excel      xls    # MS Excel spreadsheet
#
image/gif                     gif    # GIF 256-colour image (icons etc)
image/jpeg                    jpg    # JPEG photograph
image/png                     png    # Portable Network Graphics file

In httpd.conf make sure DocumentRoot is correctly set to the directory where your pages will be stored. You should now restart the webserver to make the changes take effect. (With RedHat Linux, you can do this with /etc/rc.d/init.d/httpd restart)

If DocumentRoot is $DOCROOT, then create the two etc directories: $DOCROOT/../etc/members and $DOCROOT/../etc/groups To start adding members and groups, you must first create one administration user which is a member of the webadmin group, by creating files in those directories.

First, create an empty file in ./etc/members with your URL-encoded certificate DN: each character in the DN which is not A-Z a-z 0-9 . = - must be replaced by % followed by its ASCII value in hexadecimal (using a-f not A-F.) The command line tool urlencode supplied with GridSite will do this conversion for you. For example: urlencode "/O=Grid/O=UKHEP/OU=hep.man.ac.uk/CN=Andrew McNab"

Next create a file in ./etc/groups consiting of one line: the word admin, followed by a single space, then your DN (not urlencoded and not surrounded by quotes.) For example:

admin /O=Grid/O=UKHEP/OU=hep.man.ac.uk/CN=Andrew McNab

You should now be able to see yourself listed on https://yourservername/website/members/ and carry out the tasks described in the Administration and User sections of this Guide to add more groups, users, pages and directories.

If this does not work - in particular if you do not see the "You are ..." line in the footer - then you should double check the previous steps, in particular the certificate chain configuration necessary for mod_ssl to verify user certificates.