2018-10-03 Fred Gleason <fredg@paravelsystems.com>

* Updated 'UPGRADING' to include information for v3.x.
	* Updated 'INSTALL'.

UPGRADING

@@ -1,25 +1,25 @@
 IMPORTANT NOTE: BE SURE TO SEE THE SECTION ON 'PASSWORD STORAGE' BELOW,
 OTHERWISE YOU MAY BE LOCKED OUT OF THE SYSTEM AFTER THE UPDATE!
 
-This file provides some notes to those performing an upgrade from a v1.x
-version to Rivendell.  It is an attempt to provide some pointers about things
-which have changed, but is in no way a substitute for reading the 'INSTALL' 
-file and other documentation!
+This file provides some notes to those performing an upgrade from a v1.x or
+v2.x version of Rivendell. It is an attempt to provide some pointers about
+things which have changed, but is in no way a substitute for reading the
+'INSTALL' file and other documentation!
 
 1) DEPENDENCIES
 The set of external packages required to build and run Rivendell has changed
-significantly from that required for a 1.x system.  See 'INSTALL' for a full
-list.
+significantly from that required for a 1.x or 2.x system. See 'INSTALL' for
+a full list.
 
 2) MPEG SUPPORT
-This version of Rivendell inaugurates optional support for MPEG Layer 2 
+This version of Rivendell includes optional support for MPEG Layer 2 
 encoding within the core Rivendell audio library for all classes of audio 
-device (JACK and ALSA as well as AudioScience HPI).  To make use of this 
+device (JACK and ALSA as well as AudioScience HPI). To make use of this 
 feature, it will be necessary to have the appropriate MPEG libraries 
-properly installed at both build- and run-time.  See 'INSTALL' for the 
+properly installed at both build- and run-time. See 'INSTALL' for the 
 specifics.
 
-3) FILE OWNERSHIP AND PERMISSIONS
+3) FILE OWNERSHIP AND PERMISSIONS (v1.x only)
 Recommended file ownership and permissions for the '/var/snd' directory and 
 its contents have changed.  These items should be owned by system user and 
 group accounts created specifically for Rivendell; no 'real' user on the 
@@ -32,25 +32,25 @@ should have read, write set for user and group and just read for others (0664).
 
 4) WEB SERVICES
 This version of Rivendell makes use of a web services protocol to accomplish
-many functions (audio import, export, ripping, etc).  These services require
+many functions (audio import, export, ripping, etc). These services require
 that a CGI-compliant web server be installed and active on the system.  
 Any server that complies with CGI-1.1 should work, although as of this writing
-only Apache 2.2 has been well tested.  A configuration file snippet for Apache
+only Apache 2.2 has been well tested. A configuration file snippet for Apache
 that will configure the target web services directory (set by the
 '--libexecdir=' switch passed to './configure') correctly is generated 
 automatically as part of the build process; it can be found in
 'conf/rd-bin.conf' after the build is complete.
 
-5) PASSWORD STORAGE
-The method of storing passwords in the database has changed in Rivendell 2.x,
-requiring that all non-null passwords be reset after performing the upgrade.
-This means that it is important that the account used to access RDAdmin be set
-to use a null (blank) password *before* applying the update, otherwise you
-will not be able to access RDAdmin afterwards!  Once the update has been
-applied, passwords should be re-entered for all user accounts in RDAdmin
-(including administrative ones) in the usual manner.
+5) PASSWORD STORAGE (v1.x only)
+The method of storing passwords in the database has changed in Rivendell 2.x
+and 3.x, requiring that all non-null passwords be reset after performing the
+upgrade. This means that it is important that the account used to access
+RDAdmin be set to use a null (blank) password *before* applying the update,
+otherwise you will not be able to access RDAdmin afterwards!  Once the update
+has been applied, passwords should be re-entered for all user accounts in
+RDAdmin (including administrative ones) in the usual manner.
 
-6) AUDIO SAMPLE RATE
+6) AUDIO SAMPLE RATE (v1.x only)
 The sample rate to be used for the Rivendell audio library is now a single
 system-wide setting (found in RDAdmin->SystemSettings); it is no longer
 possible to set sample rates individually per module/workstation.  When 
@@ -67,8 +67,51 @@ the target file, respectively.
 
 The 'smb:' protocol is no longer supported.
 
-8) RLM API CHANGES
+8) RLM API CHANGES (V1.x only)
 The parameters passed to the RLMPadDataSent() callback in RLMs have changed;
 private plug-ins written for RD 1.x will need to be modified to work with the
 new API.  (All plug-ins supplied with the Rivendell sources have already been
 modified appropriately.)
+
+9) DATABASE CHARACTER SET CONVERSION
+Databases generated using Rivendell v1.x or v2.x used the 'latin1' character
+set. Such databases must be converted to use the 'utf8mb4' character set
+before they can be properly utilized by Rivendell 3.x. To perform this
+conversion, proceed as follows:
+
+BEFORE UPDATING
+---------------
+A) Make a full and complete backup of the database, using either rdadmin(1)
+or the MySQL mysqldump(1) utility. Don't skip this!
+
+B) Use the rddbcheck(8) tool to verify the consistency of the database.
+Be sure to fix any problems found *before* upgrading the Rivendell binaries!
+
+AFTER UPDATING
+--------------
+C) Check the '[mySQL]' section of '/etc/rd.conf' and verify that the
+following parameters are set:
+
+[mySQL]
+Charset=utf8mb4
+Collation=utf8mb4_general_ci
+
+(There will likely be additional parameters present in the '[mySQL]'
+section; these can be left unchanged).
+
+D) Update the DB schema using the rddbmgr(8) command:
+
+   rddbmgr --modify
+
+If all goes well, the command should exit without printing anything.
+
+E) Convert the DB character set using the rddbmgr(8) command:
+
+   rddbmgr --check --yes
+
+You should see a list of DB tables generated as each one is converted. 
+
+At this point, you should be ready to start the Rivendell service, by doing:
+
+   systemctl restart rivendell
+