This file explains how to upgrade an existing install of Apache VCL to Apache VCL 2.3.1. It assumed that you extracted the release archive to /root/apache-VCL-2.3.1 The basic steps that will be performed: 1. Shutdown httpd and vcld services 2. Create backup of vcl database 3. Update mysql schema 4. Grant CREATE TEMPORARY TABLES to mysql user 5. Update Web code, create a backup, copy in new, make changes 6. Restart httpd service 7. Update Management node vcl code, create a backup, copy in new, make changes 8. Restart vcld service 1. Shutdown httpd and vcld services service httpd stop service vcld stop 2. Create a backup of vcl database We will create a backup of the vcl database. This will provide a restore point if necessary. mysqldump vcl > ~/vcl-pre2.3.1-upgrade.sql 3. Update mysql schema This step updates the mysql schema. cd /root/apache-VCL-2.3.1 mysql vcl < mysql/update-vcl.sql One item of note: In 2.3 a new resource group is added in update-vcl.sql - "all profiles". Access to manage the group is added to the VCL->admin node in the privilege tree if that node exists. If not, you will need to add it manually after starting httpd again (step 6). To add it manually, pick a node in the privilege tree, scroll to Resources, click Add Resource Group, select "serverprofile/all profiles" from the drop-down box, check available, administer, manageGroup, and manageMapping, and click "Submit New Resource Group". 4. FOR UPGRADING from 2.2 ONLY (skip to step 5 if upgrading from 2.2.1 or 2.3) Grant CREATE TEMPORARY TABLES to mysql user The web code now requires access to create temporary tables in mysql. You need to grant the user your web code uses to access mysql the "CREATE TEMPORARY TABLES" permission. Look at the secrets.php file in your web code for the user and hostname. For example, if your web code is installed at /var/www/html/vcl, your secrets.php file would be /var/www/html/vcl/.ht-inc/secrets.php. Look for $vclhost and $vclusername. The secrets.php file might have something like: $vclhost = 'localhost'; $vcluser = 'vcluser'; Then, you need to issue the grant command to mysql. Using the values from above as examples, connect to mysql and then issue the grant command: mysql GRANT CREATE TEMPORARY TABLES ON `vcl`.* TO 'vcluser'@'localhost'; exit 5. Update web code This step we will move the existing web directory out of the way, so we can copy in the new web code base. After copying in the new code, we will migrate your configuration changes. These instructions assume that you installed the vcl web code at /var/www/html/vcl. If you installed it elsewhere, replace /var/www/html/vcl with your vcl web root. a. move your old code out of the way cd /var/www/html mv vcl ~/vcl-pre2.3.1_web b. copy the new code in place cd /root/apache-VCL-2.3.1 cp -r web /var/www/html/vcl c. copy your config files from the previous version: cd ~/vcl-pre2.3.1_web/.ht-inc cp conf.php secrets.php pubkey.pem keys.pem /var/www/html/vcl/.ht-inc d. make /var/www/html/vcl/.ht-inc/maintenance writable by the web server - if httpd on your server is running as the user apache: chown apache /var/www/html/vcl/.ht-inc/maintenance e. update conf.php upgrading from 2.2.1: * add the following defines: define("DEFAULTLOCALE", "en_US"); define("ALLOWADDSHIBUSERS", 0); * remove the following arrays: $blockNotifyUsers - This has been replace by a user group permission that controls who can manage block allocations globally or for a specific affiliation. It can be granted to any user group under Privileges->Additional User Permissions->Manage Block Allocations $userlookupUsers - This has been replace by a user group permission that controls who can look up users globally or for a specific affiliation. It can be granted to any user group under Privileges->Additional User Permissions->User Lookup * Add the following two keys to each entry you have for LDAP authentication in the $authMechs array. Descriptions of the items can be found in the 2.3 conf-default.php file. "lookupuserbeforeauth" => 0, "lookupuserfield" => '', * change the following two lines for local authentication from $addUserFunc[$item['affiliationid']] = create_function('', 'return 0;'); $updateUserFunc[$item['affiliationid']] = create_function('', 'return 0;'); to $addUserFunc[$item['affiliationid']] = create_function('', 'return NULL;'); $updateUserFunc[$item['affiliationid']] = create_function('', 'return NULL;'); * remove the three commented lines toward the bottom that talk about adding an entry to $addUserFund for Shibboleth authenticated affiliations (# any affiliation that is shibboleth...) upgrading from 2.2: * add the following defines: define("DEFAULTLOCALE", "en_US"); define("ALLOWADDSHIBUSERS", 0); * remove the following arrays: $blockNotifyUsers - This has been replace by a user group permission that controls who can manage block allocations globally or for a specific affiliation. It can be granted to any user group under Privileges->Additional User Permissions->Manage Block Allocations $userlookupUsers - This has been replace by a user group permission that controls who can look up users globally or for a specific affiliation. It can be granted to any user group under Privileges->Additional User Permissions->User Lookup * Add the following two keys to each entry you have for LDAP authentication in the $authMechs array. Descriptions of the items can be found in the 2.3 conf-default.php file. "lookupuserbeforeauth" => 0, "lookupuserfield" => '', * Remove all of these arrays: $affilValFunc $affilValFuncArgs $addUserFunc $addUserFuncArgs $updateUserFunc $updateUserFuncArgs * Add the following code: $affilValFunc = array(); $affilValFuncArgs = array(); $addUserFunc = array(); $addUserFuncArgs = array(); $updateUserFunc = array(); $updateUserFuncArgs = array(); foreach($authMechs as $key => $item) { if($item['type'] == 'ldap') { $affilValFunc[$item['affiliationid']] = 'validateLDAPUser'; $affilValFuncArgs[$item['affiliationid']] = $key; $addUserFunc[$item['affiliationid']] = 'addLDAPUser'; $addUserFuncArgs[$item['affiliationid']] = $key; $updateUserFunc[$item['affiliationid']] = 'updateLDAPUser'; $updateUserFuncArgs[$item['affiliationid']] = $key; } elseif($item['type'] == 'local') { $affilValFunc[$item['affiliationid']] = create_function('', 'return 0;'); $addUserFunc[$item['affiliationid']] = create_function('', 'return NULL;'); $updateUserFunc[$item['affiliationid']] = create_function('', 'return NULL;'); } } 6. Restart httpd service service httpd start * Confirm you can access the VCL portal before continuing. 7. Update management node code This step will make a backup copy of the installed vcl code base and then copy the new code over the existing code to preserve any drivers or other files you've added. a. Copy the existing management node code base to a backup location cd ie. cd /usr/local/ cp -r vcl ~/vcl-pre2.3.1_managementnode b. Copy in the 2.3.1 code base to /usr/local, copying in should preserve any drivers or other files you've added. /bin/cp -r /root/apache-VCL-2.3.1/managementnode/* /usr/local/vcl c. Run install_perl_libs.pl to update the perl dependencies (this will take a few minutes.) /usr/local/vcl/bin/install_perl_libs.pl 8. Restart vcld service service vcld start * Check the /var/log/vcld.log file to confirm vcld is working. * Run through a few VCL reservation requests to confirm is it working.