UPGRADE

This file explains how to upgrade an existing install of Apache VCL 2.2 or 2.2.1
to Apache VCL 2.2.2. It assumed that you extracted the release archive
to /root/apache-VCL-2.2.2

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.2.2-upgrade.sql

3. Update mysql schema (2.2 -> 2.2.2 only)

This step updates the mysql schema.

   cd /root/apache-VCL-2.2.2
   mysql vcl < mysql/update-vcl.sql

4. Grant CREATE TEMPORARY TABLES to mysql user (2.2 -> 2.2.2 only)

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 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. copy your old code out of the way

      cd /var/www/html
      mv vcl ~/vcl-pre2.2.2_web

   b. copy the new code in place

      cd /root/apache-VCL-2.2.2
      cp -r web /var/www/html/vcl

   c. copy your config files from the previous version:

      cd ~/vcl-pre2.2.2_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 
      user - normally this is the 'apache' user

      chown apache /var/www/html/vcl/.ht-inc/maintenance

   e. make changes to conf.php: (2.2 -> 2.2.2 only)

      A new user group permission that controls who can manage block allocations
      globally or for a specific affiliation has been added. It can be granted
      to any user group under Privileges->Additional User Permissions->Manage
      Block Allocations. Users with this permission are notified of new block
      allocation requests. Remove the following from conf.php.

         $blockNotifyUsers

      A new user group permission that controls who can look up users globally
      or for a specific affiliation has been added. It can be granted to any
      user group under Privileges->Additional User Permissions->User Lookup.
      Users with this permission can look up information about other users.
      Remove the following from conf.php.

         $userlookupUsers


6. Restart httpd service

   service httpd start

7. Update management node code

This step will make a backup copy of the existing code 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 <your vcl MN code root path>
      ie. cd /usr/local/
      cp -r vcl ~/vcl-pre2.2.2_managementnode

   b. Copy in the 2.2.2 code base to /usr/local, copying in should preserve any
      drivers or other files you've added.

      /bin/cp -r /root/apache-VCL-2.2.2/managementnode/* /usr/local/vcl

   c. Run install_perl_libs.pl to add any new perl library requirements:

      /usr/local/vcl/bin/install_perl_libs.pl

8. Restart vcld service

   service vcld start