Upgrading From v2.2

Upgrading From v2.2

Upgrades from v2.2 are performed by exporting your accounts from v2.2 and importing them into a new v3.x installation.

Prerequisites

  • A working Centova Cast v2.2.6 or v2.2.7 installation from which you want to import accounts
  • A working Centova Cast v3 installation into which you want to import your v2.2 accounts
  • Identical streaming server (SHOUTcast, IceCast, etc.) and streaming source (sc_trans, ices, etc.) software installed and enabled on both your v2 and v3 servers

Centova Cast v2 and v3 may both be installed on the same server, or they may be installed on separate servers; the account export utility supports both scenarios.

Performing the Upgrade

Begin by ensuring that you have met the prerequisites for upgrading; specifically, you must have a separate, working Centova Cast v3 installation before beginning the upgrade. The upgrade procedure will only import your accounts from v2 to v3; it will not convert your Centova Cast v2 installation to v3.

Further, your v2 server must be running Centova Cast v2.2.6 or v2.2.7 -- earlier versions are not compatible with the upgrade utility. If your v2 server is running an earlier version of Centova Cast, it will need to be upgraded to v2.2.7 before beginning the v3 upgrade.

  1. Log in to the server running Centova Cast v2 and execute the following commands to download and invoke the export utility:

    cd /home/centovacast/system
    wget http://foo.example.com:2199/exportv2.tar.gz
    tar xzf exportv2.tar.gz
    cd export22x
    ./export.sh
    

    Replace foo.example.com with the hostname (or IP address) of your Centova Cast v3 installation.

  2. The export utility will prompt you for your Centova Cast v2 and v3 administrator passwords:

    Enter your Centova Cast v2 admin password:
    Enter your Centova Cast v3 admin password:
    

    Enter the password for the admin account on each of your servers.

  3. Next, the utility will inquire as to whether v2 and v3 are on the same or different servers:

    Is your Centova Cast v3 installation on the same server as
    Centova Cast v2, or on a different server?
    
    [S] Same server
    [D] Different server
    
    Choose (S or D):
    

    Press S if you have installed Centova Cast v3 on the same server as Centova Cast v2. Press S if you are using different servers for v2 and v3.

  4. If you have selected S for same server in step 3, skip the next 3 steps which will only appear when D for different server is selected.

    The utility will prompt you for the IP address of your Centova Cast v3 installation:

    Enter the IP address for your Centova Cast v3 web interface:
    

    Enter your Centova Cast v3 IP address.

  5. The utility will prompt you for the port number of your Centova Cast v3 installation:

    Enter the port number for your Centova Cast v3 web interface.
    If in doubt, press enter to use the default (port 2199):
    

    Unless you have deliberately changed this setting by manually editing configuration files on your v3 server, just press ENTER to use the default of 2199.

  6. Next, the utility will prompt you for your SSH port for the Centova Cast v3 server. SSH will be used to securely and efficiently transfer your clients' files from your v2 server to your v3 server.

    If your SSH server on foo.example.com listens on a custom port,
    enter the port number below.  Otherwise, just press enter to use
    the default (port 22).
    

    If your SSH server on your v3 server uses a nonstandard port, enter it here, otherwise just press ENTER.

  7. Finally, the utility will prompt you for the root password for your Centova Cast v3 server. Again, the utility will use this to securely connect to the remote server over SSH to transfer your clients' files.

    Please enter the root password for the remote
    server (foo.example.com) below.
    

    Enter your root password for your Centova Cast v3 server to continue.

After prompting for all of the necessary information (above), the utility will begin exporting your accounts from your Centova Cast v2 database:

BEGINNING ACCOUNT EXPORT
============================================================
Exporting database(s) ...

Creating database dump /home/centovacast/vhosts/_export/abc.ccsql
Creating database dump /home/centovacast/vhosts/_export/def.ccsql
...

If Centova Cast v2 and v3 are on different servers, your clients' files will be efficiently copied to the remote server using rsync (if available) or scp:

Exporting account data via rsync ...

Exporting account abc ...
Exporting account def ...
...

If Centova Cast v2 and v3 are on the same partition on the same server, your clients' files will be hardlinked directly from /home/centovacast/vhosts (on v2) to /usr/local/centovacast/vhosts (on v3). This is much faster than copying them and avoids the consumption of double the disk space.

If Centova Cast v2 and v3 are on different partitions on the same server, cross-partition hardlinks are not possible so your clients' files will be copied from v2 to v3.

Finally, the exported accounts will be imported into Centova Cast v3:

BEGINNING ACCOUNT IMPORT
============================================================
Performing import on Centova Cast v3 server ...

Importing account abc ...
     Successfully imported account abc

Importing account def ...
     Successfully imported account def
...

After each of the accounts are migrated, a completion message will be displayed and the accounts will be ready to use on the new server.

Note that the stream accounts in Centova Cast v2 will NOT be stopped or removed; they will remain intact and running on your Centova Cast v2 server, and your Centova Cast v3 server will now contain exact duplicates of each of them. This is intentional to allow you to test the accounts under v3 before decommissioning them under v2 and activating them under v3.

Upon completion, it is essential that you perform the steps in the next section.

Completing the Upgrade

After the upgrade completes, it is essential that you perform the following steps to verify and complete the transition to Centova Cast v3:

  1. Log in to Centova Cast v3 and check each of your streams to ensure that they were imported correctly.

  2. When you are satisfied that the accounts were migrated successfully to v3, stop just one stream in Centova Cast v2 and start it in Centova Cast v3. Ensure that the stream starts properly and operates correctly.

  3. When you are satisfied that the stream works correctly, stop all of your streams in Centova Cast v2 and start them all in Centova Cast v3. Note that this will interrupt the audio broadcast for each of your streams, and will disconnect all listeners.

  4. Confirm the correct operation of all of your streams in Centova Cast v3. When you are satisfied that the streams were migrated successfully and that everything is working properly under Centova Cast v3, you may (and should) remove Centova Cast v2 from your server.

Advanced Options

Commandline Parameters

The export.sh script accepts a number of commandline parameters to allow for customization and/or automation of the upgrade procedure. The support parameters include:

  • --accounts=username1,username2,...
    Specifies a comma-separated list of username(s) to transfer. Use this if you do not wish to transfer ALL accounts, but only a select few.

  • --skip-accounts=username1,username2,...
    Specifies a comma-separated list of username(s) to ignore.  Use this if you wish to transfer all accounts EXCEPT for a select few.

  • --oldpass=password
    Specifies your Centova Cast v2 administrator (admin account) password.

  • --newpass=password
    Specifies your Centova Cast v3 administrator (admin account) password.

  • --local=1
    Specifies that Centova Cast v2 and v3 are both installed on the same server. (Omit this if Centova Cast v3 is installed on a different, remote server.)

  • --host=foo.example.com
    Specifies the hostname (or IP address) for your Centova Cast v3 server.

  • --port=2199
    Specifies the Centova Cast web interface port number for your Centova Cast v3 server, if you have configured Centova Cast v3 to use a nonstandard port number.

  • --sshport=22
    Specifies the SSH port number for your Centova Cast v3 server, if you have configured your SSH daemon to use a non-standard port.

  • --resume=1
    Specifies that username conflicts should be ignored. Specifically, if a username from the v2 server already exists on the v3 server, the importer will assume you already imported that account on a previous invocation. This is useful if the import job fails for any reason and needs to be restarted (as a username conflict will normally cause the upgrade to abort.)