Release 9.1
Server Administration Guide
©2010 Blackboard Inc. Proprietary and Confidential
Publication Date: March 29, 2010 Worldwide Headquarters
International Headquarters
Blackboard Inc.
Blackboard International B.V.
650 Massachusetts Avenue NW Sixth Floor Washington, DC 20001-3796
Dam 27 2nd Floor 1012 JS Amsterdam The Netherlands
+1 800 424 9299 toll free US & Canada +1 202 463 4860 telephone
+31 20 5206884 (NL) telephone
+1 202 463 4863 facsimile
+31 20 5206885 (NL) facsimile
www.blackboard.com
www.blackboard.com
Copyright © 1997-2010. Blackboard, the Blackboard logo, BbWorld, Blackboard Learn, Blackboard Transact, Blackboard Connect, the Blackboard Outcomes System, Behind the Blackboard, and Connect-ED are trademarks or registered trademarks of Blackboard Inc. or its subsidiaries in the United States and other countries. U.S. Patent Numbers: 6,988,138; 7,493,396; 6,816,878. Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Linux is a registered trademark of Linus Torvalds. Microsoft, Active Directory, SQL Server, and Windows are registered trademarks of Microsoft Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Red Hat and Red Hat Enterprise Linux are registered trademarks of Red Hat, Inc. in the U.S. and other countries. Sun, Java, JDBC, JDK, and Solaris are trademarks of Sun Microsystems, Inc. in the United States and/or other countries. UNIX is a registered trademark of The Open Group. Other product and company names mentioned herein may be the trademarks of their respective owners. No part of the contents of this manual may be reproduced or transmitted in any form or by any means without the written permission of the publisher, Blackboard Inc.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 2
Contents About the Server Administration Guide..................................................................................... 9 Where to Start..................................................................................................................... 9 Other Resources for Administrators ................................................................................... 9 PushConfigUpdates ............................................................................................................ 9 Blackboard Learn - Basic Edition Limitations ..................................................................... 9 Authentication.............................................................................................................................. 10 Overview ........................................................................................................................... 10 In this Section ................................................................................................................... 10 Introduction to Blackboard Learn Authentication .................................................................... 12 Overview ........................................................................................................................... 12 Customize the Default Authentication .............................................................................. 12 Return to the Default Authentication ................................................................................ 12 Authentication Properties ................................................................................................. 12 Introduction to LDAP Authentication ....................................................................................... 14 Overview ........................................................................................................................... 14 LDAP Authentication ........................................................................................................ 14 LDAP Module .......................................................................................................................... 15 Overview ........................................................................................................................... 15 Limitations......................................................................................................................... 15 LDAP Configuration Overview ................................................................................................ 16 Overview ........................................................................................................................... 16 LDAP Configuration .......................................................................................................... 16 Open LDAP – UNIX Operating Systems Only.................................................................. 16 LDAP Properties ..................................................................................................................... 17 Overview ........................................................................................................................... 17 File format ......................................................................................................................... 17 Editing the properties file .................................................................................................. 17 LDAP Property Configuration ........................................................................................... 17 Example ............................................................................................................................ 19 Troubleshooting LDAP ............................................................................................................ 21 Overview ........................................................................................................................... 21 Debugging LDAP Authentication ...................................................................................... 21 Troubleshooting LDAP Authentication Properties for Windows ....................................... 21 Troubleshooting LDAP Authentication Properties for UNIX ............................................. 22 Revert to Default Authentication ....................................................................................... 23 Blackboard Application Log .............................................................................................. 23 Common Problems ........................................................................................................... 23 LDAP Scenarios ............................................................................................................... 24 Troubleshooting LDAP with SSL ...................................................................................... 24
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 3
LDAP Fail Over Considerations .............................................................................................. 29 Overview ........................................................................................................................... 29 Automatic Fail Over for LDAP Server Error ...................................................................... 29 Automatic Fail Over for Users who Do Not Exist in LDAP Database ............................... 29 Security Risks ................................................................................................................... 29 Changing the Default Configuration for LDAP Server Error ............................................. 30 Changing the default configuration for users that do not exist in LDAP database ........... 30 LDAP with Active Directory ..................................................................................................... 31 Overview ........................................................................................................................... 31 Connecting via an Anonymous Bind ................................................................................ 31 Connecting via a Privileged Bind ...................................................................................... 31 Troubleshooting LDAP with Active Directory.................................................................... 32 Introduction to Web Server Delegation Authentication........................................................... 33 Overview ........................................................................................................................... 33 Management ..................................................................................................................... 33 Implementation ................................................................................................................. 33 Web Server Delegation with Windows 2003 ........................................................................... 34 Overview ........................................................................................................................... 34 Configure Web Server Delegation with Windows 2003 ................................................... 34 Introduction to Active Directory Authentication ...................................................................... 35 Overview ........................................................................................................................... 35 Active Directory Authentication......................................................................................... 35 Limitations......................................................................................................................... 35 Active Directory Authentication and Portal Direct Entry ................................................... 35 Active Directory Configuration ................................................................................................ 36 Overview ........................................................................................................................... 36 File format ......................................................................................................................... 36 Set authentication type ..................................................................................................... 36 Property Configuration ...................................................................................................... 36 Example ............................................................................................................................ 37 Active Directory Security Considerations ................................................................................ 38 Overview ........................................................................................................................... 38 Security Considerations .................................................................................................... 38 Introduction to Custom Authentication .................................................................................... 39 Overview ........................................................................................................................... 39 Audience ........................................................................................................................... 39 Data Model ....................................................................................................................... 39 Object Model ........................................................................................................................... 40 Overview ........................................................................................................................... 40 Authentication Object Model............................................................................................. 40
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 4
Authentication Process ........................................................................................................... 41 Overview ........................................................................................................................... 41 Login ................................................................................................................................. 41 Logout ............................................................................................................................... 42 Authentication API................................................................................................................... 43 Overview ........................................................................................................................... 43 Authentication Processing Methods ................................................................................. 43 Configuration File Processing Methods ............................................................................ 46 Implementation Details............................................................................................................ 47 Overview ........................................................................................................................... 47 Blackboard Default Implementation ................................................................................. 47 LDAP Implementation ....................................................................................................... 47 Web Server Delegation Implementation ........................................................................... 47 Extending Other Blackboard-created Authentication Modules ......................................... 48 Sample Custom Authentication Module ........................................................................... 48 Sample IUserPassAuthModule Code ............................................................................... 52 Customizing Authentication Page Flow .................................................................................. 53 Overview ........................................................................................................................... 53 Implementing requestAuthenticate() ................................................................................ 53 Redirecting to the Original Target URL ............................................................................ 53 Creating and Deploying Custom Implementations ................................................................. 54 Overview ........................................................................................................................... 54 Extending Blackboard-provided Implementations ............................................................ 54 Extending the Blackboard Default Implementation .......................................................... 54 Creating a Custom LDAP Implementation ....................................................................... 55 Creating a Custom Web Server Delegation Implementation ........................................... 55 Deploying Custom Implementations ................................................................................. 55 Updating the Collaboration Server ................................................................................... 56 Updating the launch-tool Script ........................................................................................ 56 Using WebDAV with a Custom Implementation ............................................................... 57 Troubleshooting Custom Implementations ....................................................................... 57 Blackboard Learn Architecture .................................................................................................. 58 Overview ........................................................................................................................... 58 In this Section ................................................................................................................... 58 File System ............................................................................................................................. 59 Overview ........................................................................................................................... 59 Command Line Tools ....................................................................................................... 59 HTTP Compression .......................................................................................................... 59 Content Storage ............................................................................................................... 59 Queries ............................................................................................................................. 60 Logs .................................................................................................................................. 60
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 5
Databases ............................................................................................................................... 61 Overview ........................................................................................................................... 61 BBLEARN_ADMIN ........................................................................................................... 61 BBLEARN ......................................................................................................................... 61 BBLEARN_STATS ........................................................................................................... 61 Database Users ................................................................................................................ 61 Oracle RAC Support, UNIX ..................................................................................................... 62 Overview ........................................................................................................................... 62 Configuration .................................................................................................................... 62 Prerequisites ..................................................................................................................... 62 Configure the Oracle RAC Environment .......................................................................... 62 Configure Single Instance Mode ...................................................................................... 64 Upgrading Blackboard Learn in an Oracle RAC Environment ......................................... 65 Special RAC Patches on Oracle RAC with 10g R2 .......................................................... 65 Best Practices ................................................................................................................... 65 Services .................................................................................................................................. 67 Definition of Blackboard Services ..................................................................................... 67 Starting and Stopping Services ........................................................................................ 67 Starting and Stopping the bb-collab Service .................................................................... 68 Tomcat Clusters ...................................................................................................................... 69 Overview ........................................................................................................................... 69 Installing One or More Tomcat Clusters ........................................................................... 69 Troubleshooting Installation Issues .................................................................................. 72 Cache Replication ............................................................................................................ 73 Removing a Cluster Node ................................................................................................ 74 Best Practices ................................................................................................................... 74 Operating System and Database Maintenance ...................................................................... 75 Overview ........................................................................................................................... 75 Applying a Service Pack or Security Patch after Installing Blackboard Learn ................. 75 Backup and Recovery ............................................................................................................. 76 Overview ........................................................................................................................... 76 System backup and recovery ........................................................................................... 76 Incremental data protection .............................................................................................. 76 Avoiding Recovery of Files During Upgrade .................................................................... 76 Command Line Tools .............................................................................................................. 77 Overview ........................................................................................................................... 77 PurgeAccumulator ............................................................................................................ 77 PushConfigUpdates .......................................................................................................... 78 RotateLogs ....................................................................................................................... 79 ServiceController .............................................................................................................. 79 SystemInfo ........................................................................................................................ 80
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 6
Using a Proxy Server .............................................................................................................. 81 Overview ........................................................................................................................... 81 Configure the Proxy Server, UNIX.................................................................................... 81 Configure the Proxy Server, Windows ............................................................................. 81 Content Management Administration ....................................................................................... 82 Overview ........................................................................................................................... 82 In this Section ................................................................................................................... 82 Introduction to Content Management Administration .............................................................. 83 Overview ........................................................................................................................... 83 Turn on the Content Collection ............................................................................................... 84 Overview ........................................................................................................................... 84 Enable SSL ....................................................................................................................... 84 Set up the Portal ............................................................................................................... 84 Configure Content Management Settings ........................................................................ 84 Configure Full Text Search ............................................................................................... 85 Configure Display Options ................................................................................................ 85 Enable Content Management Features ........................................................................... 86 Enable Content System Features in Courses .................................................................. 86 Access the Content Collection.......................................................................................... 86 Configuration Changes ........................................................................................................... 87 Overview ........................................................................................................................... 87 Configure the System ....................................................................................................... 87 Command Line Tools .............................................................................................................. 88 Overview ........................................................................................................................... 88 PurgeAccumulator ............................................................................................................ 88 PushConfigUpdates .......................................................................................................... 89 RotateLogs ....................................................................................................................... 89 ServiceController .............................................................................................................. 90 SystemInfo ........................................................................................................................ 91 Setting Up SSL ............................................................................................................................. 92 Overview ........................................................................................................................... 92 In this Section ................................................................................................................... 92 About SSL and SSL Choice .................................................................................................... 93 Overview ........................................................................................................................... 93 How Does SSL Work? ...................................................................................................... 93 Obtain a Certificate ........................................................................................................... 93 How Does SSL Appear to Users? .................................................................................... 94 SSL Choice ....................................................................................................................... 94 Configure SSL for IIS .............................................................................................................. 95 Overview ........................................................................................................................... 95 Configure SSL for IIS ........................................................................................................ 95
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 7
Configuring SSL for the Collaboration Tool, Windows ............................................................ 97 Overview ........................................................................................................................... 97 Load-Balanced Configurations ......................................................................................... 97 Create the Keystore .......................................................................................................... 98 Configure Tomcat to Work with the SSL Certificate ......................................................... 98 Configuring SSL for Apache ................................................................................................. 100 Overview ......................................................................................................................... 100 Configure SSL for Apache .............................................................................................. 100 Configuring SSL for the Collaboration Tool, UNIX ................................................................ 102 Overview ......................................................................................................................... 102 Configure the Collaboration Tool with a Self-signed Sertificate ..................................... 102 Configure the Collaboration Tool with a Signed Certificate ............................................ 102 Create the Keystore ........................................................................................................ 103 Configure Tomcat to Work with the SSL Certificate ....................................................... 103 SSL Choice ........................................................................................................................... 105 Overview ......................................................................................................................... 105 Find this Page ................................................................................................................. 105 SSL Choice Page Fields ................................................................................................. 105 Setting Up SIF Integration ........................................................................................................ 106 Overview ......................................................................................................................... 106 In this Section ................................................................................................................. 106 About SIF .............................................................................................................................. 107 Exchanging and Synchronizing Data ............................................................................. 107 The Blackboard SIF Agent ............................................................................................. 107 Configure the Blackboard SIF Agent .................................................................................... 108 Overview ......................................................................................................................... 108 Edit the service-config.properties File ............................................................................ 108 Configure Settings in the bb-config.properties File ........................................................ 108 Example: ......................................................................................................................... 110 Sample bb-sif-agent-config.xml ...................................................................................... 111 Configure SSL for SIF ........................................................................................................... 112 Overview ......................................................................................................................... 112 Create and Configure the Keystore ................................................................................ 112 Configure TrustStore ...................................................................................................... 114 Data Mapping ........................................................................................................................ 115 Overview ......................................................................................................................... 115 Data Map ........................................................................................................................ 115
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 8
About the Server Administration Guide The Blackboard Learn Server Administration Guide covers the configuration of server-side options such as authentication and security.
Where to Start Institutions that have just installed Blackboard Learn should become familiar with the environment before making it available to users. After installation, read the available Blackboard Learn documentation and then develop and revise a plan for managing the system. Consider: •
Authentication: Should users login to Blackboard Learn using a unique user name and password or should users authenticate once on the network and then have seamless access to Blackboard Learn? Read the section on Authentication for information on how to integrate Blackboard Learn with an authentication system already on campus (such as LDAP or Active Directory).
•
Security: Should user communications with Blackboard Learn be protected by SSL? Will users suffer with slower performance due to SSL? Read the section on SSL to encrypt user communications with Blackboard Learn.
•
Maintenance: Read the Blackboard Learn Architecture section for guidance on server maintenance. This section also reviews the file system and database structure and the command line tools available to administrators.
Other Resources for Administrators It is important that administrators read the Release Notes and review the Known and Resolved Issues. Blackboard also provides an Operations Workbook and Guide to help administrators organize their resources and plan tasks. The Operations Workbook is the outline of an administrator's "run book" and is designed to be modified and extended to meet individual needs. For information about optimizing Blackboard Learn to perform best in a particular environment, see Blackboard Learn Performance Optimization Guide.
PushConfigUpdates The PushConfigUpdates command automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible web server hostname to the database. When the PushConfiguUpdates command is complete, it will not display whether or not dynamic compression is enabled on your IIS installation. Verify this setting in IIS 6.0 by visiting Configure Compression in IIS 6.0 using Windows 2003 or in IIS 7.0 by visiting Configure Compression in IIS 7.0 using Windows 2008.
Blackboard Learn - Basic Edition Limitations Several of the server-side options described in this manual are not available to Institutions running the Blackboard Learn - Basic Edition. Blackboard Learn - Basic Edition administrators will find the Architecture section valuable. Integrated authentication and SSL are not available with the Blackboard Learn - Basic Edition.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 9
Authentication Overview This section reviews the configuration, and management of several different Authentication models supported with Blackboard Learn.
In this Section This section includes the following topics: T opic
De s cr ip t io n
Introduction to Blackboard Learn Authentication
This topic defines the default authentication model.
LDAP Authentication Introduction to LDAP
This topic defines LDAP.
LDAP Module
This topic presents the set of included code that supports LDAP.
LDAP Configuration Overview
This topic defines how to setup Blackboard Learn to use LDAP.
LDAP Properties
This topic defines the configurable properties that define how LDAP works with Blackboard Learn.
Troubleshooting LDAP
This topic presents solutions to some common problems encountered with LDAP.
LDAP Failover Considerations
This topic describes the decisions that control the authentication process when an issue is encountered.
LDAP with Active Directory
This topic describes how to use LDAP with Active Directory.
Web Server Delegation Introduction to Web Server Delegation Authentication
This topic presents information on implementing a Web Server authentication solution.
Web Server Delegation with Windows 2003
This topic covers Web Server Delegation with Windows 2003.
Active Directory Authentication Introduction to Active Directory Authentication
This topic defines Active Directory authentication and the implementation process.
Active Directory Configuration
This topic reviews the options available when setting up Active Directory authentication.
Active Directory Security Considerations
This topic presents information on Active Directory security.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 10
T opic
De s cr ip t io n
Custom Authentication Introduction to Custom Authentication
This topic describes the APIs that can be used to create a custom authentication model.
Object Model
This topic reviews the object model of the Authentication APIs.
Authentication Process
This topic describes the authentication process.
Authentication API
This topic provides information on the Authentication APIs.
Implementation Details
This topic describes some of the issues that must be resolved when implementing a custom authentication model.
Customizing Authentication Page Flow
This topic covers changing the authentication page flow.
Creating and Deploying Custom Implementations
This topic describes how to implement a custom authentication model.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 11
Introduction to Blackboard Learn Authentication Overview The default authentication for Blackboard Learn authenticates the user’s login credentials against the Blackboard Learn database.
Customize the Default Authentication Changing the Blackboard Learn Authentication process and options does not require any database changes. All of the options are stored in a properties file. Modify the authentication.properties file to customize the default authentication for Blackboard Learn.
Return to the Default Authentication If, in the Course of setting up a customized Authentication solution, it is necessary to return to Blackboard Learn default authentication (rdbms), the authentication type (bbconfig.auth.type) can be set via the command line. This allows Blackboard Learn, at start up, to select the appropriate set of auth.type*.* entries. Follow these steps to reset the system to use the default authentication model: 1.
Change to the following directory: cd BB_DEPLOY_DIR\blackboard\config
2.
Edit the authentication.properties file as shown. auth.type.rdbms.impl=blackboard.platform.security.authentication. BaseAuthenticationModule auth.type.rdbms.use_challenge=true
3.
Edit the bb-config.properties file. Change the property to bbconfig.auth.type=rdbms.
4.
Run the PushConfigUpdates command line tool to activate the changes.
Authentication Properties The table below details the properties applicable to the default authentication model. These properties are configured through the authentication.properties file. The authentication.properties properties file is found in /bbservices/config. P ro p e rt y
De s cr ip t io n
auth.type.rdbms.impl
Defines the class which must conform to the HttpAuthModule interface. The default value, blackboard.platform.security. authentication.BaseAuthenticationModul e, should not be changed unless the Institution builds and implements its own class for Blackboard
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 12
P ro p e rt y
De s cr ip t io n Learn default authentication.
auth.type.rdbms.use_challenge
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Defines the encryption setting where a value of “false” indicates the password is encrypted with base 64 and a value of “true” indicates the password is encrypted with MD5. The default value is “true”. MD5 encryption offers stronger security for passwords. Base64 is similar to sending the password in plain text.
Page 13
Introduction to LDAP Authentication Overview Blackboard Learn includes an LDAP (Lightweight Directory Access Protocol) module that will authenticate users against an Institution’s directory server or servers using LDAP. All the files necessary to support LDAP authentication are included with Blackboard Learn.
LDAP Authentication LDAP is an Internet standard that provides access to information from different computer systems and applications. LDAP uses a set of protocols to access information directories and retrieve information. A directory is like a database, but contains information that is more descriptive and attribute-based. Information in a directory is generally read more often than it is written or modified. LDAP allows an application, running on the Institution’s computer platform, to obtain information such as user names and passwords. Centralizing this type of information is very beneficial. It simplifies the job of the System Administrator by providing a single point of administration. It also provides a single location for user information, reducing the storage of duplicate information. This, in turn, reduces maintenance needs. LDAP authentication also enables users to have a single login and password to access a number of different applications.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 14
LDAP Module Overview Standard LDAP authentication is fully integrated with Blackboard Learn. All necessary .jar files, including those for setting up an SSL connection between Blackboard Learn application server and the directory servers, are provided in the /systemlib directory. The application server startup executables include the .jar files in their classpath. Note that all configuration options in the authentication.properties file are set to default values. Some of these default values are place holders and must be changed by the Administrator for LDAP authentication to work successfully. To begin authenticating against an LDAP server or servers, set the properties found in the authentication.properties file. The SSL Configuration topic has specific information on enabling the Blackboard Learn application server and the directory servers to communicate over SSL.
Limitations The limitations of this version of the LDAP module are summarized in the following list. •
The module only supports authentication through a successful bind with the directory server using the FDN for this Blackboard user—the module cannot retrieve any information from the directory.
• The module only supports binding anonymously or binding with a privileged user and then performing a search for the user's FDN. Check with Blackboard Technical Support if you have any questions regarding these limitations. For installation problems or questions while using this document, contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com. For planning, architectural analysis, best practices, or assistance with implementation, call Blackboard Technical Solutions.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 15
LDAP Configuration Overview Overview This topic provides an overview of the LDAP Installation process. This process consists of a set of steps that will enable the System Administrator to use LDAP authentication.
LDAP Configuration The following steps outline the LDAP configuration process: 1.
Edit the /blackboard/config/authentication.properties file. See the next topic, LDAP Property Configuration for specific information on the properties and possible values in this file.
2.
Configure the bbconfig.auth.type property to LDAP. This must be done for the configuration to proceed correctly. Make the following change in the bbconfig.properties file: bbconfig.auth.type=ldap
3.
Run PushConfigUpdates to activate the changes.
Open LDAP – UNIX Operating Systems Only Blackboard has two versions of LDAP client authentication modules, the default and OpenLDAP. Two modules exist because the default LDAP client does not release file descriptors when it is under heavy load. A file descriptor is used by UNIX Operating Systems to keep track of open files and network connections. If the system continually accumulates file descriptors, the server will reach a maximum number of allowed file descriptors, at which point no more files can be opened and no more network connections can be accepted. Administrators of UNIX Operating Systems who experience this file descriptor issue under heavy load may deploy OpenLDAP as a workaround. If OpenLDAP is used, the .jar files must be updated so the command line tools do not fail. A copy of the jar file should be in /systemlib. Additionally, edit /system/build/bin/launch-tool.sh and append the .jar files to the BB_CP variable. Otherwise, command line tools that bootstrap the core services (for example, LogRotation or PurgeAccumulator) will not work.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 16
LDAP Properties Overview The properties set in the authentication.properties file include general properties for LDAP configuration, as well as properties for individual directory servers. When adding multiple servers the variable x represents the sequence number. Parameters must be set for each directory server that Blackboard Learn will authenticate against. The LDAP module will access the servers according to the sequence number.
File format The authentication.properties and bb-config.properties files contain a series of properties that must be set before authentication against the Institution’s directory server or servers can occur. Each property is listed with an equal sign followed by the corresponding value.
Editing the properties file Open the authentication.properties file in an editor and set the LDAP specific properties to match the Institution. Descriptions of the properties appear in the following section. Properties that are suffixed with a number are properties that are associated with an individual directory server. To add information for additional directory servers, add a group of properties suffixed with the next available sequence number. The LDAP module will access the servers in the order in which they are sequenced.
LDAP Property Configuration The table below details the LDAP properties configured through the authentication.properties file. P ro p e rt y
De s cr ip t io n
auth.type.ldap.impl
Defines the class which must conform to the HttpAuthModule interface. The default value, blackboard.platform.security. authentication.LDAPAuthModule, should not be changed unless the Institution builds and implements its own class for LDAP authorization.
auth.type.ldap.use_ challenge
Defines the encryption setting where a value of “false” indicates base 64 encryption and a value of “true” indicates MD5 encryption. The default value is “false”. MD5 encryption should only be used if the LDAP servers use MD5 encryption in the same manner as Blackboard. In most cases, using base 64 encryption and securing the connection between Blackboard Learn and the LDAP servers with SSL is the best approach.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 17
P ro p e rt y
De s cr ip t io n
auth.type.ldap.num_ servers
Defines the number of directory servers in use. For each server, there must be a corresponding set of server properties. This property must be kept current; update it each time a new server’s entries are added to the authentication.properties file.
auth.type.ldap.user _not_found_fallback
Can be set to “true” or “false”. By default, this property is set to “false” due to the security considerations outlined in LDAP Security Considerations. If set to “true” the module will attempt to authenticate the user using the password in Blackboard Learn database if the user is not found in any of the directory servers.
auth.type.ldap.erro r_fallback_to_bb
Can be set to “‘true” or “false”. By default, this property is set to “false” due to the security considerations outlined in LDAP Security Considerations. If set to “true” the module will attempt to authenticate the user using the password in Blackboard Learn database if there is an error connecting to any of the directory servers.
Server Specific Properties auth.type.ldap.serv er_url.x
The URL of the directory server including port. Example: ldap://directory.university.edu:389 If the LDAP server is setup to communicate over SSL, the URL should be: ldaps://directory.university.edu:636
auth.type.ldap.serv er_ssl.x
Must be set to “true” or “false”. If set to “true” the module will attempt to connect to the LDAP directory using SSL. The LDAP server must be set up to handle SSL connections. See the SSL Configuration section for more information.
auth.type.ldap.use_ priv_user.x
Must be set to “true” or “false”. If set to “true” the module will bind to the LDAP server as a privileged (specific) user when searching for the FDN of the user to authenticate.
auth.type.ldap.user _fdn.x
The user binds as this FDN. Leave as “(none)” if not applicable.
auth.type.ldap.user _pwd.x
The password of the privileged user. Leave as “(none)” if not applicable.
auth.type.ldap.dere f_aliases.x
Set this property to configure how aliases are dereferenced during search operations. The following values are defined for this property:
auth.type.ldap.user _tag.x
•
always: Always dereference aliases.
•
never: Never dereference aliases.
•
finding: Dereference aliases only during name resolution (that is, while locating the target entry).
•
searching: Dereference aliases once name resolution has been completed (that is, after locating the target entry).
Set this property to the attribute containing Blackboard Learn User Name. This setting is domain specific.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 18
P ro p e rt y
De s cr ip t io n
auth.type.ldap.serv er_error_fatal.x
Must be set to “true” or “false”. If set to “true” the module will exit with a fatal error if there is an error connecting to the server.
auth.type.ldap.cont ext_factory.x
Set this property to handle password expiration warnings for LDAP accounts. The following values are defined for this property:
auth.type.ldap.refe rral.x
•
blackboard.platform.security.authentication.Password PolicyContextFactory for IETF-compatible LDAP servers (Novell, Active Directory). This is the default value.
•
blackboard.platform.security.authentication.Response PolicyContextFactory for Netscape-compatible LDAP servers supporting the Netscape response control specification.
The value of this property is a string that specifies how referrals should be handled by the module. The following values are defined for this property: •
follow: Automatically follow any referrals.
•
throw: Throw a Java ReferralException for each referral. This will result in an error condition for this server.
•
ignore: Ignore referrals if they appear in results. In debug mode, a log message will be generated to indicate an incomplete result, but this will not result in an error condition for this server.
auth.type.ldap.refe rral_limit.x
The value of this property is a string of decimal digits specifying the maximum number of referrals to follow in a chain of referrals. A setting of zero indicates that there is no limit.
base_search_fdn
The starting point in the LDAP directory structure for searching for a Blackboard Learn user.
Example Below is an example of the LDAP properties configured through the authentication.properties file. auth.type.ldap.impl=blackboard.platform.security.authentication. LDAPAuthModule auth.type.ldap.use_challenge=false auth.type.ldap.error_fallback_to_bb=false auth.type.ldap.user_not_found_fallback_to_bb=false auth.type.ldap.log_level=error # Available property values for auth.type.ldap.log_level are fatal,error,warning,information,debug auth.type.ldap.num_servers=2 # The auth.type.ldap.num_servers property value must be increased with each server configuration addition. If there are
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 19
three server configurations, then the value must be 3 for this parameter.
Server #1 Configuration auth.type.ldap.server_ssl.1=false # The auth.type.ldap.server_ssl property value sets SSL interaction between # the Blackboard installation server and LDAP server to true or false. auth.type.ldap.base_search_fdn.1=dc=dc,dc=blackboard,dc=com auth.type.ldap.deref_aliases.1=never auth.type.ldap.server_url.1=ldap://lsvr1 auth.type.ldap.use_priv_user.1=true auth.type.ldap.user_fdn.1=uid=UserA,ou=Special Users,dc=dc,dc=blackboard,dc=com auth.type.ldap.user_pwd.1=test1 auth.type.ldap.user_tag.1=uid auth.type.ldap.referral.1=ignore auth.type.ldap.referral_limit.1=0 auth.type.ldap.server_error_fatal.1=true auth.type.ldap.context_factory.1=blackboard.platform.security.au thentication.PasswordPolicyContextFactory
Server #2 Configuration auth.type.ldap.server_ssl.2=false # The auth.type.ldap.server_ssl property value sets SSL interaction between # the Blackboard installation server and LDAP server to true or false. auth.type.ldap.base_search_fdn.2=dc=dc,dc=blackboard,dc=com auth.type.ldap.deref_aliases.2=never auth.type.ldap.server_url.2=ldap://lsvr2 auth.type.ldap.use_priv_user.2=true auth.type.ldap.user_fdn.2=uid=UserB,ou=Special Users,dc=dc,dc=blackboard,dc=com auth.type.ldap.user_pwd.2=test2 auth.type.ldap.user_tag.2=uid auth.type.ldap.referral.2=ignore auth.type.ldap.referral_limit.2=0 auth.type.ldap.server_error_fatal.2=true auth.type.ldap.context_factory.2=blackboard.platform.security.au thentication.PasswordPolicyContextFactory
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 20
Troubleshooting LDAP Overview The LDAP module should function with minimal maintenance if the authentication.properties file is configured properly. This topic includes information on how to troubleshoot configuring the properties files and on maintenance for LDAP authentication.
Debugging LDAP Authentication Administrators may debug the LDAP authentication as part of troubleshooting. The steps below explain how to debug LDAP authentication: 1.
Modify /blackboard.config/service-config.properties. Under Logging Service in the service-config.properties file set: blackboard.service.log.param.logdef.default.verbosity=debug
2.
Restart the services. //tools/admin/ServiceController services.stop //tools/admin/ServiceController services.stop
3.
Login to the system again.
4.
Search //logs/bb-services-log.txt for references to LDAPAuthModule. Windows users: Open the log file in a text editor and search for LDAPAuthModule. UNIX users: Execute the following: tail -f -n200 //config/service-config.properties | grep "LDAPAuthModule"
Troubleshooting LDAP Authentication Properties for Windows For Administrators using a Windows workstation, the LDP executable may be used to troubleshoot LDAP authentication properties. The LDP executable, found on the Windows 2003 Server CD in the \SUPPORT\TOOLS folder, is used to search for specific data against the Active Directory and includes a graphical user interface. For users not using Active Directory, this tool may be used in the same way against other LDAP servers. The following steps explain how to use the LDP Tool: 1.
Go to the Connection menu, uncheck the NTLM/Kerberos check box, and select Bind.
2.
Enter the LDAP privileged user DN in the User: field and the LDAP password in the Password: field.
3.
Locate the defaultNamingContext attribute.
4.
Go to the View menu and select Tree.
5.
Enter the defaultNamingContext attribute value into the BaseDN: field and click OK.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 21
6.
Locate the container for user records (by default, the DN for this container starts with CN=Users; however the user records may be located elsewhere; try to locate the DN that contains all faculty and student user records).
7.
Record the DN that contains all faculty and student user records
8.
Double-click on the tree view of this container to see all user records.
9.
Go to the Options menu and select Search.
10.
Customize fields in the user records returned from the search. (This step may not be necessary)
11.
With the container selected, go to the Browse menu and select Search.
12.
Enter the user field to search by. The user field is the user tag property, for example, (CN=jsmith).
13.
Record the distinguishedName attribute for this user record.
14.
Verify that you can find a sample user. Enter the baseDN from Step 7 and (user_tag=someUserValue) where user_tag is the name of the LDAP user record field that the client expects users to enter in the Blackboard login form. (For example, if the client expects users to login by entering their email address as the ‘username’ in the Blackboard login form, then the user_tag should be the name of the field that stores the user’s email address).
15.
Next, Administrators must update authentication.properties: Set auth.type.ldap.base_search_fdn.1 to the DN for the container for user records (See Step 7 above). Set auth.type.ldap.user_fdn.1 to the distinguishedName attribute value for the LDAP user (See Step 13 above). Windows Operating System only: Set auth.type.ldap.user_tag.1 to sAMAccountName if the client wants users to login to Blackboard using a Windows username. sAMAccountName is the name of the Active Directory user record field that stores the Windows username.
Troubleshooting LDAP Authentication Properties for UNIX For Administrators using a UNIX workstation, the LDAP Browser may be used to troubleshoot LDAP authentication properties. This tool may be found at http://www.iit.edu/~gawojar/ldap/. The following steps explain how to use the tool: 1.
Open the LDAP browser.
2.
Click File Menu and select Connect.
3.
Enter the LDAP server hostname in the Host: field.
4.
Enter the port number that the LDAP server is listening on in the Port: field.
5.
Enter the base search DN in the Base DN: field. If a privileged bind is required, uncheck Anonymous bind.
6.
Enter the privileged user DN in the User DN: field. If Append base DN is checked, the Administrator only needs to add the relative DN ( for example, if the base DN is "OU=test users,dc=blackboard,dc=com" and the privileged user's full DN is
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 22
"CN=privldap,OU=ldap testers,OU=test users,dc=blackboard,dc=com", then only enter "CN=privldap,OU=ldap testers"). 7.
Click Connect.
8.
Click Search to search for a given user DN, or scroll through the list.
Revert to Default Authentication To revert to the default authentication from LDAP, change bbconfig.auth.type to "rdbms”, and restart Blackboard Learn application server. For more information, see Return to Default in the Introduction to Blackboard Learn Authentication topic.
Blackboard Application Log Blackboard Learn log records all application events handled by the Java API. Within the log the Blackboard LDAP module writes error, warning, informational, and debug messages to the bbservices-log.txt file.
Common Problems The table below outlines some of the common problems that may occur when authenticating Blackboard Learn users against LDAP servers. P ro b le m
Ac t io n
The LDAP module loads but users cannot log in using their LDAP passwords.
Ensure that all of the users logging in have a Blackboard Learn User Name. Blackboard Learn needs a user record to associate Course and other information to the user.
An error is posted to the bbservices-log.txt whenever a user tries to log into the system. The module is configured to use SSL.
Ensure that the server certificate for your LDAP directory has been imported into the keystore of the JVM on Blackboard Learn application server. The JVM needs this certificate to allow SSL connections to the LDAP directory.
The LDAP module loads, but users cannot log in. Nothing is displayed in the logs, or the messages that are displayed are insufficient to diagnose the problem.
Re-run the auth-type.properties file and specify a log_level of “debug”. Log messages will generate with more detail.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 23
LDAP Scenarios The table below details the systems response to a number of potential LDAP situations. The default configuration of LDAP will support the set of behaviors described here. Is su e
S ymp t o m
The LDAP server is down
Authentication should fail with an appropriate message.
The user exists in Blackboard but not in LDAP
Authentication should fail with an appropriate message.
The user exists in LDAP but not in Blackboard
Authentication should fail with an appropriate message.
The privileged user doesn't exist or has expired
Authentication should fail with an appropriate message. Blackboard Learn configuration file must be updated to proceed.
The privileged user password has changed
Authentication should fail with an appropriate message. Blackboard Learn configuration file must be updated to proceed.
There are multiple LDAP accounts for a specific user
The search domain would be restricted to a specific context within the directory tree. The first account returned will be the one used. It is the Institution's responsibility to set the base_search_fdn property correctly to avoid this situation.
The LDAP SSL certificate expires
Authentication should fail with an appropriate message. The LDAP SSL certificate must be updated to proceed.
Troubleshooting LDAP with SSL This section explains how to troubleshoot the SSL connection between the Blackboard server and the LDAP server for clients who are using an SSL connection to secure their LDAP server. Follow these instructions for debugging and clean up on UNIX: 1.
Save //apps/tomcat/bin/tomcat.sh as tomcat.sh.prod
2.
Enter the following command: cp tomcat.sh.prod tomcat.sh.debug
3.
Insert -Djavax.net.debug=all,record,plaintext into tomcat.sh.debug
4.
Go to line 207 of tomcat.sh.debug Edit this line to read: $JAVACMD -Djavax.net.debug=all,record,plaintext $TOMCAT_OPTS $JAVA_OPTS $MAIN start $@ \
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 24
5.
Enter the following command: cp tomcat.sh.debug tomcat.sh
6.
Restart services
7.
Login with the LDAP username and password.
8.
Copy the SSL-connection trace information from /usr/local/blackboard/logs/tomcat-jvm-stdout.txt. See the log file example below.
9.
Repeat Steps 6 and 7 until debugging is complete.
10.
Enter the following command: cp tomcat.sh.prod tomcat.sh
11.
Restart services.
Follow these instructions for debugging and clean up on Windows: 1.
Save D:\\apps\tomcat\conf\jk\wrapper.pro perties as wrapper.properties.prod.
2.
Copy wrapper.properties.prod and name the copy wrapper.properties.debug.
3.
Insert -Djavax.net.debug=all,record,plaintext into wrapper.properties.debug.
4.
Go to line 163 of wrapper.properties.debug.
5.
Edit that line to read: "wrapper.cmd_line=$(wrapper.javabin) $(wrapper.java_opts) Djavax.net.debug=all,record,plaintext Djava.security.policy=="$(wrapper.tomcat_policy)" Djava.security.manager -Dtomcat.home="$(wrapper.tomcat_home)" Dblackboard.home="$(bbapp.root)" Dbbservices_config="$(bbapp.root)\config\serviceconfig.properties" Dorg.apache.tomcat.apps.classpath="$(wrapper.class_path.apps)" classpath $(wrapper.class_path) $(wrapper.startup_class) -config $(wrapper.server_xml)"
6.
Delete wrapper.properties then copy wrapper.properties.debug and name the copy wrapper.properties.
7.
Restart services.
8.
Login with the LDAP username and password.
9.
Copy the SSL-connection trace information from D:\blackboard\logs\tomcatjvm-stdout.txt. See the log file example below.
10.
Repeat until debugging is complete.
11.
Delete wrapper.properties then copy wrapper.properties.prod and name the copy wrapper.properties.
12.
Restart services.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 25
Log File Example If the SSL -connection-setup process cannot continue, the reason for the SSL connection setup failure is printed to the tomcat-jvm-stdout.txt log. After this failure appear in the log the SSL-debug output stops. There are a number of reasons why the application server may have trouble connecting to the LDAP server over SSL. The problem can be found in the SSL-debug output. Open the tomcat-jvm-stdout.txt log; go to the end of the debug output (where it gives the reason for quitting) and then scroll backwards through the output, looking for the detailed error message. For example, in the debug output below, the end of the output shows the message “Thread-31, SEND SSL v3.0 ALERT: fatal, description = certificate_unknown”. Scrolling backwards through the log, the message “out of date cert” appears before the last certificate was processed; the certificate’s information shows that the certificate had expired in 2002. The example below includes the beginning of the debug output and the last section with the error: keyStore is : keyStore type is : jks init keystore init keymanager of type SunX509 trustStore is: /usr/java1.3/jre/lib/security/cacerts trustStore type is : jks init truststore adding as trusted cert: [ ……………… out of date cert: [ [ Version: V3 Subject: O=HC, CN=204.165.200.98 Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5 Key: com.sun.net.ssl.internal.ssl.JSA_RSAPublicKey@187197 Validity: [From: Sun Jun 18 07:16:00 EDT 2000, To: Tue Jun 18 07:16:00 EDT 2002] Issuer: O=HC, OU=Organizational CA SerialNumber: [ 021411e9 6f9a05e1 28e9293c c80ae5b5 1166338c 1cbc0201 0c] Certificate Extensions: 3 [1]: ObjectId: 2.16.840.1.113719.1.9.4.1 Criticality=false Extension unknown: DER encoded OCTET string = 0000: 04 82 01 BD 30 82 01 B9 04 02 01 00 01 01 FF 13 ....0........... 0010: 1D 4E 6F 76 65 6C 6C 20 53 65 63 75 72 69 74 79 .Novell Security 0020: 20 41 74 74 72 69 62 75 74 65 28 74 6D 29 16 43 Attribute(tm).C 0030: 68 74 74 70 3A 2F 2F 64 65 76 65 6C 6F 70 65 72 http://developer 0040: 2E 6E 6F 76 65 6C 6C 2E 63 6F 6D 2F 72 65 70 6F .novell.com/repo 0050: 73 69 74 6F 72 79 2F 61 74 74 72 69 62 75 74 65 sitory/attribute 0060: 73 2F 63 65 72 74 61 74 74 72 73 5F 76 31 30 2E s/certattrs_v10.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 26
0070: 68 74 6D 30 htm0..J.....0.0. 0080: 02 01 01 02 .....F0.0....... 0090: 02 01 69 A1 ..i.....0.0..... 00A0: 01 46 30 08 .F0.0.........i. 00B0: 06 02 01 17 ............Z... 00C0: 02 02 00 FF ................ 00D0: 00 00 00 00 ................ 00E0: 00 30 18 30 .0.0............ 00F0: FF FF 01 01 ..........H0.0.. 0100: 01 00 02 08 ................ 0110: 04 06 F0 DF ....H0X.X....... 0120: 02 01 00 03 ......@......... 0130: 00 00 03 09
[email protected] 0140: 10 02 01 00 ................ 0150: 00 02 04 11 .....o.0.0...... 0160: 7F FF FF FF ...............o 0170: 9A A2 4E 30 ..N0L........... 0180: 0D 00 80 00 ................ 0190: 00 80 00 00 .........0.0.... 01A0: 02 08 7F FF .............0.0 01B0: 10 02 01 00 ................ 01C0: 00
82 01 4A A0
1A 01 01 00 30 08 30 06
01 46 30 08
30 06 02 01 01 02 01 0A
1A 01 01 00
30 08 30 06 02 01 01 02
30 06 02 01
01 02 01 0A 02 01 69 A2
01 01 FF A3
82 01 06 A0 5A 02 01 02
02 01 00 03
0D 00 80 00 00 00 00 00
00 00 03 09
00 80 00 00 00 00 00 00
10 02 01 00
02 08 7F FF FF FF FF FF
00 02 04 06
F0 DF 48 30 18 30 10 02
7F FF FF FF
FF FF FF FF 01 01 00 02
48 30 58 A1
58 02 01 02 02 02 00 FF
0D 00 40 00
00 00 00 00 00 00 00 00
00 40 00 00
00 00 00 00 00 30 18 30
02 08 7F FF
FF FF FF FF FF FF 01 01
E9 6F 9A 30
18 30 10 02 01 00 02 08
FF FF FF FF
01 01 00 02 04 11 E9 6F
4C 02 01 02
02 01 00 02 02 00 FF 03
00 00 00 00
00 00 00 00 00 00 03 09
00 00 00 00
00 30 12 30 10 02 01 00
FF FF FF FF
FF FF 01 01 00 30 12 30
02 08 7F FF
FF FF FF FF FF FF 01 01
[2]: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: 01 ] ] [3]: ObjectId: 2.5.29.15 Criticality=false KeyUsage [ DigitalSignature
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
.
.
Page 27
Key_Encipherment ] ] Algorithm: [SHA1withRSA] Signature: 0000: 50 75 22 E0 14 FE E7 50 FE 44 3B 36 D2 C8 EC 10 Pu"....P.D;6.... 0010: 49 8D 48 1D 6F E6 91 1A 05 1E 8E FD 69 D3 4D 70 I.H.o.......i.Mp 0020: C3 3C FE 14 D0 D4 99 DE CA BF 23 57 80 A0 04 F2 .. 0040: 94 73 F9 83 21 2C 80 17 B1 CE 6E 19 FD 14 FF A8 .s..!,....n..... 0050: C0 CB 51 C7 1A C1 C0 E4 71 2F 46 9D 50 91 52 E8 ..Q.....q/F.P.R. 0060: 5B CA 24 84 FF 7F 3E 84 32 09 AA 43 66 E8 CD AB [.$...>.2..Cf... 0070: 65 EC 5C 89 88 43 3C 15 07 3C 9D 52 AA CF 31 A1 e.\..C update .xy_file_systems set jdbc_connection_url='jdbc:oracle:oci:@bbrac '; 2 rows updated. SQL> commit; Commit complete.
9.
Go to /tools/admin
10.
Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh
11.
Verify the application has connected to the Oracle RAC environment and is working as expected.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 63
Note
The ORACLE_HOME location is defined by the property bbconfig.database.local.oracle.home in bb-config.properties. The default ORACLE_HOME is /apps/oracleclient/
Configure Single Instance Mode 1.
Verify that Blackboard Learnis connected to Oracle RAC instances and functioning properly.
2.
Stop your server by issuing .//tools/admin/ServiceController.sh services.stop
3.
Go to /config
4.
Open the bb-config.properties file to switch back to the JDBC driver and unset tns for RAC. bbconfig.oracle.client.drivertype=thin bbconfig.database.type.oracle.tns=
5.
Verify that the bbconfig.database.server.* parameters in bbconfig.properties points to one of the RAC instances as follows: bbconfig.database.server.name= rac01 bbconfig.database.server.fullhostname= rac01.foo.com bbconfig.database.server.instancename= bb-rac-db01 bbconfig.database.server.portnumber=1521 bbconfig.database.server.systemuserpassword=oracle
6.
Connect to the database with a user that has permissions to the BBLEARN_CMS schema then query the database and update the connection where rac01 is the name of the first database instance and bb-rac-db01 is the server name where the first instance is running : sqlplus @bbrac SQL> select DB_USERNAME,DB_PASSWORD,JDBC_CONNECTION_URL from .XY_FILE_SYSTEMS; SQL> update .xy_file_systems set jdbc_connection_url='jdbc:oracle:thin:@rac01:1521: bb-rac-db01'; 2 rows updated. SQL> commit; Commit complete.
7.
Go to /tools/admin
8.
Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 64
9.
Verify the application has connected using the JDBC driver and all components are working as expected.
Upgrading Blackboard Learn in an Oracle RAC Environment 1.
Prior to upgrading Blackboard Learn in an Oracle RAC environment, all modifications to the configuration must be reversed. Follow the instructions in Configure Single Instance Mode to ensure that properties relating to the database server are pointing to one RAC node.
2.
Stop your server by issuing .//tools/admin/ServiceController.sh services.stop
3.
While connected to one of the RAC nodes, perform a standard upgrade of Blackboard Learn
4.
Verify the application has connected using the JDBC driver and all components are working as expected.
5.
Follow the instructions in Configure the Oracle RAC Environment to reconfigure the application to use an Oracle RAC environment.
Special RAC Patches on Oracle RAC with 10g R2 Problem: ORA-00600: internal error code, arguments: [kkocxj : pjpCtx] while complex sqls. Solution: To work around this Oracle bug, logon as sysdba and alter system set "_optimizer_push_pred_cost_based" = false scope =both; Reference: http://forums.oracle.com/forums/thread.jspa?threadID=836121
Best Practices •
Review all requirements for Blackboard Learn 9.1 application configuration prior to installation
•
Use only 1 application and database instance to configure the environment to connect to Oracle RAC.
•
Always test application functionality to verify the application is working as expected.
•
Test failover of the database by shutting down one database instance and test the application functionality
•
Check netstat to ensure that the application is connected to the correct IP/alias for the instance
•
If you want to configure the application server, cloning the first application server and updating the configuration files is the most efficient method for initial installation
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 65
•
If upgrading, always reverse configuration and customizations, then test functionality before running the installer
•
If you require additional planning or assistance with the configuration contact Blackboard Consulting.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 66
Services After Blackboard Learn is installed, it adds the bb-collab and bb-tomcat services to the operating system. In addition, for Blackboard Learn to run properly on Windows, the IIS service must be running and the SQL Server database must be started. When running on a UNIX operating system, the Apache process must be running and the Oracle database must be started and running correctly. When performing maintenance or upgrade tasks it may be necessary to stop some of these services. For most upgrade tasks, including installing Blackboard Learn software updates, the bb-collab, bb-tomcat, and IIS or Apache services should be stopped but the database should be running. While this is a good general rule, please refer to the specific instructions for each task to confirm. Blackboard uses the "service" terminology familiar to Windows users. UNIX users should think of services as processes.
Definition of Blackboard Services bb-collab: The bb-collab service runs the Collaboration Tool within Blackboard Learn. Stopping this service will make the Collaboration Tool unavailable to users. bb-tomcat: The bb-tomcat service runs the Java® servlet engine. Stopping this service makes any Java servlet pages unavailable to users, including the Login page.
Starting and Stopping Services The ServicesController utility is used to start and stop services. This utility must be run from the command line. Windows: C:\\tools\admin\ServiceController UNIX: //tools/admin/ServiceController Where each is defined in the following table. Ar g um en t
De s cr ip t io n
services.start
Starts all the services related to the Blackboard Learn.
services.stop
Stops all the services related to the Blackboard Learn.
services.restart
Stops and immediately starts the services related to the Blackboard Learn.
services.appserver.start
Starts the bb-tomcat service.
services.appserver.stop
Stops the bb-tomcat service.
services.appserver.restart
Stops and immediately starts the bb-tomcat service.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 67
Ar g um en t
De s cr ip t io n
services.webserver.start
Starts the IIS or Apache® Web service.
services.webserver.stop
Stops the IIS or Apache Web service.
services.webserver.restart
Stops and immediately starts the IIS or Apache Web service.
Starting and Stopping the bb-collab Service In rare instances it may be necessary to stop only the bb-collab service but leave all other services running. For example, when setting up a dedicated collaboration server in a multiple Web/app server configuration it is necessary to stop the bb-collab service on all servers except the collaboration server. The bb-collab service (as well as the IIS and bb-tomcat services) can be controlled individually through the Services panel on Windows operating systems. UNIX operating system users employ UNIX commands that control processes to manage the bb-collab and apache "services."
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 68
Tomcat Clusters Overview Tomcat Application Clusters consist of multiple Blackboard Learn java application (JVM) server instances running simultaneously (on the same physical server) and working together to provide increased scalability. Scalability is an application's ability to support a growing number of users. If it takes one application 10 milliseconds to respond to one request, how long does it take to respond to 10,000 requests? If a user logs on at 3 AM do they experience the same responsiveness as they do at 3 PM? Tomcat Application Clusters ensure that Blackboard Learn remains responsive by adding server instances to a cluster without interruption of service. Note
Cluster nodes cannot be modified. If a change is required, then the node must be removed and then added again with the updated information.
Tomcat Application Clusters are not meant as a replacement for traditional load balance configurations, but as a complementary scheme that provides improved scalability and failover capabilities. Traditional load-balancing is a physical distribution of server instances across multiple servers. Tomcat Application Clusters are logical instances of the Java application components that reside on a single server, or are distributed across multiple servers. There are two types of server clustering: horizontal and vertical: •
Horizontal clustering allows server instances to be deployed across multiple physical servers. This method of clustering is not implemented by Blackboard because Blackboard already supports load-balancing.
•
Vertical clusters, also known as multi-home clusters, allow multiple server instances to be run on a single machine. This method takes full advantage of the processing power of a single server. Vertical clusters are load-balanced by the web server.
Tomcat Clustering runs on all Blackboard platforms (Windows, Linux, and Solaris).
Installing One or More Tomcat Clusters This section includes all of the procedures needed to install and configure Tomcat Application Clusters. These procedures assume an Administrator has full administrative rights as either administrator or root. Before Installing a Cluster The server must be configured to support clustering prior to installing a Tomcat Cluster node. Clustering is disabled by default and must be enabled. Installing a cluster requires that the application instance be shutdown and restarted. Configuring in Windows: 1.
Go to the Blackboard Learn home, \config
2.
Open the bb-config.properties file.
3.
Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 69
4.
Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts.
5.
Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node.
6.
Go to \tools\admin
7.
Launch the Push Config Updates script by running the PushConfigUpdates.bat file.
8.
Create a new ServerGroup in Blackboard Learn a. Navigate to \tools\admin b. Create a ServerGroup with a specified port number by running: ServerGroupManager.bat -c -n -p
Configuring in UNIX: 1.
Go to the Blackboard Learn home, /config
2.
Open the bb-config.properties file.
3.
Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'.
4.
Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts.
5.
Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node.
6.
Go to /tools/admin
7.
Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh
8.
Create a new ServerGroup in Blackboard Learn a. Navigate to /tools/admin b. Create a ServerGroup with a specified port number by issuing: ./ServerGroupManager.sh -c -n -p
Note
In a Windows or UNIX load-balanced environment, the PushConfigUpdates script must be run on each load-balanced server. Each Node must have its own ServerGroup.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 70
How to Install These procedures assume an Administrator has full administrative rights as either administrator or root. Upon creating an individual cluster node, the Blackboard services will need to be shutdown and restarted in order to reset the configuration with the new clustered node. P ro p e rt y
De s cr ip t ion
Cluster ID
Must be a unique name with no spaces between any of the letters. Best practice is to identify one naming convention for all nodes and increment numerically to differentiate servers and nodes. Example: Blackboard1 or Blackboard2.
Server Shutdown Port
Must be a unique port in order to connect to the JVM for the clustered node and shut it down. By default the primary application server installed with Blackboard runs on port 8005, therefore a new value must be supplied to avoid port socket contention. Best practice is to increment the current server shutdown port by 1000.
JK Connector Port
Must be a unique port in order for the web server to communicate to each clustered node. The default port is 8009. Best practice is to increment the current jk connector port by 1000.
Cluster Listener Port
Must be a unique port for the cluster to replicate session information across the wire. The default port is 4000. Best practice is to increment the current listen port by 1000.
Installing in Windows: 1.
Launch the Install Cluster script by running the InstallCluster.batfile. After running the file, you will be prompted for the following information. Configure the settings according to the previous table. a. Cluster ID. b. Server shutdown port. c. JK Connector port. d. Cluster Listener port.
2.
The cluster is now created.
3.
Stop your server by running ServiceController.bat services.stop
4.
Start your server by running ServiceController.bat services.start
Installing in UNIX: 1.
Launch the Install Cluster script by issuing ./InstallCluster.sh After running the command, you will be prompted for the following information. Configure the settings according to the previous table. a. Cluster ID. b. Server shutdown port.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 71
c. JK Connector port. d. Cluster Listener port. 2.
The cluster is now created.
3.
Stop your server by issuing ./ServiceController.sh services.stop
4.
Start your server by issuing ./ServiceController.sh services.start
5.
Run the jps command from your JAVA_HOME to see the bootstrap processes. You should see one Tomcat Process, and the number of Cluster Process IDs.
Tip
UNIX customers should increase the Apache MaxClients value as they add nodes. Blackboard recommends multiplying the initial value by the number of total JVMs. For example, if MaxClients is 500 for a non-clustered configuration, when 2 JVMs are added, this setting should increase to a minimum of 1500.
Files that are Affected After a cluster is installed, there are a number of files and directories that are produced. The following table highlights some of these files and directories. Di re ct o r y o r F il e
De s cr ip t io n
/apps/tomcat/ cluster/
A new directory that is created when the first node (other than root) is installed.
/apps/tomcat/c luster/
A new directory that is created for every node added. Each directory contains files affecting that node: …/conf/server.xml and log files.
/apps/tomcat/ conf/jk/workers.proper ties
This file exists before adding a node but changes whenever a node is added to include load-balancing information for that node. For more information about the workers.properties file, see http://tomcat.apache.org.
server.xml
A file that allows you to configure Tomcat nodes through the use of XML descriptors.
Troubleshooting Installation Issues This topic contains three steps to take if the Tomcat Cluster is not functioning as expected. 1.
Check that the following value is present and set to true in the bb-config.properties file located in /config: bbonfig.tomcat.enable=true If it is set to false, then run PushConfigUpdates.bat to change. For more information, see Before installing a cluster.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 72
2.
Check that the workers.properties file contains the correct information for all of the nodes installed in the cluster. For more information about the workers.properties file, see Files that are affected.
3.
Watch the Java processes running on your application server. There should be a Java process running for each node installed and one for the root node. CPU processing should be distributed across the nodes.
Cache Replication By default Blackboard Learn will install with cache replication in a cluster disabled. To enable replication, you must manually configure the setting and restart your application servers. Replication in Windows: 1.
Go to the Blackboard Learn home, \config\internal/
2.
Open the ehcache.xml file.
3.
Search for the two cacheManagerxxx elements, and remove the comments.
4.
Additional information is located within the ehcache.xml file, specific to the elements.
5.
Stop your server by running ServiceController.bat services.stop
6.
Start your server by running ServiceController.bat services.start
Replication in UNIX: 1.
Go to the Blackboard Learn home, /config/internal/
2.
Open the ehcache.xml file.
3.
Search for the two cacheManagerxxx elements, and remove the comments.
4.
Additional information is located within the ehcache.xml file, specific to the elements.
5.
Stop your server by issuing ./ServiceController.sh services.stop
6.
Start your server by issuing ./ServiceController.sh services.start
After restarting, all caches which are marked as bbconfig.cache.(cachename).needsclusterinvalidation=true in cachesettings.properties will send invalidation notifications to all nodes in the system when entries are removed/flushed/updated.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 73
Removing a Cluster Node These procedures assume an Administrator has full administrative rights as either administrator or root. Upon removing an individual cluster node, the Blackboard services will need to be shutdown and restarted in order to reset the configuration without the clustered node. Removing in Windows: 1.
Go to \tools\admin
2.
Stop your server by running ServiceController.bat services.stop
3.
Launch the Remove Cluster script by running RemoveCluster.bat
4.
Specify the cluster to be deleted, when prompted.
5.
Start your server by running ServiceController.bat services.start
Removing in UNIX: 1.
Go to /tools/admin
2.
Stop your server by issuing ./ServiceController.sh services.stop
3.
Launch the Remove Cluster script by issuing ./RemoveCluster.sh
4.
Specify the cluster to be deleted, when prompted.
5.
Start your server by issuing ./ServiceController.sh services.start
6.
Verify the cluster was successfully removed by running the jps command from your JAVA_HOME to see the bootstrap processes.
Best Practices For information about optimizing Blackboard Learn to perform best in a particular environment, see Blackboard Learn Performance Optimization Guide.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 74
Operating System and Database Maintenance Overview Blackboard supports operating system and database service packs and security patches for the operating systems and databases supported for use with Blackboard Learn, and Blackboard Learn - Basic Edition. Blackboard will test, certify, and, if necessary, provide fixes to ensure that Blackboard systems work with service packs and security patches. There is, necessarily, a short lag time between a service pack release and the completion of testing. Even during this interim testing period, however, Blackboard will provide support for just released operating system and database service packs and security patches. Note
This policy does not include support for subsequent releases. For example, if Blackboard supports version 1 of a database system any security patches or service packs for version 1 will be supported.
Blackboard will not support a version 2 release of the same database system until that version has been properly tested and published as part of the software requirements for that release of the Blackboard system.
Applying a Service Pack or Security Patch after Installing Blackboard Learn Follow these steps to install a service pack or a security patch to the operating system or database. 1.
Back up the system.
2.
Shut down Blackboard Learn.
3.
Contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com to check for any prerequisite maintenance that may be required to ensure compatibility with an OS or DBMS service pack or security patch.
4.
Apply the operating system or database service pack or Security patch to the test/development environment.
5.
Restart the test/development server.
6.
Ensure that system is still shutdown. If auto start mechanisms are configured to restart Blackboard after a server restart, remember to shut down the Blackboard system before continuing.
7.
Apply any necessary Blackboard prerequisite maintenance to the test/development Blackboard systems.
8.
Restart the Blackboard systems.
9.
Check the results either by testing your critical path features or by running your verification procedures.
10.
If results are satisfactory, back up the system again. (If not, please log a service request with Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com describing the failure.)
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 75
Backup and Recovery Overview This topic offers some tips on system-wide backups and describes the tools in Blackboard Learn for incrementally backing up Courses and Organizations.
System backup and recovery System administrators should backup the database and file system according to the needs of the Institution. Blackboard Learn supports full backup and restores at the operating system and database levels. As a general rule, daily backups should be kept for two weeks, as errors may not appear for several days. Recovery plans should include how to restore the entire system. For assistance restoring the system, contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com.
Incremental data protection Blackboard Learn includes the following utilities for incrementally backing up individual Courses and Organizations. Export/Import: Export takes Course content and puts it in a package that can be used in another Course at a later date. One or more Course areas can be included in the package. Archive/Restore: The Archive Course function creates a record of the Course including user interactions. It is most useful for recalling Student performance or interactions at a later time. The archive package is saved as a .ZIP file that can be restored to the system at another time. The command line tool that processes batch operations for Export/Import and Archive/Restore is a powerful tool for backing up Course and Organization data. For detailed information on using these utilities, see the Blackboard Learn Administrator Manual. Note
If attempting to import a file over the size of 250 MB, the command line must be used rather than a web browser. If it is necessary to increase the maximum upload limit, modify the parameter located in webapps/blackboard/WEBINF/config/struts/reporting-struts-config.xml. The file size upload limit is tied to Tomcat, therefore it is not encountered with WebDAV uploads. Because the setting is tied to Tomcat, the services must be restarted for the change to take effect.
Avoiding Recovery of Files During Upgrade During a Blackboard Learnupgrade, items such as custom folders, and archived snapshots which are stored directly beneath the directory are moved to a time-stamped backup directory. Customized files and folders which are not Blackboard-owned will be considered unexpected and moved to the backup directory. To avoid your customized non-Blackboard-owned files from being moved during an upgrade, create client-dirs.txt and client-files in your config directory. List each file and folder's relative path to your directory on its own line in the respective text file. The files do not accept wildcards, so the files and folders must be specified individually. This method must be used with caution to avoid a partially upgraded environment, and if the file is Blackboardowned and customized it will still be overwritten with the new version.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 76
Command Line Tools Overview Blackboard Learn includes a set of system administration tools that must be run from the command line. Trying to execute a utility by clicking the .bat file in the Windows GUI will return errors and possibly cause the system to stop functioning. This topic covers each tool and the syntax to invoke the tool. All of the commands described in this topic are found in the /tools/admin directory.
PurgeAccumulator Every 30 days an automatic process runs that synchronizes the data in the stats database with the data in the main database and then deletes the statistical data from the main database that is more than 30 days old. This process can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can also be used to delete data from the statistics database. Windows Syntax: PurgeAccumulator.bat UNIX Syntax: PurgeAccumulator.sh Ar g um en t
De s cr ip t io n
purge-live – Takes data from Blackboard Learn database and syncs with tables in the statistics database. After synching, it purges statistical data in the main database that is older than the number of days or date set. purge-stats – Goes to stats DB and purges all data older than the last x days or older than a specific date.
Enter the name of the main database (bbuid) of the database to be purged.
The number of days (from the current date) that should not be processed by the PurgeAccumulator tool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will be purged.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 77
PushConfigUpdates This tool updates the configuration according to the settings in the bb.config.properties file. Running this command will redeploy all of the properties files. If any customizations have been made to the properties files, they will be lost. The PushConfigUpdates command has been enhanced to improve system management. Now, the PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database. Running this tool always restarts the services to reflect the changes. The first operation of this tool will replace the existing template files, copying the original template files to a time-stamped sub-directory of /backups/templates/. Use these files to retrieve and re-apply any local customizations. The second operation of this tool is Tomcat specific and requires that Custom Authentication be disabled to successfully complete this operation. The .jar files from apps/tomcat//lib/directories will be loaded rather than from /systemlib/. Be aware that any .jar file found in the directory will be loaded at Tomcat startup. This operation is controlled by the .classpath files located in config/tomcat/classpath. Any changes to the Tomcat configuration files or startup scripts must be made to the templates in the config/tomcat/ directory, in particular this applies to additional MIME types added to the web.xml file. Touch points are files such as web.xml, server.xml, startup scripts, and configuration files used in clustered Tomcat environments. The third operation updates the BBLEARN.SYSTEM_REGISTRY (legacy: BB_BB60.SYSTEM_REGISTRY) database table with the configuration changes. The current performance parameters for the Application server are recorded in the BBLEARN_ADMIN.CONFIG.REGISTRY (legacy: BB_BB60_ADMIN.CONFIG.REGISTRY) database table. The final operation configures content management, which includes license verification, connection information update, then pushing the new information to the database. The version of each database schema is then checked and updated if necessary. Windows Syntax: \tools\admin\PushConfigUpdates.bat UNIX Syntax: /tools/admin/PushConfigUpdates.sh When using the PushConfigUpdates tool in Windows, it is very important that the tool is run on the command line rather than double-clicking the file from windows explorer. The command line will execute the tool in verbose mode, displaying important messages.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 78
RotateLogs This tool processes a log rotation outside the scheduled log rotations configured through the Manage Log Rotation page. The tool stops all necessary services and starts the services after the rotation is finished. Windows Syntax: \tools\admin\RotateLogs.bat UNIX Syntax: /tools/RotateLogs.sh This command does not take any arguments. If logs are manually rotated using this tool it will not interrupt the regular intervals. However, the logs that were rotated manually will not be included in the archive files created at the regularly scheduled rotation. For example, if the log rotation is set at 30 days and the logs are manually rotated after 15 days, only the last 15 days of logs will be included in the archives at the next scheduled log rotation. For more information about managing logs, see the Blackboard Learn Administrator Manual.
ServiceController This tool is used to start and stop services. Windows Syntax: \tools\admin\ServiceController UNIX Syntax: /tools/admin/ServiceController An error may occur when running this tool if a symbolic link in /bin to the correct location of the bash shell does not exist. Run the following command to create this link: ln –s /bin/bash /usr/local/bin/bash This assumes that bash resides in /usr/local/bin/bash. If it resides elsewhere, please use that path when creating the symbolic link. Ar g um en t
De s cr ip t io n
services.start
Starts all the services related to Blackboard Learn.
services.stop
Stops all the services related to Blackboard Learn.
services.restart
Stops and immediately starts the services related to Blackboard Learn.
services.appserver.start
Starts the bb-tomcat service.
services.appserver.stop
Stops the bb-tomcat service.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 79
Ar g um en t
De s cr ip t io n
services.appserver.restart
Stops and immediately starts the bb-tomcat service.
services.webserver.start
Starts the IIS or Apache Web service.
services.webserver.stop
Stops the IIS or Apache Web service.
services.webserver.restart
Stops and immediately starts the IIS or Apache Web service.
SystemInfo This command will create a detailed report of system settings. The report can be viewed in the //logs/system-info directory. The name of the report will be named yyyymmdd_OS.log. Where OS is the operating system and yyyymmdd is the date in year-month-day format. Windows Syntax: \tools\admin\SystemInfo.bat UNIX Syntax: /tools/admin/SystemInfo.sh
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 80
Using a Proxy Server Overview Some Institutions require an outbound proxy server to comply with government regulations or Institution practices. Blackboard Learn allows the use of an outbound proxy server to secure communications. In particular, the proxy server works with Course Cartridge downloads and RSS feeds incorporated into community modules.
Configure the Proxy Server, UNIX Follow these steps to configure Blackboard Learn to use an outbound proxy server. 1.
Install the proxy server according to the Institution standards.
2.
Open the //config/bb.config.properties file.
3.
Add the domain name or IP address of the proxy server to the bbconfig.webserver.ouboundproxyurl property.
4.
Save the file.
5.
Run the PushConfigUpdates command to finalize the setting.
Configure the Proxy Server, Windows Follow these steps to configure Blackboard Learn to use an outbound proxy server. 1.
Install the proxy server according to the Institution standards.
2.
Open the C:\\config\bb.config.properties file.
3.
Add the domain name or IP address of the proxy server to the bbconfig.webserver.ouboundproxyurl property.
4.
Save the file.
5.
Run the PushConfigUpdates command to finalize the setting.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 81
Content Management Administration Overview This section describes how to initially set up and manage the content management capabilities of Blackboard Learn.
In this Section This section includes the following topics. T opic
De s cr ip t io n
Introduction to Content Management Administration
This topic provides an overview of managing the content management capabilities.
Turn on the Content Collection
This topic describes how to setup the Content Collection after installing the content management capabilities.
Configuration Changes
This topic provides information about configuration options.
Command Line Tools
This topic covers the utilities that are available from the command line.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 82
Introduction to Content Management Administration Overview The Content Collection is in a “disabled” mode after installation. This gives the Administrator a chance to configure and configure the Content Collection before making it publicly available for all to access. The Content Collection is very flexible and has numerous options. This section covers the basic steps Administrators that need to get started. Detailed information about administering the Content Collection is located in the Blackboard Learn Administrator Guide.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 83
Turn on the Content Collection Overview Turn on the Content Collection and appropriate Tools and Features. If Portfolios are enabled, select which roles may use this feature. Turn on the Content Collection and its features from: Administrator Panel>Content Management Settings>Enable/Disable Features and Tools
Enable SSL Authentication for Web Folders (also known as WebDAV) occurs in plain text. Blackboard strongly recommends running SSL. If SSL is not used, authentication may be compromised. For more information, see Setting Up SSL.
Set up the Portal This section is relevant only for clients who license the community engagement capabilities of Blackboard Learn. Follow the steps below to set up the Portal: 1.
If Portal Direct Entry is enabled, disable the Content Collection for Guests and any other roles that should not use it, such as Prospective Students and (Undefined variable: BbVariables_AS.plural observer)Administrator Panel>Manage Tabs > Modify>Tab Properties
2.
Select Properties next to each Content Collection module then set the System Availability of the module.
3.
Enable Content System Portal Modules. These include: Bookmarks, Course Content, (Undefined variable: BbVariables_AS.institution content), My Content, My Portfolios, (Undefined variable: BbVariables_AS.organization content), Search Content System, and Workflow Activities. Administrator Panel>Manage Modules>Properties (next to each Content System Module)
Configure Content Management Settings The following steps explain which Settings must be initially configured: 1.
Set up Virtual Hard Drives for users. This determines which roles have folders available in the users directory. The quota for these folders is setup in Default Folder Settings. Administrator Panel>Virtual Hard Drive
2.
Select the availability of virtual hard drives. If virtual hard drives are made available, select for which roles folders are created.
3.
Set up Default Folder Settings. This determines which folders will be created by default in the Content Collection, such as Course folders within the Courses directory for users with specific roles. It also allows the Administrator to set a quota for user folders. Administrator Panel>Settings>Default Folder Settings >Manage
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 84
4.
Select Manage next to each top level folder. Set the permissions and default quotas for each top level folder. These options for top level folders may be changed in the future, BUT changes will only affect new folders created.
5.
Set up Privacy Settings, this determines whether the Content Collection respects the user’s privacy. Users have the option of choosing whether or not their user information is made public in the User Directory of the Blackboard Learn. The Privacy Settings page allows Administrators to determine whether these privacy settings chosen by users will be respected during user searches of the Content Collection. Administrator Panel>Settings>Privacy Settings
6.
Enable the Deletion Audit Trail for the Document Stores. This setting tracks how long files will remain in the system before being permanently deleted. This log is stored in the database; the lifetime may be set fairly high without affecting system performance. Administrator Panel>Technical Settings>Document Stores>Manage>Deletion Audit Trail Settings
7.
Turn on the Deletion Audit Trail for each Document Store by entering the number of days for the Delete Audit Trail Lifetime.
8.
Enable persistent cookies. Using persistent cookies increases the usability of WebDAV; users will not be asked to authenticate multiple times. Administrator Panel>Technical Settings>Authentication Properties
Configure Full Text Search Configure full text search indexing options. This sets the time of day and the duration for the system to rebuild the Full Text Search Indexes. It is recommended that option be set to a minimum of one hour. Administrators may also choose to use the Immediate Update option, which will update the index as files are added to the system. This setting may impact performance. Administrator Panel>Technical Settings>Full Text Search Settings If the system has automated backup, check that the settings on the Full Text Settings page do not interfere with the backup.
Configure Display Options The Display Options allow the Administrator to set up how the Content Collection appears to users. Administrator Panel>Content System Display Options The following areas must be configured in Display Options: •
Content List Display Options – Set which features are available in the Action Bar, such as Add Folder and Copy. Determine which columns will appear, such as Display Size and Display Permissions.
•
Menu Display Options – Choose how the left-hand navigation menu appears to users.
•
Manage Shortcut View – Customize the appearance of the Shortcut View.
•
Manage Folder View – Customize the appearance of the Folder View.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 85
Enable Content Management Features Follow the steps below to enable some of the features available in the Content Collection: 1.
Make Portfolios available on the system. Select which roles have access to this functionality. Administrator Panel>Portfolios>Portfolio Settings
2.
Modify Portfolio Templates to suit the Institution and make them available. Administrator Panel>Portfolios>Portfolio Templates
3.
Set the availability of eReserves. Administrator Panel>eReserves
4.
Enable Web Folders. Administrator Panel>WebFolders
5.
Enable the availability of the Learning Objects Catalog. Administrator Panel>Learning Objects Catalog>Catalog Availability
6.
Select Catalog Managers. Administrator Panel>Learning Objects Catalog>Catalog Management Options
Enable Content System Features in Courses Follow the steps below to enable Content System features available in Blackboard Learn Courses: 1.
Allow Instructors to check links to Content System items within a Course. Set the Check CS Links tool to Available. Administrator Panel>Course Settings>Course Tools
2.
Allows Instructors to copy files from a Course to the Content Collection. Set the Copy Files to CS tool to Available. Administrator Panel>Course Settings>Course Tools
Access the Content Collection Once enabled, the Content Collection Tab will appear when a user logs into Blackboard Learn. The Administrator may access the Content Collection through this tab or through the Manage Content option on the Administrator Panel.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 86
Configuration Changes Overview Administrators who are running the Blackboard Learn may make changes to the system configuration. If content management is installed, the Administrator must also update the configuration in the Blackboard Learn. This is done using the push-cs-config-update tool. There are no parameters for this tool. The following are examples of when this command is used: •
The content management database password is changed
•
The database server name is changed
•
The location of Java SE is modified
•
The Web Server Hostname is changed
•
The Web Server Port is changed
•
Database username and password are modified
•
Blackboard Basedir is changed
Configure the System Follow the steps below to make changes to the system configuration: 1.
Update the \blackboard\config\bb-config.properties file.
2.
Update the \blackboard\apps\bbcms\config\bbcms-install.properties file. This step is only necessary if one of the following properties is updated: License Key Content Management database password
3.
Run \blackboard\apps\bbcms\bin\push-cs-config-update.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 87
Command Line Tools Overview Blackboard Learn includes a set of system administration tools that must be run from the command line. Trying to execute a utility by clicking the .bat file in the Windows GUI will return errors and possibly cause the system to stop functioning. This topic covers each tool and the syntax to invoke the tool. All of the commands described in this topic are found in the /tools/admin directory.
PurgeAccumulator Every 30 days an automatic process runs that synchronizes the data in the stats database with the data in the main database and then deletes the statistical data from the main database that is more than 30 days old. This process can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can also be used to delete data from the statistics database. Windows Syntax: PurgeAccumulator.bat UNIX Syntax: PurgeAccumulator.sh Ar g um en t
De s cr ip t io n
purge-live – Takes data from Blackboard Learn database and syncs with tables in the statistics database. After synching, it purges statistical data in the main database that is older than the number of days or date set. purge-stats – Goes to stats DB and purges all data older than the last x days or older than a specific date.
Enter the name of the main database (bbuid) of the database to be purged.
The number of days (from the current date) that should not be processed by the PurgeAccumulator tool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will be purged.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 88
PushConfigUpdates This tool updates the configuration according to the settings in the bb.config.properties file. Running this command will redeploy all of the properties files. If any customizations have been made to the properties files, they will be lost. The PushConfigUpdates command has been enhanced to improve system management. Now, the PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database. Running this tool always restarts the services to reflect the changes. The first operation of this tool will replace the existing template files, copying the original template files to a time-stamped sub-directory of /backups/templates/. Use these files to retrieve and re-apply any local customizations. The second operation of this tool is Tomcat specific and requires that Custom Authentication be disabled to successfully complete this operation. The .jar files from apps/tomcat//lib/directories will be loaded rather than from /systemlib/. Be aware that any .jar file found in the directory will be loaded at Tomcat startup. This operation is controlled by the .classpath files located in config/tomcat/classpath. Any changes to the Tomcat configuration files or startup scripts must be made to the templates in the config/tomcat/ directory, in particular this applies to additional MIME types added to the web.xml file. Touch points are files such as web.xml, server.xml, startup scripts, and configuration files used in clustered Tomcat environments. The third operation updates the BBLEARN.SYSTEM_REGISTRY (legacy: BB_BB60.SYSTEM_REGISTRY) database table with the configuration changes. The current performance parameters for the Application server are recorded in the BBLEARN_ADMIN.CONFIG.REGISTRY (legacy: BB_BB60_ADMIN.CONFIG.REGISTRY) database table. The final operation configures content management, which includes license verification, connection information update, then pushing the new information to the database. The version of each database schema is then checked and updated if necessary. Windows Syntax: \tools\admin\PushConfigUpdates.bat UNIX Syntax: /tools/admin/PushConfigUpdates.sh When using the PushConfigUpdates tool in Windows, it is very important that the tool is run on the command line rather than double-clicking the file from windows explorer. The command line will execute the tool in verbose mode, displaying important messages.
RotateLogs This tool processes a log rotation outside the scheduled log rotations configured through the Manage Log Rotation page. The tool stops all necessary services and starts the services after the rotation is finished.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 89
Windows Syntax: \tools\admin\RotateLogs.bat UNIX Syntax: /tools/RotateLogs.sh This command does not take any arguments. If logs are manually rotated using this tool it will not interrupt the regular intervals. However, the logs that were rotated manually will not be included in the archive files created at the regularly scheduled rotation. For example, if the log rotation is set at 30 days and the logs are manually rotated after 15 days, only the last 15 days of logs will be included in the archives at the next scheduled log rotation. For more information about managing logs, see the Blackboard Learn Administrator Manual.
ServiceController This tool is used to start and stop services. Windows Syntax: \tools\admin\ServiceController UNIX Syntax: /tools/admin/ServiceController An error may occur when running this tool if a symbolic link in /bin to the correct location of the bash shell does not exist. Run the following command to create this link: ln –s /bin/bash /usr/local/bin/bash This assumes that bash resides in /usr/local/bin/bash. If it resides elsewhere, please use that path when creating the symbolic link. Ar g um en t
De s cr ip t io n
services.start
Starts all the services related to Blackboard Learn.
services.stop
Stops all the services related to Blackboard Learn.
services.restart
Stops and immediately starts the services related to Blackboard Learn.
services.appserver.start
Starts the bb-tomcat service.
services.appserver.stop
Stops the bb-tomcat service.
services.appserver.restart
Stops and immediately starts the bb-tomcat service.
services.webserver.start
Starts the IIS or Apache Web service.
services.webserver.stop
Stops the IIS or Apache Web service.
services.webserver.restart
Stops and immediately starts the IIS or Apache Web service.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 90
SystemInfo This command will create a detailed report of system settings. The report can be viewed in the //logs/system-info directory. The name of the report will be named yyyymmdd_OS.log. Where OS is the operating system and yyyymmdd is the date in year-month-day format. Windows Syntax: \tools\admin\SystemInfo.bat UNIX Syntax: /tools/admin/SystemInfo.sh
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 91
Setting Up SSL Overview This section reviews how to use the Secure Sockets Layer (SSL) protocol to secure communication between a Blackboard Learn Web/app server and a client machine. SSL Offloading is not currently supported.
In this Section This section includes the following topics. T opic
De s cr ip t io n
About SSL and SSL Choice
This topic introduces SSL and Blackboard Learn feature, SSL Choice, that lets Administrators select which areas of the system are secured with SSL.
Configure SSL for IIS
This topic gives detailed instructions for configuring IIS to use the SSL protocol. This must be done before using the SSL Choice feature.
Configure SSL for the Collaboration Tool, Windows
This topic provides instructions for securing Collaboration Tool communications over SSL when the server is running Windows.
Configure SSL for Apache
This topic gives detailed instructions for configuring Apache to use the SSL protocol. This must be done before using the SSL Choice feature.
Configure SSL for the Collaboration Tool, UNIX
This topic provides instructions for securing Collaboration Tool communications over SSL when the server is running a UNIX operating system.
SSL Choice
This topic reviews the SSL Choice feature available through the user interface.
Note
If using a self-signed certificate, the certificate must be added to the list of allowed certificates on the client machine. If this is not done, the multi-upload will fail, as will a few other features which use SSL.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 92
About SSL and SSL Choice Overview Secure Sockets Layer (SSL) is a protocol for protecting Internet communications. SSL ensures that a communication is not read or changed by another entity. Blackboard Learn uses SSL to secure all or some communications between the Web server and the client machine. This feature that allows Administrators to select which areas of Blackboard Learn are secured using SSL is called SSL Choice. Note
SSL may also be used to secure the connection between Blackboard Learn and a separate server for authentication (such as an Active Directory server). If SSL will be used both for connecting to an authentication server and for client sessions, SSL for the authentication server must be configured first. For more information on configuring SSL for securing with an integrated authentication server, see Authentication.
SSL Off-loading is not supported.
How Does SSL Work? SSL works through public key encryption. Transmissions are decrypted and encrypted using certificates. The steps below outline the process for establishing a connection over SSL: 1.
Client contacts the server with a list of encryption methods.
2.
The Server returns its certificate and a public key. These initial communications are scrambled with random data.
3.
Client validates the certificate.
4.
Client creates a secret string using an encryption method recognized by both the client and the server. The string is combined with the server's public key and sent back to the server.
5.
Both the client and server create session keys based on the secret string.
6.
The client sends a message to the server that it will now use the session key to encrypt and decrypt communications.
7.
The server responds that it will also use the session key.
8.
After each side confirms, the session keys are used to encrypt and decrypt communications during the session.
Obtain a Certificate The simplest way to obtain a certificate for use with a Web site is through a vendor known as a Certifying Authority (CA). The process, shown in the steps below, is relatively simple. 1.
Generate a certificate request.
2.
Send the request to a CA.
3.
The CA creates and registers a certificate.
4.
Make this certificate available to the Web Server (IIS or Apache).
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 93
Certificates created in this way are usually registered and good for one year. After one year the certificate will no longer work and a new certificate must be obtained.
How Does SSL Appear to Users? SSL works with the Hypertext Transfer Protocol (HTTP) to secure connections between Blackboard Learn Web server and the client machines. It is fairly easy to see when a Web page is using SSL to secure transmissions because an “s” is appended to the http at the beginning of the address. Without SSL: http://blackboard.yourinstitution.com With SSL: https://blackboard.yourinstitution.com It is important to understand that if SSL is used to secure the Web page in this example then the first URL (without SSL) is invalid and will return a 404 error.
SSL Choice The SSL Choice feature is available in the user interface from the System Control Panel. It allows an institution to decide if all, none, or some of Blackboard Learn is secured with SSL. If SSL is to be used, it is most effective when applied to the entire Web site and not just selected areas. Note
SSL must be configured on the Web Server before using the SSL Choice feature. If SSL Choice is turned on before the Web server is configured then any areas set to use SSL will be unavailable to users!
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 94
Configure SSL for IIS Overview To use SSL to secure Blackboard Learn the IIS Web server must first be set to use SSL. Configuring SSL should only be done by an experienced Microsoft System Administrator. Once SSL is configured, the SSL Choice feature (accessible from the Administrator Control Panel) will function correctly. Trying to use the SSL Choice feature before configuring SSL for Apache can result in serious system errors.
Configure SSL for IIS Follow these steps to configure SSL for the IIS Web server. 1.
Open the Internet Services Manager.
2.
Right-click on the blackboard_bblearn Web site and select Properties from the menu.
3.
Click the Directory Security tab.
4.
Click Server Certificate in the Secure communications frame at the bottom of the tab.
5.
The Web Server Certificate Wizard will appear. The Status of your Web server should report that there is not a certificate installed and there are no pending requests. If anything else appears, there may be a certificate installed or a pending request already. Click Next to advance.
6.
Select Create a new certificate and click Next to advance.
7.
Select Prepare the request now, but send it later and click Next to advance.
8.
Enter a name for the certificate (the name of the Web site in IIS is the default) and select a bit length from the drop-down list. Blackboard recommends a bit length of 1024. Click Next to advance.
9.
Enter the name of your Organization and your Organizational unit in the fields. This information is important to ensure that your certificate is unique and easily identified. Click Next to advance.
10.
Enter the Common name of the Web site. The host plus the domain name works best (example: blackboard_server.yourinstitution.edu). Click Next to advance.
11.
Enter the appropriate geographical information for your institution. Click Next to advance.
12.
Enter a file name for the certificate request or click Next to select the default and advance.
13.
Click Finish to create the certificate request.
14.
Send the certificate request to a Certifying Authority. There are several commercial vendors or you can sign your own if you have the capability. The output from the Certifying Authority will be a file with the extension .cer.
15.
Once you have obtained a .cer file, return to the Web Server Certificate Server as described in Steps 1-4.
16.
Select Process the Pending Request and click Next to advance.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 95
17.
Enter the location of the .cer file and click Next to advance.
18.
Click Next to advance through the summary steps (be sure to review the summaries to make sure you are installing the correct certificate!).
19.
Return to the Properties box for the blackboard_bblearn Web site as described in Steps 1 and 2.
20.
If the Web Site tab is not active, select it.
21.
Enter 443 for the SSL Port in the Web Site Identification frame at the top of the tab.
22.
Restart the server to complete the process.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 96
Configuring SSL for the Collaboration Tool, Windows Overview Setting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because the Collaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing the Collaboration Tool requires using a separate SSL certificate with Tomcat. Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool is not used to transmit sensitive data. It should also be noted that using SSL with the Collaboration Tool slows down performance of the tool. Consider both the need for security and the performance slow down associated with applying SSL before deciding to use SSL with the Collaboration Tool. As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that stores certificates. A self-signed certificate is a certificate created by you that is not submitted to a Certifying Authority. Note
Macintosh users running Netscape, Internet Explorer, or Safari may use self-signed certificates to configure SSL. A pop-up warning may appear during the process; select Continue to complete the process.
If users would prefer to use a signed certificate see the Java documentation on keytools for information on obtaining a signed certificate and including it in the keystore. In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing the Collaboration Tool. Certifying Authorities are used to prove to users of a Web site that the connection is secure and verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learn most likely do not require the validation of a third party before using the tool. The process for configuring SSL for the Collaboration Tool has two steps: 1.
Create a keystore.
2.
Configure Tomcat properties to use SSL encryption.
Load-Balanced Configurations The same certificate must be used on each server. For detailed instructions on how to install the same certificate on each server please consult Microsoft Knowledge Base article 310178 at http://support.microsoft.com/default.aspx?scid=kb;en-us;310178&Product-win2000) Services on each Web/application server must be restarted after changing the SSL Choice option.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 97
Create the Keystore After creation the keystore contains a self-signed SSL certificate specifically for Tomcat, . To create the keystore and certificate, follow these steps: 1.
Log on to the Web/app server as the user that runs Blackboard Learn.
2.
Run the following from the command line: %JAVA_HOME%\bin\keytool –genkey -storetype pkcs12 –alias tomcat – keyalg RSA –keystore The keystore will be created at the .
3.
The first prompt asks for a password for the keystore. The default password that Tomcat expects is "changeit”, but it is recommended that another password be used. Tomcat can be configured later to accept the new password.
4.
The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over SSL. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is: First and Last Name Organizational Unit Organization City or Locality State or Province Two-letter country code
5.
The last prompt asks for the password for the certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used.
6.
The keystore will be created in the specified directory.
Configure Tomcat to Work with the SSL Certificate After creating the keystore and certificate, the last step is to edit the blackboard\config\bbconfig.properties file. Follow these steps to edit the file to work with SSL: 1.
Make a backup of the following file: blackboard\config\bb-config.properties
2.
Keep it safe so that the original settings can be restored.
3.
Open the bb-config.properties file in Notepad or an XML editor.
4.
Find the following lines in the file and add the appropriate values. bbconfig.collabserver.keystore.filename= bbconfig.collabserver.keystore.password= bbconfig.collabserver.portnumber.ssl.default=8443 bbconfig.collabserver.keystore.type=PKCS12 The keystore.type must be set to PKCS12.
5.
Save the file.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 98
6.
Run the PushConfigUpdates tool.
7.
Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the certificate. After accepting the certificate, the Collaboration Tool will open and communications will be secured using SSL encryption.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 99
Configuring SSL for Apache Overview To use SSL to secure Blackboard Learn the Apache Web server must first be set to use SSL. Note
Successful completion of this process requires that Solaris users are running Solaris 10, Solaris 9, or Solaris 8 with patch 112438-02.
Configuring SSL should only be done by an experienced System Administrator. Once SSL is configured, the SSL Choice feature (accessible from the Administrator Control Panel) will function correctly. Trying to use the SSL Choice feature before configuring SSL for Apache can result in serious system errors.
Configure SSL for Apache The following steps detail how to configure SSL with Apache. 1.
Login to the Web/application server as root.
2.
Set the PATH to include the OpenSSL provided by Blackboard with the following commands: PATH=//apps/openssl/bin:$PATH export PATH
3.
Test that OpenSSL is in the PATH by executing openssl. If OpenSSL is set in the PATH correctly, an OpenSSL> prompt will appear. Enter ‘q’ to exit the prompt. If another instance of openssl is installed on the operating system make sure that the version supplied by Blackboard is the version that appears in the PATH.
4.
Create a directory to store certificates. Then change directories. For example: mkdir //apps/httpd/conf/certs/ cd //apps/httpd/conf/certs/
5.
Create a RSA private key: openssl genrsa –out server.key 1024 where server is a variable for the file name. Typically the server name is used.
6.
Backup this file and make sure that only root has read permissions on it. Make sure that the password is secure and can be recalled when necessary. (need to recall to start the server).
7.
Create a Certificate Signing Request (CSR) for the server RSA private key with the following command: openssl req –new –days 365 –key server.key –out server.csr The –days option sets the expiration of the certification. Most Certifying Authorities will only sign a certificate for 1 year. At that time the certificate must be resigned.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 100
8.
View the details of the CSR with the following command: openssl req –noout –text –in server.csr When submitting the request, it may be necessary to view the file and copy text from it for submission to the Certifying Authority (CA).
9.
10.
Send the CSR to a Certifying Authority for signing. There are several commercial options available or you can sign your own if you have the capability. The output of either process is a server.crt file. Edit the //apps/httpd/conf/httpd.conf file to include the following directive: Include conf/ssl.conf
11.
Edit the //config/bb-config.properties file by modifying the following attributes, as shown below. SSLCertificateFile //server.crt SSLCertificateKeyFile //server.key
12.
Restart the server.
13.
The SSL Choice feature can now be used to select which areas of Blackboard Learn use SSL. For more information on using SSL Choice, please see SSL Choice.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 101
Configuring SSL for the Collaboration Tool, UNIX Overview Setting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because the Collaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing the Collaboration Tool requires using a separate SSL certificate with Tomcat. Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool is not used to transmit sensitive data. It should also be noted that using SSL with the Collaboration Tool slows down performance of the tool. Consider both the need for security and the performance slow down associated with applying SSL before deciding to use SSL with the Collaboration Tool. As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that stores certificates. A self-signed certificate is a certificate created by you that is not submitted to a Certifying Authority. Macintosh users running a Netscape or Internet Explorer browser will not be able to access the Collaboration Tool if a self-signed certificate is used to configure SSL. The Safari Web browser will work with a self-signed certificate. If there are Macintosh users running Netscape or Internet Explorer browsers then use a signed certificate. If a signed certificate is preferred, see the Java documentation on keytools for information on obtaining a signed certificate and including it in the keystore. In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing the Collaboration Tool and a self-signed certificate may be used. Certifying Authorities are used to prove to users of a Web site that the connection is secure and verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learn most likely do not require the validation of a third party before using the tool.
Configure the Collaboration Tool with a Self-signed Sertificate The process for configuring SSL for the Collaboration Tool has two steps: 1.
Create a keystore.
2.
Configure Tomcat properties to use SSL encryption.
Configure the Collaboration Tool with a Signed Certificate Clients who would like to use their existing SSL certificate should follow these steps. 1.
Convert the server.key and server.crt into a PKCS12 keystore using OpenSSL. openssl pkcs12 -export -out keystore.pkcs12 -in /path/to/server.crt -inkey /path/to/server.key
2.
This will prompt for a keystore password. The keystore will be created as keystore.pkcs12 in the current directory. Move this to an appropriate location.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 102
3.
Use the keystore and certificate in the steps below that cover editing the bbconfig.properties file so that Tomcat uses SSL.
Create the Keystore After creation, the keystore contains a self-signed SSL certificate specifically for Tomcat, . To create the keystore and certificate, follow these steps: 1.
Log on to the Web/app server as the user that runs Blackboard Learn.
2.
Run the following from the command line: %JAVA_HOME%\bin\keytool –genkey -storetype pkcs12 –alias tomcat – keyalg RSA –keystore The keystore will be created at the .
3.
The first prompt asks for a password for the keystore. The default password that Tomcat expects is "changeit”, but it is recommended that another password be used. Tomcat can be configured later to accept the new password.
4.
The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over SSL. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is: First and Last Name Organizational Unit Organization City or Locality State or Province Two-letter country code
5.
The last prompt asks for the password for the certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used.
6.
The keystore will be created in the specified directory.
Configure Tomcat to Work with the SSL Certificate After creating the keystore and certificate, the last step is to edit the /blackboard/config/bbconfig.properties file. Follow these steps to edit the file to work with SSL: 1.
Make a backup of the following file: /blackboard/config/bb-config.properties
2.
Keep it safe so that the original settings can be restored.
3.
Open the bb-config.properties file in an editor.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 103
4.
Find the following lines in the file and add the appropriate values. bbconfig.collabserver.keystore.filename= bbconfig.collabserver.keystore.password= bbconfig.collabserver.portnumber.ssl.default=8443bbconfig.collabs erver.keystore.type=PKCS12The keystore.type must be set to PKCS12
5.
Save the file.
6.
Run the PushConfigUpdates tool.
7.
Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the certificate. After accepting the certificate, the Collaboration Tool will open and communications will be secured using SSL encryption.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 104
SSL Choice Overview After IIS or Apache is configured to support SSL, then the communication between users and Blackboard Learn can be configured using the SSL Choice feature. SSL Choice allows Administrators to determine if none, all, or some of Blackboard Learn is secured with SSL. Note
If the SSL Choice is set to use SSL before SSL is configured in IIS or Apache Blackboard Learn will not be accessible! To ensure that users can always login, configure IIS or Apache for SSL prior to changing the security options on the SSL Choice page.
If planning on using SSL, Blackboard recommends enforcing SSL on the entire system. This ensures that all proprietary data is secured. If the choice option is chosen, it is important to update SSL settings whenever a new tool is enabled or a System Extension added.
Find this Page Click SSL Choice from the Security and Integration section of the System Control Panel.
SSL Choice Page Fields Fie ld
De s cr ipt io n
System-wide Disable SSL System-wide
Select this option and SSL will not be used to secure any of the communication between users and Blackboard Learn.
Enable SSL System-wide
Select this option and SSL will be used to secure all of the communication between users and Blackboard Learn.
Enable SSL for the following areas
Select this option to determine which areas of Blackboard Learn will be secured through SSL. Select the different areas from the check boxes on this page.
Specific Areas Select the check box for each area that should be secured using SSL. Tools Select the check box for each tool, tab, or Course content area that should be secured using SSL. Building Block Tools Select the check box for each Building Block that should be secured using SSL. Proxy Tools Select the check box for each Proxy Tool that should be secured using SSL. Web Services Select the check box for each Web Service that should be secured using SSL.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 105
Setting Up SIF Integration Overview This section reviews how to use SIF (School Interoperability Framework) to share data between a Blackboard Learn installation and other systems using the framework.
In this Section This section includes the following topics. T opic
De s cr ip t io n
About SIF
Describes SIF and its uses.
Configure the Blackboard SIF Agent
Provides instructions for connecting to a ZIS using the Blackboard SIF Agent.
Configure SSL for SIF
Provides instructions on securing communication between the ZIS and the SIF Agent.
Data Mapping
Matches the SIF data attributes to Blackboard data attributes.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 106
About SIF Exchanging and Synchronizing Data The School Interoperability Framework (SIF) is an industry initiative to develop a scalable solution for data exchange, synchronizing data entered in one system with the data in other systems within the SIF framework. A SIF implementation is a distributed networking system that consists of a Zone Integration Server (ZIS) and one or more SIF integration agents that communicate with the ZIS, all organized into a zone. The size of the zone is flexible and could consist of a single building, a school, a small group of schools, or a district. The ZIS is responsible for all access control and routing within the system. It provides integration services to all the agents registered with it so that the agents can subscribe to data changes that occur within the zone or publish data changes out into the zone. For example, if a user’s phone number is changed on one of the agent systems, the agent can publish this change to the ZIS, and any other agents that have subscribed to user information data changes will then receive the new phone number from the ZIS. In SIF, an agent never talks to another agent directly. Instead, an agent communicates with the ZIS which manages the connection to the other agent. By having the ZIS manage the routing responsibilities, complex communications can occur between agents that have no direct information about each other. The ZIS acts as the trusted intermediary that brokers the data exchange.
The Blackboard SIF Agent The Backboard SIF Agent registers with a ZIS and indicates the data Blackboard Learn can receive. ZIS tracks the data that the Blackboard SIF Agent can receive and forwards a message to the Blackboard SIF Agent if another agent has posted an applicable data change to the ZIS. The Blackboard SIF Agent conforms to SIF standards for receiving updates to user information data from the ZIS. It subscribes to data changes but does not publish data changes. SIF communication is automated. Once the Blackboard SIF Agent is configured, it automatically updates information when notification of a data change is received from the ZIS. The frequency of updates is configurable. Some important points about the Blackboard SIF Agent: •
The SIF Agent will not transmit information to the ZIS server, it will only receive information.
•
The SIF Agent will add, modify, or delete user records. It will not make changes to other data.
•
The SIF Agent is configured to listen for data from the ZIS at intervals using the Pull protocol.
•
The ZIS server owns the data sent according to the Blackboard Learn database. Ensure that this does not conflict with established integration solutions using Snapshot or the Blackboard integration APIs.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 107
Configure the Blackboard SIF Agent Overview The Blackboard SIF agent is installed with Blackboard Learn. Configuring the SIF Agent to receive information from the ZIS is accomplished by activating the Agent in the serviceconfig.properties file and editing the Agent properties in the bb-config.properties file.
Edit the service-config.properties File Edit //config/service-config.properties to activate the SIF Agent. Uncomment the following lines: ############################ SIF Service ################################blackboard.service.name.sifservice=blac kboard.platform.sif.SIFAgentServiceblackboard.service.impl.sifservice=b lackboard.platform.sif.SIFAgentServiceblackboard.service.sifservice.par am.config=config/bb-sif-agentconfig.xmlblackboard.service.sifservice.initlevel=17 Uncommenting these lines of code will cause the application to attempt to communicate with a ZIS server using the parameters defined in the bb-config.properties file.
Configure Settings in the bb-config.properties File Edit //config/bb-config.properties as follows: P ro p e rt y
De s cr ip t io n
bbconfig.sif.pull.frequency
Determines how often the SIF Agent will retrieve updates from the ZIS. This value is expressed in seconds.
bbconfig.sif.zone
Identifies the zone to which the SIF Agent subscribes.
bbconfig.sif.host
Identifies the ZIS server.
bbconfig.sif.port
The port used to listen for communication from the ZIS.
bbconfig.sif.protocol
This must be set to HTTP for an unencrypted connection or HTTPS to use SSL to encrypt communication between the ZIS and the SIF Agent.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 108
P ro p e rt y
De s cr ip t io n
bbconfig.sif.keystore
The keystore is a certificate used to identify the SIF agent. refers to the keystore file that our agent uses to identify itself (in the handshake process of the HTTPS protocol type connection, the ZIS will read this keystore from the agent and the agent will also read the ZIS’s self-identifying keystore).
bbconfig.sif.keystore.password
Password for the keystore.
bbconfig.sif.truststore
The truststore is a certificate used to identify trusted sources. refers to the keystore file that says who our agent trusts; this keystore file is created from importing the ZIS’s selfidentifying certificate, so that in the handshake process our agent can match the ZIS’s keystore with who we say we trust in our truststore file.
bbconfig.sif.truststore.password
Password for the truststore.
bbconfig.sif.authlevel
The SIF Authentication levels we set for bbconfig.sif.authlevel means the following to the ZIS receiving the connection message: 0- this agent is not sending a certificate to identify itself 1- this agent has a valid certificate to send to identify itself 2- this agent has a valid certificate to send to identify itself AND it got it from a source the ZIS trusts (trusted certificate authority) For level 0, the SIF Agent is not authenticating itself to the ZIS. In this instance, use the HTTP protocol to connect and do not set a keystore or a truststore. For levels 1 and 2, the HTTPS protocol must be used to connect and the keystore and truststore parameters set. When creating the keystore files, the ZIS must be configured to trust the agent’s certificate. This is done by importing the agent’s certificate into the ZIS’s “Trusted Agent Certificates” section. If the ZIS trusts the SIF Agent certificate, the agent will successfully connect to the ZIS on level 2 authentication because the selfidentifying keystore is one that the ZIS trusts. If the ZIS does not trust the agent’s certificate, then connection at level 2 would fail.
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 109
P ro p e rt y
De s cr ip t io n However, level 1 authentication level will still allow the agent to successfully connect to the ZIS if the ZIS were to not trust our agent’s certificate. This is because at level 1, the agent only needs a valid certificate to identify itself—the certificate does not have to be one that the ZIS trusts.
Example: ##################################################################### #################### SIF configuration settings ##################### ##################################################################### bbconfig.sif.pull.frequency=30000 bbconfig.sif.zone=Bb-SIF-Test bbconfig.sif.host=ZIS_SERVER.BLACKBOARD.EDU bbconfig.sif.port=7443 bbconfig.sif.protocol=https bbconfig.sif.keystore=//config/certs/SIFa gent.ks bbconfig.sif.keystore.password=changeit bbconfig.sif.truststore=//config/certs/Tr usted.ks bbconfig.sif.truststore.password=changeit bbconfig.sif.authlevel=2 Run PushConfigUpdates and verify the connection Run the PushConfigUpdates command to apply the changes. Note
The PushConfigUpdates command has been enhanced to improve system management. PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database.
UNIX //tool/admin/PushConfigUpdates.sh Windows: C:\\tool\admin\PushConfigUpdates The values in bb-config.properties will be written out to //config/bb-sif-agent-config.xml Check the log //logs/tomcat/sif-log.txt to verify the connection. 2009-08-12 17:29:35,833 DEBUG [ADK.Agent$Bb-SIF-Test] Polling for next message...2009-08-12 17:29:35,986 DEBUG [ADK.Agent$Bb-SIF-Test] Send SIF_SystemControl2009-08-12 17:29:35,987 DEBUG [ADK.Agent$Bb-SIF-
Blackboard Learn Server Administration Guide ©2010 Blackboard Inc. Proprietary and Confidential
Page 110
Test] MsgId: 7CDD8B1AA327B2F646030FDE3B72DC5F2009-08-12 17:29:35,989 DEBUG [ADK.Agent$Bb-SIF-Test] Sending message (646 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Expecting reply (489 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Received reply (489 chars)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] Receive SIF_Ack (Status = 9; Errors = 0)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] MsgId: 7166CC00636B004C4A81061B23E137A7200908-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] OrgId: 7CDD8B1AA227B2F646030FDE3B72DC5F2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] No messages waiting in agent queue
Sample bb-sif-agent-config.xml The example below defines the sif-agent-config.xml file. Please remember not to make any changes directly to this file, rather, edit the parameters in the bb-config.properties file and run PushConfigUpdates to make changes.
