Skip to main content
Blackboard Help

Cloning Blackboard Learn: Unix


One of a system administrator's primary jobs is to maintain the stability of the system they support. Testing and development environments are the means to facilitate this responsibility. But to get authentic results, it's vitally important to keep your testing environment in sync with your production environment. This is where cloning becomes invaluable. By cloning your production environment to your testing and development environment, you can use the most recent data to test performance and upgrades. This article is a general guide through the cloning process, since every environment has it's own nuances.

Pre-Clone Steps

Replicate Production Infrastructure

To eliminate as many infrastructure question marks as possible, replicate the production server specifications in your development environment. You don't necessarily need as many web servers in your testing and development environment as you have in production, but the specifications of your database (DB), network file system (NFS), load balancer, and web servers should be the same as (or close to) your production servers' specifications. Speak to your server administrator about duplicating the infrastructure. For more information, see the Windows Hardware Sizing Guide or the UNIX Hardware Sizing Guide.

Back Up Current Development Environment

Back up your development environment prior to the clone. This includes web servers. The backups enable you to recover your development environment in the event an issue arises when cloning. Once your clone is successful, retain the backups at your own discretion.

For the database, ask your database administrator to run an RMAN (recovery manager) backup of the database.

For the content share and web servers:

  • Use backup software to backup the data to tape or disk
  • Use the rsync command to copy the data to another server or disk partition
  • Use the tar command (or any other compression tool) to compress the data to an archive file

The size of your content share dictates which method is the most practical.

Find special building blocks with Dev references and keys, and keep/backup that data including SafeAssign info in config="" p="" plugins="">

