Please read this entire README file before continuing with the build and installation process. Assumptions: ============ 1. PBS is already installed on all the relevant systems. 2. Secure Shell (e.g., OpenSSH) is installed on all the relevant systems. 3. You are familiar with how to install, configure, and run Apache. We provide some, but not very much, guidance on Apace below. Apache experts will notice that we gloss over a number of details. Requirements: ============= You will need the following software packages (which can be automatically downloaded for you by the included script build_single_acct): 1. Apache HTTP Server - available from http://httpd.apache.org. We use version 1.3.20. For example (or use a mirror site): http://httpd.apache.org/dist/httpd/apache_1.3.20.tar.gz 2. PHP Hypertext Preprocessor - available from http://www.php.net. We use version 4.0.6. For example (or use a mirror site): http://www.php.net/do_download.php?download_file=php-4.0.6.tar.gz&source_site=www.php.net 3. PostgreSQL Relational DBMS - available from http://www.postgresql.org. We use version 7.1.2. For example (or use a mirror site): ftp://looking-glass.usask.ca/pub/postgresql/source/v7.1.2/postgresql-7.1.2.tar.gz The following software packages are optional, but *highly* *highly* recommended: 4. OpenSSL Toolkit - available from http://www.openssl.org. We use version 0.9.6a. For example (or use a mirror site): http://www.openssl.org/source/openssl-0.9.6a.tar.gz 5. modSSL Apache Module - available from http://www.modssl.org. We use version 2.8.4 for Apache 1.3.20. For example (or use a mirror site): http://www.modssl.org/source/mod_ssl-2.8.4-1.3.20.tar.gz In addition, you will need 1 - 2 accounts on 1 - 2 machines. One account controls the Apache HTTP Server, the other controls the PostgreSQL server. NOTE: The Apache HTTP Server can be run under the same account as the PostgreSQL server. In this case, you only need one account on one machine. This is how we are set up. ------------------------------------------------------------------------ NOTE: *Before* you run build_single_acct, you must edit it and set certain configuration variables. See the script itself for in-line documentation. Script "build_single_acct" (included with this distribution) automates steps 1 to 16 of the following Installation process. The script is not particularly robust, so if it fails, you need to follow our instructions by-hand. You can run the script directly or type "make build". Installation: ============= 1. Unpack PostgreSQL. E.g. tar xvzf postgresql-7.1.2.tar.gz 2. Install PostgreSQL on one of the two accounts. Configure PostgreSQL with the following options: --prefix=$HOME/pgsql --with-perl --with-tcl I assume that $HOME is set to the account's home directory (aka ~). Run gmake, followed by gmake install to complete the installation. E.g. cd postgresql-7.1.2 ./configure --prefix=$HOME/pgsql --with-perl --with-tcl gmake gmake install 3. Initialize the PostgreSQL database folder by doing the following: $HOME/pgsql/bin/initdb -D $HOME/pgsql/data 4. OPTIONAL: Install the PostgreSQL documentation with: cd $HOME/pgsql/doc;gmake install Now add the equivalent of export MANPATH=$MANPATH:/usr/brule6/misc/pbsweb/pgsql/man to your shell .*rc file. 5. Unpack OpenSSL, if you're going to use it. E.g. tar xvzf openssl-0.9.6a.tar.gz cd openssl-0.9.6a 6. Install OpenSSL, if you choose to use it. Execute the following commands in the OpenSSL directory: ./config --prefix=$HOME/openssl E.g., ./config --prefix=~/PBSWebInstall/openssl make make test make install 7. Unpack Apache. 8. Unpack modSSL (optional). 9. Apply the mod_ssl patch to Apache. Run the following from the mod_ssl dir: ./configure --with-apache=../apachedir where apachedir is the directory that the apache package is in (e.g., apache_1.3.20) 10. Pre-configure Apache for PHP. Do this by executing the following in the apache directory: ./configure --prefix=$HOME/apache 11. Unpack PHP. 12. Compile and install PHP by doing the following from the PHP directory: CFLAGS='-O2 -I$HOME/openssl/include' \ ./configure --prefix=$HOME/php \ --with-apache=../apachedir \ --with-pgsql=$HOME/pgsql \ --with-config-file-path=$HOME/php/lib \ --without-mysql \ --enable-memory-limit=yes \ --enable-debug=no \ --enable-force-cgi-redirect --enable-discard-path \ --enable-trans-sid make make install 13. Move the php.ini-dist file from the PHP package directory to $HOME/php/lib/php.ini, and edit it to change the following: session.use_cookies = 1 to session.use_cookies = 0 session.cache_limiter = nocache to session.cache_limiter = NOTE: There is nothing following the = in the previous line. 14. Create temporary certificates (optional). Follow the instructions found at http://www.thawte.com/certs/server/keygen/mod_ssl.html 15. Move the generated keys into $HOME/PrivateKeys/machine_name, where machine_name is the name of the machine where Apache will be running. 16. Compile and install Apache by doing the following in the Apache directory: SSL_BASE=$HOME/openssl \ ./configure \ --prefix=$HOME/apache \ --enable-module=ssl \ --activate-module=src/modules/php4/libphp4.a \ --enable-module=php4 make make certificate TYPE=existing \ CRT=$HOME/PrivateKeys/lamont/lamont.cs.ualberta.ca.crt \ KEY=$HOME/PrivateKeys/lamont/lamont.cs.ualberta.ca.key make install Only use --enable-module=ssl and make certificate if you are using SSL. ---- end of steps done automatically by script build_single_acct ---- 17. Modify the Apache httpd.conf file as follows: ** This is basic Apache systems admin and configuration. You will need to draw upon your own preferences and experiences in this matter. - Look in $HOME/apache/conf/httpd.conf - change the port numbers as desired. It defaults to port 8080 for HTTP and port 8443 for HTTPS - Modify "User" and "Group" as appropriate, if you want Apache to su to a different user id - change User nobody to User username, where username is the name of the account under which Apache will be run. - change Group daemon to Group group, group being what is expected. - by default, the Makefile will symbolically link $HOME/apache/htdocs/PBSWeb/ to $HOME/PBSWebExport. You may point Apache to a different directory, if you wish. For example: - change DocumentRoot "$HOME/apache/htdocs" to "$HOME/thisdir", where thisdir is the directory of the PBSWeb src. - change to "$HOME/thisdir" - change a second DocumentRoot found in the virtual host settings as above. If you are not using SSL, ignore this one. - ***VERY IMPORTANT*** Uncomment the following lines: AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps ** After editing createdb.psql, Steps 18 to 21 can be automatically ** executed by typing "make setupdb" 18. If PostgreSQL is run on a different machine than Apache, you will need to allow access to the Apache machine by modifying the pg_hba.conf file in $HOME/pgsql/data. If PostgreSQL is to be running on the same machine, then proceed to step 19. 19. Fire up PostgreSQL by: $HOME/pgsql/bin/postmaster -i -D $HOME/pgsql/data >log_file 2>&1 & Paul note to self: pgsql/bin/postmaster -i -D pgsql/data > log_file 20. Create the pbsweb_release database by $HOME/pgsql/bin/createdb pbsweb_release Aside: You can delete a database with, for example: $HOME/pgsql/bin/dropdb pbsweb_release 21. Edit file createdb.psql (look for comments MODIFY ME) For example, change the line: 1. \connect - paullu to use your own Unix ID 2. User information at the end of the file - one entry per PBSWeb user - see the in-line comments 3. Host information at the end of the file - one entry per host running PBS - see the in-line comments Populate the pbsweb_release database by $HOME/pgsql/bin/psql -d pbsweb_release -f createdb.psql Edit this file for more instructions on how to modify it for your site. 22. Use $HOME/pgsql/bin/psql -d pbsweb_release to add users to the system and to otherwise inspect or change the database. See the PostgreSQL documentation for further details. For example, to print users: select * from users; Add a user "paullu": insert into "users" (name, password, email, rights, deleted) values ('paullu', 'XXXXX','paullu@cs.ualberta.ca','0','0'); 23. Modify the $HOME/pgsql/data/pg_hba.conf file to allow database access from the account that will run Apache. If the database and Apache accounts are the same, you do not need to make any modifications. 24. Fire up apache by: $HOME/apache/bin/apachectl start or apachectl startssl. If you use "startssl" you will be prompted for your passphrase from Step 14 above. 25. Modify the dbutils.php script globals section to reflect your username, password, and machine name of the account under which you are running the database. 26. Modify the PBSWebConstants.php script to reflect the correct paths to upload and copy directories. These directories must also be created in the account that will run Apache. For example, $PBSWEBDIR="pbsweb"; $DEFAULTHOST="aurora.nic.ualberta.ca"; $TEMPUPLOADDIR="/usr/brule6/misc/pbsweb/upload"; are the values we use at the U of Alberta. You will have to find appropriate local values for your site. 27. Access the system via, for example,: http://:8080/PBSWeb/ without SSL https://:8443/PBSWeb/ with SSL Of course, if you changed the port number in $HOME/apache/conf/httpd.conf, then the above URLs will be different too. ------------------------------------------------------------------------ Local Configuration You will likely need to modify the PHP scripts in order for PBSWeb to run correctly at your site. Aside from the modifications listed in steps 24 and 25 above, you will find machine-specific code in the submitscript.php script. The else handles the most common cases, but specific handling of a machine or queue may be required. ------------------------------------------------------------------------ Adding a User to use PBSWeb: 1. Add user to database. See Step 22 (above) and the comments within file createdb.psql. Below, we assume the new user has Unix id "newuser". For example, within psql, do: insert into "users" (name, password, email, rights, deleted) values ('newuser', 'XXXXX','newuser@emailaddr','0','0'); 2. Create an upload directory for the new user in directory pointed to by $TEMPUPLOADDIR in file PBSWebConstants.php For example, mkdir -p $TEMPUPLOADDIR/newuser 3. Have the new user add the identity.pub file of the username running the PBSWeb/Apache server to their ~newuser/.ssh/authorized_keys (this is for SSH Protocol 1.0). We have not tried using SSH Protocol 2.0 For example, if Unix id "paullu" is running the PBSWeb/Apache server, then the new user must add paullu's identity.pub to ~newuser/.ssh/authorized_keys. See the papers in Papers/ for more details. 4. The new user must create a directory (or symbolic link) in their home directory to the path specified by $PBSWEBDIR (in PBSWebConstants.php). This directory must be created on each host to be controlled using PBSWeb. For example, mkdir -p ~newuser/$PBSWEBDIR on every host. For example, directory ~paullu/pbsweb/ exists on both MACI machines, aurora.nic.ualberta.ca and maci-cluster.ucalgary.ca. ------------------------------------------------------------------------ Other Notes: 1. The Help function is not operational.