Rivendellaudio/UPGRADING

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 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 or 2.x system. See 'INSTALL' for
a full list.

2) MPEG SUPPORT
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 (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 
system should use these accounts.  The Rivendell system user and group 
accounts are specified in the 'AudioOwner=' and 'AudioGroup=' directives in
the '[Identity]' section of rd.conf(5); see 'conf/rd.conf-sample' for an
example.  Permissions for '/var/snd' should be read, write and execute bits
set for User and Group and read, execute for Others (0775), while the contents
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
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/2.4 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 (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 (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 
updating the schema, Rivendell will default this to the value previously
configured for RDLibrary on a randomly selected host; since this may or may
not be appropriate for your site, checking this value after the update is 
recommended.

7) RDCATCH CHANGES
Upload and Download events in RDCatch that use the 'file:' protocol now 
require that a username/password for an appropriate shell user account be 
entered.  'Appropriate' here means one with write or read permissions for 
the target file, respectively.

The 'smb:' protocol is no longer supported.

8) Now & Next / PAD Updates
The built-in UDP and RLM PAD transmission subsystems found in previous
Rivendell versions have been replaced with a Python 3 based scripting
system known as 'PyPAD'. Documentation for the full API can be found
by entering the following at a Python 3 interactive prompt:

   import pypad
   help(pypad)

A heavily commented sample script can also be found at
'apis/pypad/tests/now_and_next.py' in the source tree.

The following RLMs that were previously shipped with Rivendell 2.x have
been ported to PyPAD:

--------------------------------------------------------------------------
|  RLM Plug-in        |  PyPAD Script       |  Remarks                   |
--------------------------------------------------------------------------
| rlm_ando            | pypad_ando.py       |                            |
| rlm_filewrite       | pypad_filewrite.py  |                            |
| rlm_icecast2        | pypad_icecast2.py   |                            |
| rlm_inno713         | pypad_inno713.py    |                            |
| rlm_liqcomp         | pypad_liqcomp.py    |                            |
| rlm_live365         | pypad_live365.py    |                            |
| rlm_serial          | pypad_serial.py     |                            |
| rlm_shoutcast1      | pypad_shoutcast1.py |                            |
| rlm_spinitroni_plus | pypad_spinitron.py  | Supports Spinitron v2 only |
| rlm_spottrap        | pypad_spottrap.py   |                            |
| rlm_tunein          | pypad_tunein.py     |                            |
| rlm_udp             | pypad_udp.py        |                            |
| rlm_urlwrite        | pypad_urlwrite.py   |                            |
| rlm_walltime        | pypad_walltime.py   |                            |
|                     | pypad_xcmd.py       | New in Rivendell 3.0       |
| rlm_xds             | pypad_xds.py        |                            |
| rlm_xmpad           | pypad_xmpad.py      |                            |
--------------------------------------------------------------------------

With one exception, the configuration files for all of the above RLMs
are forward compatibile with the successor PyPAD script. To apply the
configuration, simply copy/paste the contents of the RLM configuration file
into the Configuration box when creating the PyPAD instance in rdadmin(1).
(See the Operations Guide for information on creating and modifying PyPAD
instances).

The single exception is the 'pypad_spinitron.py' script. Since this script
supports only v2 of the Spinitron API, configuration parameters that apply
only to the v1 API ('MajorVersion=', 'Station=' and 'Password=') are ignored.
With these execptions, the RLM configuration is fully forward compatible.

9) MULTICAST DATA
This version of Rivendell includes a new system for providing real-time
status updates between Rivendell modules by means of multicast network
packets. The default subscription address for these updates is
239.192.255.72 (administratively scoped), but can be customized in
RDAdmin->SystemsSettings if necessary.

This means that all Rivendell hosts sharing a common database must
be able to communicate via the specified multicast group. For typical
installations (stand-alone, or networked with all hosts residing on a
common TCP/IP subnet), this should 'just work', but those sites employing
hosts on disparate TCP/IP networks (multiple subnets, WAN links, etc) may
need to provision an appropriate multicast routing infrastructure.

10) DATABASE MANAGEMENT
This version of Rivendell splits off database management tasks (creating,
updating, backing up and restoration) from rdadmin(1). Simple management
tasks can be done with the rddbconfig(8) GUI utility (available on the
Rivendell->Configuration desktop menu), while advanced functionality is
available in the rddbmgr(8) command-line utility (do 'man 8 rddbmgr' for
full documentation). The functions of the rdrevert(8) and rddbcheck(8)
utilites have also been subsumed into rddbmgr(8).

11) ARTIST SEPARATION
This version of Rivendell moves artist separation in rdlogmanager(1) from
clocks to events. The artist separation value from Rivendell 2.x is still
visible in the EditClock->SchedulerRules dialog but will not be used
by the "Generate Log" scheduler. New artist separation values will have
to be entered into each event.