For the web servers, lessen the size of the logs and backup directories before backing up the server.

  • For the Logs directory, only keep the most recent logs (for a dev environment, you only need a few days' worth of logs). Delete any heap dump files and threaddump files, because they significantly increase the size of your web server backup if they are present.
  • For the backups directory, delete all but the most recent backup file. However, if the most recent file is large,  delete it too. The backups directory is used by Blackboard installers to revert an environment back to it's original state should an upgrade go wrong. It is rare for an administrator to need any file in the backups directory.

If your dev environment is on the same Service Pack (SP) and patch level as your production environment, copy the file to another location. This way, you can simply copy it back after the web server has been cloned and you won't need to edit it.

After the size of the directories has been reduced, backup the web server directories, minus the content share, using the same methods as described here.

Clone Production to Development (Linux/Oracle)

  1. Shutdown the development environment.
  2. Clone the NFS/content share:
    • If using rsync, delete the dev content share, and rsync Prod /usr/local/blackboard/content to Dev /usr/local/blackboard/content.
      For example: run on Dev fileserver: rsync -av --delete --whole-file bbfilesrv0:/storage/content/ /storage/content/
      where bbfilesrv0 is the Prod NFS server.
    • This can be done with Prod still active with normal user work occurring. However, it has a small chance of causing extra load on your environment. Plan the timing accordingly.
      Run a final rsync of the content share after the production environment has been shutdown, and remember the completion time.
    • If using a backup from tape/disk, delete the dev content share, and use your backup software to restore the production content share to the dev location.
    • If using tar (or another compression tool), delete the dev content share, and expand the archive file in it's place.
  3. Shut down the production environment.

Cloning the Database

  • Run a rman full backup of your Oracle production database while production is running so you don't have too much down time of the production system. Keep redo logs from the time when rman full backup is done and the time the rsync of the content share is done.
  • Restore rman backup files from Prod database to Dev database.
  • Roll forward database to /storage file copy completion time as best can be done using the redo logs.

Cloning the Web Servers

  • If you are using backup software to clone the production web servers, backup the /usr/local/blackboard directory, minus the content directory, and restore it onto the development/test server.
  • If using rsync, similar to the content share, rsync the directories from the production /usr/local/blackboard/ directory to the /usr/local/blackboard/ directory on the dev web server(s). See a command example.
  • If using tar or gzip, simply compress the /usr/local/blackboard directory (that you decreased in size and it's subfolders) and put them into an archive file. Copy the file to a web server and uncompress it in the /usr/local directory of the development web server.
    For example: tar cvfz /tmp/BbClone.tgz /usr/local/blackboard

Post-Clone Steps

Edit the file:

  • If your production and dev/test environments are on the same service pack level and you've copied your original file from the dev/test servers prior to copying the production data, this step is easy. Make a backup copy of the cloned file, just to be safe (mv /usr/local/blackboard/config/ /usr/local/blackboard/config/, and copy the dev copy to the now cloned /usr/local/blackboard/config directory (mv /<folder>/ /usr/local/blackboard/config/).
  • If your environments are not on the same service pack level, then you must edit the file manually. See these instructions on how to do so here.

Correct the BbPatch Utility Configuration:

  • After the clone, your BbPatch utility configuration will be incorrect, as it still has production-related information in it. To clear it, you need to reconfigure the utility to recognize your dev/test environment.
  • Go to the /usr/local/blackboard/content/bbpatch/inventory/appservers/ directory. Inside the directory there are several folders named after the FQDN of each of your production servers. Rename the folders after the FQDN of each of your dev/test servers (example: mv Delete any left over with production server names. They are not needed (example: rm -rf *
  • Next, edit the /usr/local/blackboard/system/bbpatch/target.hostname file. Open this file on each of your dev/test servers and make sure that it only has the FQDN of the server you are on. For example, if you are logged into, then the only line in the target_hostname file should be "". Do not put the quotes in the file.
  • To test if the BbPatch utility has been configured correctly, run the command: /usr/local/blackboard/tools/admin/ list. The results should show the same patch level as your production environment. If you encounter an error, confirm the prior steps were completed.

Avoid Building Block Interference:

  • Disable building blocks that have Bb Learn Prod server name or special keys references in them by using blackboard/tools/admin/ to set them to unavailable. See B2Manager script options.
    (if a vxi virtual error occurs when trying to run, you may have to pushconfig and stop Learn to get some linkages set up)


  • Now that the file and the bbpatch utility have been configured, it is time to startup the newly cloned environment.
  • Run the script (located in the /usr/local/blackboard/tools/admin directory) as the root user on the backend server of the cluster. 
    example: [root@server1 /]# cd /usr/local/blackboard/tools/admin
    [root@server1 admin]# ./
  • After the backend server has restarted completely, run the script on the remaining servers in the cluster.

Clean Out Production Settings:

Now that the servers are up and running, the production settings that have been copied down by the clone need to be altered to reflect their new development/test status.

  • Change the Cloud Connector to non-production status.
  • Reconfigure disabled building blocks with Dev server references and keys (set UNAVAILABLE, alter settings, set AVAILABLE).
  • Fix up plugins/config/ (or delete it entirely).
  • Mark all notifications as being done using SQL update listed below. This avoids students from receiving notices from the Dev system.
  • As a safety precaution, you can disable Notifications for the rest of the semester (System Admin – Notifications – Notification Collection disabled).
  • Reinstall any building blocks that were in your dev/test environment prior to the clone that were not in your production environment.

B2Manager Script Options

Usage: B2Manager.{bat,sh} [ -o ] < -i | -r | -s STATUS > < FILENAME | B2HANDLER >
B2Manager.{bat,sh} < -l | -v > [ FILENAME | B2HANDLER ]

-i Install the given building block
-l List all currently installed building blocks (short listing)

Shows single plugin if FILENAME or B2HANDLER are specified
-r Remove the given building block
-s Change the building block status (INACTIVE, AVAILABLE, UNAVAILABLE)
-v List all currently installed building blocks (verbose listing)

Shows single plugin if FILENAME or B2HANDLER are specified
-o Override safety measures for mandatory B2s

BLACKBOARD USE ONLY Usage can put your system in an unstable state.

  1. Open command prompt
  2. Enter: cd C:\blackboard\tools\admin
  3. Enter: B2Manager.bat -o -r bb-software-updates
  4. Enter: B2Manager.bat -i
  5. C:\blackboard\system\autoinstall\basic.learning\allavailable\software-updates-2.0.6.war
  6. Enter: B2Manager.bat -s AVAILABLE bb-software-updates

OR this will work without the cd using this command: /usr/local/blackboard/tools/admin/

Example of removing and reinstalling a B2 from the Linux command line:

#This will re-install the Software updates building block.
# (APPHOME = Blackboard Home [/usr/local/blackboard])
# verify
$APPHOME/tools/admin/ -v bb-software-updates
# set unavailable
$APPHOME/tools/admin/ -s UNAVAILABLE bb-software-updates
# remove
$APPHOME/tools/admin/ -r bb-software-updates
# clear out plugin directory
rm -Rf $APPHOME/content/vi/bb_bb60/plugins/bb-software-updates
# use app gui to verify it is all gone
# install
$APPHOME/tools/admin/ -i

# set available
$APPHOME/tools/admin/ -s AVAILABLE bb-software-updates
# verify
$APPHOME/tools/admin/ -v bb-software-updates
# use app gui to verify it is all good

Example of disabling notifications in database:

select a.course_name || ' ' || d.user_id || ' ' || b.title || ' ' || b.event_type || ' ' || c.status
from bblearn.course_main a, bblearn.eud_item b, bblearn.eud_item_recipient c, bblearn.users d
where d.pk1 = c.user_pk1 and a.pk1 = b.crsmain_pk1 and b.pk1 = c.eud_item_pk1 and b.event_type = 'AS_AVAIL'
and c.status= 'U';

Status values:
* U
Unprocessed. Waiting for distribution.
* N
Notified. Has been disseminated to all distributors.
* F
Failed. Distribution failed for all distributors.
* D
Deleted. Removed, but retained in the DB for bookkeeping.
* Z
Neuter. Never intended to be distributed

SELECT * FROM bblearn.eud_item_recipient
WHERE (user_pk1 IN (SELECT pk1 FROM bblearn.users WHERE available_ind = 'N' ) AND status = 'U')
OR ( user_pk1 IN (SELECT u.pk1 FROM bblearn.users u WHERE u.available_ind = 'Y')
AND eud_item_pk1 IN (SELECT ei.pk1 FROM bblearn.eud_item ei WHERE ei.pk1 = eud_item_pk1 ) AND status = 'U' ) ;

As house cleaning, the messages can be set to 'neutered or Z' with
UPDATE bblearn.eud_item_recipient SET status = 'Z'
WHERE (user_pk1 IN (SELECT pk1 FROM bblearn.users WHERE available_ind = 'N' ) AND status = 'U')
OR ( user_pk1 IN (SELECT u.pk1 FROM bblearn.users u WHERE u.available_ind = 'Y' )
AND eud_item_pk1 IN (SELECT ei.pk1 FROM bblearn.eud_item ei WHERE ei.pk1 = eud_item_pk1 ) AND status = 'U' );


Paul Atkinson | Drexel University | Philadelphia, PA

Randal Dalhoff | Iowa State University | Ames, IA