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

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

ChangeLog

@@ -17740,3 +17740,6 @@
 	* Removed the POSTGRESQL_BUILTIN_DATABASE define from 'lib/rd.h'.
 2018-10-03 Fred Gleason <fredg@paravelsystems.com>
 	* Added a beta test warning to 'README'.
+2018-10-03 Fred Gleason <fredg@paravelsystems.com>
+	* Updated 'UPGRADING' to include information for v3.x.
+	* Updated 'INSTALL'.

INSTALL

@@ -30,7 +30,7 @@ LibSndFile
 An audio file support library, written by Erik de Castro Lopo. Included with
 most distros, or you can find it at http://www.mega-nerd.com/libsndfile/.
 
-mySQL Database Server
+MySQL/MariaDB Database Server
 Included in most Linux distributions. See http://www.mysql.com/.
 
 PAM Pluggable Authentication Modules
@@ -55,6 +55,9 @@ SoundTouch Audio Processing Library
 A library for altering the pitch and/or tempo of digital audio data.
 Available at http://www.surina.net/soundtouch/.
 
+Systemd System and Service Manager
+Most modern Linux distros include this.
+
 X11 Window System
 Virtually all Linux distros should include this.
 
@@ -83,10 +86,6 @@ Free Lossless Audio Codec (FLAC), v1.2.x or greater
 A "lossless" audio encoding library. Included with most distros, or 
 available from: http://flac.sourceforge.net/.
 
-GPIO Driver
-A kernel driver for the line of data-acquisition boards from 
-MeasurementComputing.  See http://www.rivendellaudio.org/.
-
 FAAD2 / mp4v2 - AAC/MP4 Decoding Libraries. Needed for MP4 file importation.
 Available at http://www.audiocoding.com/faad2.html and
 https://code.google.com/p/mp4v2/ respectively.
@@ -208,16 +207,32 @@ This directory should owned, readable, writable and searchable by the user
 and group specified in the 'AudioOwner=' and 'AudioGroup=' entires in
 '/etc/rd.conf' and readable and searchable by Others (mode 0775).
 
-Finally, it's time to start things up.  Run 'rdadmin' from a shell
+Next, create an empty database on the MySQL/MariaDb server, as well as a
-prompt.  For the first time startup, RDAdmin will prompt for a login
+DB user to access it. This user should have the following privileges:
-name/password on the mySQL server so that it can create the Rivendell
-database.  To log into RDAdmin for the first time, enter a User Name of
-'admin' with no password.
 
-Much of the work in Rivendell gets done by three daemon processes,
+       Select
-named 'caed', 'ripcd' and 'rdcatchd'.  These daemons *must* be running
+       Insert
-before attempting to start any of the Rivendell applications.  The
+       Update
-order in which they are started is important, and should be the same
+       Delete
-as the order in which they are listed above.  For convienence, a Sys-V
+       Create
-style init script called 'rivendell' that can start, stop and restart 
+       Drop
-the daemons properly is installed in '/etc/init.d/'.
+       References
+       Index
+       Alter
+       Create Temporary Table
+       Lock Tables
+
+In the '[mySQL]' section of the '/etc/rd.conf' file, set the 'Database=',
+'Loginname=' and 'Password=' parameters to the DB name, user and password
+that you created. Then, create an initial Rivendell database by doing:
+
+     rddbmgr --create
+
+If all goes well, this command should return with no output.
+
+Finally, start up the Rivendell service by doing (as root):
+
+      systemctl start rivendell
+
+You should now be able to run the various Rivendell components from the
+Applications menu.

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
+This file provides some notes to those performing an upgrade from a v1.x or
-version to Rivendell.  It is an attempt to provide some pointers about things
+v2.x version of Rivendell. It is an attempt to provide some pointers about
-which have changed, but is in no way a substitute for reading the 'INSTALL' 
+things which have changed, but is in no way a substitute for reading the
-file and other documentation!
+'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
+significantly from that required for a 1.x or 2.x system. See 'INSTALL' for
-list.
+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 
 feature, it will be necessary to have the appropriate MPEG libraries 
 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 
@@ -41,16 +41,16 @@ that will configure the target web services directory (set by the
 automatically as part of the build process; it can be found in
 'conf/rd-bin.conf' after the build is complete.
 
-5) PASSWORD STORAGE
+5) PASSWORD STORAGE (v1.x only)
-The method of storing passwords in the database has changed in Rivendell 2.x,
+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.
+and 3.x, requiring that all non-null passwords be reset after performing the
-This means that it is important that the account used to access RDAdmin be set
+upgrade. This means that it is important that the account used to access
-to use a null (blank) password *before* applying the update, otherwise you
+RDAdmin be set to use a null (blank) password *before* applying the update,
-will not be able to access RDAdmin afterwards!  Once the update has been
+otherwise you will not be able to access RDAdmin afterwards!  Once the update
-applied, passwords should be re-entered for all user accounts in RDAdmin
+has been applied, passwords should be re-entered for all user accounts in
-(including administrative ones) in the usual manner.
+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
+