Maplesoft MAPLE T.A. 5.0 SYSTEM ADMINISTRATOR GUIDE

Maple T.A. 5.0 System Administrator’s Guide

No part of this guide may be reproduced, stored in a retrieval system, or transcribed, in any form or by any means — electronic, mechanical, photocopying, recording, or otherwise. Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor. The software described in this document is furnished under a license agreement and may be used or copied only in accordance with the agreement. It is against the law to copy the software on any medium except as specifically allowed in the agreement.

Copyrights

Trademarks

Maple, Maple T.A., Maplesoft, and Waterloo Maple are all trademarks of Waterloo Maple Inc.

Tomcat is a trademark of The Apache Software Foundation.

Firefox is a registered trademark of the Mozilla Foundation.

Red Hat is a registered trademark of Red Hat, Inc.

Ubuntu is a registered trademark of Canonical Ltd.

SUSE is a registered trademark of Novell, Inc.

Microsoft, Internet Explorer, Windows, and Windows Vista are registered trademarks of Microsoft Corporation.

Macintosh, Mac OS, and Safari are trademarks or registered trademarks of Apple Computer Inc.

Java, all Java based marks, Sun, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Maplesoft is independent of Sun Microsystems, Inc.

All other brand names or product names are trademarks or registered trademarks of their respective companies.

Contents

Maple T.A. 5.0 System Administrator’s Guide 1

1 Introduction 1

1.1 Introduction 1

1.2 Terminology 1

2 Installation 2

2.1 Platform Prerequisite Hardware and Software 2

2.1.1 Summary 2

2.1.2 Server Platforms and Requirements 2

2.1.3 Client Platforms and Requirements 3

2.1.4 Ins talling Java 4

2.1.5 Ins talling PostgreSQL 5

2.1.6 Ins talling Tomcat 6

2.1.7 Providing an X Server under Linux a nd Solaris 8

2.2 Installing Maple T.A. 9

2.2.1 Information Requested by the Installer 9

2.2.2 Running the Ins taller 10

2.2.3 Changes Made by the Installer 10

2.2.4 Linux Consi derations 10

2.3 Verifying the Maple T.A. Installation 12

2.3.1 Mapl e T.A. Startup Smoke Test 12

2.3.2 Basi c Maple T.A. Functionality Test 12

2.4 Reinstalling Maple T.A. 13

3 Post-Installation Con figur ation Options 15

3.1 The System Admin User Interface 15

3.1.1 The System Admin Page 15

3.1.2 The System Settings Page 16

3.1.3 Usage Page 22

3.1.4 Active Users Page 25

3.1.5 Log Utility Page 25

3.2 Gradebook Paging and Scrolling 27

3.3 Gradebook Cell Formatting Options 27

4 Logging 28

4.1 How Maple T.A. Logs 28

4.2 Configuring Logging 28

4.3 The Default Log Level 28

4.4 Contents of th e Log Fil es 28

4.5 Dealing with the “Error listene rStart” Problem 30

5 Implementing SSL 31

6 Maple T.A. LDAP Authentication 34

6.1 Introduction 34

6.2 Requirements for Maple T.A. LDAP Authentication 34

6.3 Specifying Maple T.A. LDAP Authentication 36

6.4 Changing the Authentication Mode After Installation 36

6.5 Diagnostics 37

6.6 The Maple T.A. LDAP Authentication Mod el 37

6.7 Configuring Maple T.A. LDAP Authentication 38

6.8 Maple T.A. LDAP Configuration Examples 41

6.8.1 Simple OpenLDAP Single-Container 41

6.8.2 Simple OpenLDAP Single-Container with Anonymous Search 42

6.8.3 Simple OpenLDAP Multi-Container 43

6.8.4 Active Directory 43

6.8.5 Example of an Attribute Pars er 45

6.8.6 Example of Maple T.A. LDAP Over SSL 45

7 Applying Hotfixes 47

8 Sending Diagnostic System Snapshots to Maplesoft 48

9 Appendix A - Summary of Maple T.A. Configuration Files 49

10 Appendix B – Using the Tomcat Manager Facility 50

10.1 Basics 50

10.2 Installation 50

10.2.1 Windows 50

10.2.2 Linux 50

11 Appendix C – The Maple T.A. Data Model 51

11.1 Overview 51

11.2 Database Schema Summary 51

11.3 Course Content File Sy stem Structure 53

12 Appendix D - Using PostgreSQL Tools 55

1 Introduction

Notation

Folder

The PostgreSQL installation folder. On Windows, this is by default something like “C:\Program Files\PostgreSQL\8.3”. On Linux, the default location depends on the package used. For example, on Red Hat Enterprise 5.1 with the default yum install it is /var/lib/pgsql.

The Tomcat installation folder. On Windows, this is by default something like “C:\Program Files\Apache Software Foundation\Tomcat 6.0”. On Linux, the default location depends on the package used. For example, on Red Hat Enterprise 5.1 it is /usr/share/tomcat5 (for a Tomcat 5 installation).

The Maple T.A. installation folder. On Windows, this is by default something like “C:\Program Files\Maple T.A. 5.0”. On Linux, the default is to use the folder “Maple T.A. 5.0” with the same parent folder as <Tomcat> above.

1.1 Introduction

This guide has been written for IT professionals who install and support Maple T.A. systems in colleges and universities. It addresses installation, configuration and trouble-shooting. Its goal is to provide the information necessary to perform these tasks effectively and efficiently. This guide is not a “User’s

Guide”. In particular, it does not address the use of Maple T.A. for teaching and assessment. For that, refer to Maple T.A.’s help system.

1.2 Terminology

Throughout this document, we refer to several file system folders using a shorthand notation.

Platform

OS Versions

Minimum Requirements

Recommended Requirements

Windows

Windows 2000 Professional; Windows XP Professional; Windows 2003 Server; Windows Vista Business, Ultimate, or Enterprise

• Dual core CPU

• 2 GB RAM

• 20 GB hard drive space

• Dual core CPU

• 4 GB RAM

• 40 GB hard drive

space

Windows – 64-bit

Windows XP Professional; Windows Vista Business, Ultimate, or Enterprise; Windows 2008 Server

• Dual core CPU

• 2 GB RAM

• 20 GB hard drive space

• Dual core CPU

• 4 GB RAM

• 40 GB hard drive

space

2 Installation

2.1 Platform Prerequisite Hardware and Software

2.1.1 Summary

Maple T.A. is a Java-based Tomcat web application that uses a PostgreSQL database. Maple T.A. can run on Windows, Linux, and Solaris.

2.1.2 Server Platforms and Requirements

We recommend that Maple T.A. run on a dedicated server, which may be a stand-alone machine or a virtual machine. In particular, note the following restrictions:

1. No other web applications should be sharing Maple T.A.’s Tomcat container (except for

Tomcat’s administrative applications).

2. No web server other than Tomcat should be running on the machine.

3. The machine should not be providing any non-Maple T.A. services to other machines. It should

not be a database server, a file server, a DNS server, etc.

The following are the operating systems supported, minimum requirements, and recommended requirements for each platform:

Linux – 32-bit

SUSE 10.1, 10.2,

10.3,11.0,11.1 Red Hat Enterprise 5.0; Ubuntu 8.04

• Dual core CPU

• 2 GB RAM

• 20 GB hard drive space

• X window system or

xvfb configured

• Dual core CPU

• 4 GB RAM

• 40 GB hard drive

space

• X window system or

xvfb configured

Linux – 64-bit

AMD SUSE Enterprise 10,11;

Red Hat Enterprise 5.0; Ubuntu 8.04

• Intel 64

• 2 GB RAM

• 20 GB hard drive space

• X window system or

xvfb configured

• 4 GB RAM

• 40 GB hard drive

space

• X window system or

xvfb configured

Sun

Sun Solaris 9, 10

• 2 GB RAM

• 20 GB hard drive space

• X window system or

xvfb configured

• 4 GB RAM

• 40 GB hard drive

space

• X window system or

xvfb configured

There is no particular reason that Maple T.A. will not run on other Linux distributions and on other versions of the previously mentioned distributions, but your mileage may vary. The preceding distributions and versions are those that Maplesoft puts through its full QA process. Maplesoft Technical Support will assist on a best efforts basis with problems encountered on other Linux distributions and on other versions of the preceding distributions.

2.1.3 Client Platforms and Requirements

All clients require a Java-enabled browser. Javascript™ and cookies must be enabled. Instructors require Sun Java JRE 1.5 or later. Students require Sun Java JRE 1.4.2 or later.

All clients must have access to 56K modem dial-up connection. Broadband – Cable modem or DSL – Internet connection is recommended for optimal performance.

As of April 2008, the following are the operating systems supported, browsers supported, and hardware requirements for each client platform:

Platform

OS Version

Browsers

Hardware Requirements

Windows

Windows 2000, XP, 2003, Vista

Internet Explorer® 6.x+, Firefox 2.0+

• 300 MHz processor

or better

• 64 MB RAM or

better

Windows – 64-bit

Windows XP, Vista

Internet Explorer® 6.x+, Firefox 2.0+

• 300 MHz processor

or better

• 64 MB RAM or better

Macintosh

Mac OS/X 10.4.5 or later

Firefox 2.0+; Safari 1.2.1+

(new question editor not available on Safari)

• 333 MHz processor

or better

• 64 MB RAM or

better

Linux

SUSE 10.1, 10.2, 10.3,

11.0, 11.1; Red Hat Enterprise 5.0 ; Ubuntu 8.04

Firefox 2.0+

• 300 MHz processor

or better

• 64 MB RAM or

better

Linux-64-bit

SUSE 10 SUSE Enterprise 11 Red Hat Enterprise 5.0 Ubuntu 8.04

Firefox 2.0+

 300 MHz

processor or better

 64 MB RAM or

better

2.1.4 Installing Java

Maple T.A. requires Sun Java 5.0 or later. A Java Development Kit (JDK) or Java Runtime Edition (JRE) are each suitable. The smaller JRE is adequate.

Windows

 Download and install the latest Java Runtime Edition (JRE) from Sun’s Java SE site:

http://java.sun.com/javase/downloads.

Linux

 You will typically have several choices, including installing from binaries downloaded from

http://java.sun.com/javase/downloads and including packages from various sources, depending

on your Linux distribution. We recommend using a package that installs a recent version of Java 6 as a JRE.

As of Mar 2009, the most recent Java version available from Sun was 1.6.0_13.

After installation of Java, set your system-wide JDK_HOME or JRE_HOME environment variable, depending on whether you installed the JDK or JRE. These variables are set to the base of the Java

installation folder (the parent of the Java “bin” folder).

Under Windows, add Java’s bin directory to your System path. Under Linux, this should only be

necessary with a binary install, as package installs typically install the Java to be executable in such a way that it can be found through the system path.

2.1.5 Installing PostgreSQL

Maple T.A. requires PostgreSQL 8.1 or later.

Windows

1. Download and install the latest PostgreSQL from the PostgreSQL site:

http://www.postgresql.org/.

2. Select the “installer version”. Typically, that is a .zip file whose name does not end in “no-

installer.zip”.

3. You will be asked to provide a PostgreSQL administrative username and password. Record it;

you will want to use it during the Maple T.A. install.

Linux

1. You will typically have several choices, including installing from binaries downloaded from

http://www.postgresql.org/ and including packages from various sources, depending on your

Linux distribution. We recommend installing a package with a recent version of PostgreSQL.

2. Install pgadmin (the PostgreSQL GUI database explorer tool) if you have the option, and if you

plan to run a full X server (as opposed to the minimal server needed for Maple T.A., viz. xvfb).

3. A package install will often create an administrative user “postgres” without a password. You

will need an administrative user with a password for the Maple T.A. install. The easiest way to fix this is to create a password for the postgres user, with psql. Something like this will work on most Linux versions:

sudo su –c psql –U postgres

# alter user postgres password xxxxxxxx;

# \q

You may also be able to set the postgres password using “sudo pgadmin” if you have pgadmin installed.

As of Mar 2009, the most recent PostgreSQL version available from PostgreSQL was 8.3.7.

Verifying the PostgreSQL installation

A basic smoke test is enough. Just make sure you can log in with your superuser id (usually “postgres”)

with pgadmin or psql.

2.1.6 Installing Tomcat

2.1.6.1 Basic Tomcat Installation

Maple T.A. requires Tomcat 5.5 or later.

As of July 2008, the most recent Tomcat version available from Apache was 6.0.18.

Windows

 Download and install the latest Tomcat from the Tomcat site: http://tomcat.apache.org/.  Select the “Windows Service Installer”.  During the installation, you will be asked to select the features to install. Check the “Run Tomcat

as a service” feature. This will result in Tomcat running as a Windows Service (which provides automatic start and stop at system startup and shutdown). This will also place a Tomcat icon (a feather) in the System Tray. The tray icon is very handy for configuration tasks as well as for stopping and starting Tomcat manually.

Linux

 You will typically have several choices, including installing from binaries downloaded from

http://tomcat.apache.org/ and including packages from various sources, depending on your

Linux distribution. We recommend installing a package with a recent version of Tomcat.

2.1.6.2 Required Tomcat Configuration Changes

Maple T.A. requires two Tomcat configuration changes:

1. Internationalization — If you wish to use characters not found in the basic English alphabet you

need to set the Tomcat’s default text encoding to “UTF8” (a form of Unicode).

2. Performance and Scaling — All but the smallest Maple T.A. installations must run Tomcat with

more Java memory (“heap space”) than is allocated by default.

Configure these two items as follows:

Windows

1. Right click on the Tomcat System Tray icon.

2. Select “Configure”.

3. Select the “Java” tab.

4. Set “Initial memory pool” to 128 and “Maximum memory pool” to 512.

5. Under “Java Options” add the line:

-Dfile.encoding=UTF-8 .

Linux

Set the JAVA_OPTS environment variable for Tomcat as follows:

JAVA_OPTS=”-Duser.language=en -Dfile.encoding=UTF-8 -Xms128M -Xmx512M -XX:PermSize=64M XX:MaxPermSize=128M”

There are many ways to set this variable, depending on the distribution, including (but not limited to)

 /etc/default/tomcatx

 /etc/init.d/tomcatx  <Tomcat>/bin/catalina.sh  The.profile file for the user that runs the Tomcat daemon  The system .profile file

2.1.6.3 Verifying the Tomcat Installation

1. Browse to the Tomcat home page. For a localhost install with default port this is

http://localhost:8080. You should see an Apache Tomcat page with this text at the top:

If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!

The “x” will d epend on the version o f Tomcat.

2. Browse to the Tomcat Manager. From the Tomcat home page, click on the “Tomcat Manager”

link in the upper left. You will need to log in (See “Appendix B – Using the Tomcat Manager Facility”). That should take you to an Apache Tomcat page with this text at the top:

Tomcat Web Application Manager

2.1.7 Providing an X Server under Linux and Solaris

Under Linux and Solaris, Maple T.A. requires an X-Server to provide a graphics environment needed to render mathematical symbols and graphs.

The minimal way to accomplish this is with a virtual frame buffer. We recommend xvfb.

A simple implementation is to insert the following into /etc/init.d/tomcatx, preceding the invoking of catalina.sh:

/usr/bin/Xvfb :1 -screen 0 1024x768x8 &

export DISPLAY=:1

If you do not start Tomcat from an init.d script, then devise something similar that fits your approach.

2.2 Installing Maple T.A.

2.2.1 Information Requested by the Installer

The installer needs the following information for software already installed:

 <Tomcat> — This is your Tomcat installation folder.  The username and password for a PostgreSQL superuser. Usually this will be the “postgres”

user.

The installer needs the following information about your environment:

 Your time zone: be aware that Maple T.A. uses the time zone you provide at installation. The

default suggested at installation is the time zone used by your server. We recommend that you use that default. It is possible to specify a different time zone than that of the server but situations where that is required are extremely rare. We recommend that a single instance of Maple T.A. run on a dedicate server. In this recommended scenario, there is no reason that the server time zone should not be set to the value needed for Maple T.A. That is, there is no reason for the Maple T.A. and server time zones to be different.

 Details as to how you want Maple T.A. to send mail: server name, from address, authentication

credentials.

 Authentication through LDAP: if you want to authenticate through LDAP, configuration of the

LDAP interface is done post-install. You will not need to answer any questions on it during the install.

The installer will also ask you to provide names for created items.

 The pathname for the Maple T.A. installation folder. Under Windows , we recommend the usual

“Program Files” parent with the default “MapleT.A.5.0.” folder name. Under Linux, we recommend the parent folder of the Tomcat installation as the parent folder for Maple T.A. with the default “MapleT.A.5.0.” folder name.

 The name of a PostgreSQL database to be created for Maple T.A. We recommend the default

name, “mapleta”.

 A PostgreSQL username and password to be used by Maple T.A. to access PostgreSQL.  A Maple T.A. username and password to be used as the principal administrator. Note that for

LDAP installations, this username must be in LDAP, or you will not be able to log in with it.

2.2.2 Running the Installer

The installer is run in the typical way. See section 2.2.4 below for Linux considerations.

2.2.3 Changes Made by the Installer

When it is run, the installer:

1. Installs a Maple T.A. installation folder in the location you choose during installation

2. Deploys a mapleta Tomcat web application in Tomcat’s default webapps folder -

<Tomcat>/webapps

3. Adds a user to PostgreSQL

2.2.4 Linux Considerations

 The installer runs as an X application by default. Specify the ’console’ parameter to run it in text

mode.

 The installation must be run either as root (sudo) or under the user that runs the Tomcat

daemon (usually tomcat or tomcat5 or similar). This is required to ensure that the installer can assign the necessary permissions to the Maple T.A. installation files and folders.

 Ubuntu “Error listenerStart”. Ubuntu’s package installer may install Tomcat with so-called

“Tomcat Security” enabled. This is actually Java code security2. Ubuntu also installs Tomcat in a “multiple instances” fashion, one aspect of which is that the default webapps directory is

physically outside the Tomcat folder (usually it is installed as /var/lib/tomcat/webapps)3. The combination of these two things prevents Maple T.A. from functioning correctly. The symptom

is that the mapleta web application does not start. Tomcat’s catalina.log shows “Error listenerStart” followed by a message indicating that mapleta failed to start. The problem is

caused by the fact that Maple T.A. uses Hibernate, which uses cglib, which requires elevated privileges that are not available by default in the multiple -instances T.A. installation, and which are enforced by the Tomcat Security policy. The fix is to append the following configuration setting to <Tomcat>/conf/policy.d/04webapps:

grant codeBase "file:${catalina.base}/webapps/mapleta/-" {

permission java.security.AllPermission;

};

 Ubuntu java.lang.NullPointerException

at com.maplesoft.mathdoc.font.WmiFontResolver.getFontForCharacter(Unknown Source)

Tomcat Security is documented in the Tomcat User Guide, chapter “Security Manager”. See

http://tomcat.apache.org.

The Tomcat multiple instances model is described in the Tomcat Configuration Reference, chapter “The

Host Container”. See http://tomcat.apache.org.

This arises from the Ubuntu default Java setting java.awt.headless=true

Change this, in JAVA_OPTS in /etc/default/tomcatx, to java.awt.headless=false

 Various Linux distributions javax.xml.transform.TransformerFactoryConfigurationError: Provider

org.apache.xalan.processor.TransformerFactoryImpl not found

This can arise from incompatibilities between the versions of Java and Tomcat that are installed. Normally this can be fixed by adding the following to JAVA_OPTS (for example, in /etc/default/tomcatx if your installation has that file).

-Djavax.xml.transform.TransformerFactory= com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl

2.3 Verifying the Maple T.A. Installation

Before verifying the Maple T.A. installation, you should verify the Tomcat installation. See previous section 2.1.6 “Installing Tomcat”.

2.3.1 Maple T.A. Startup Smoke Test

1. Stop Tomcat.

2. Delete all of the log files in <Tomcat>/logs.

3. Start Tomcat.

4. Browse to your Maple T.A. home page. With installation defaults, this is

http://localhost:8080/mapleta.

5. Log in to Maple T.A. with the administrator credentials that you created during installation.

6. Stop Tomcat.

7. Inspect catalina.log. The smoke test “pass” criterion is that you should see no ERROR messages

and no exception stack traces.

2.3.2 Basic Maple T.A. Functionality Test

1. Log in to Maple T.A. with the administrator credentials that you created during installation.

2. You will see a page that displays a line labeled “Maple T.A. Demonstration Class”, under the

heading “All Active Classes”.

3. Click on the name “Maple T.A. Demonstration Class”.

4. You will see a page with a grid containing two assignments.

5. Click on “Demonstration of Question Types”.

6. You will see a 6-part “matching question” on triangle types. Click Next.

7. You will see a “drop-down question” on a calculus theorem. Click Next. Continue clicking Next

until you reach question 7.

8. Question 7 should display a 4-quadrant graph, in red. Click Next.

9. Question 8 is a multi-part question. Parts (a) and (b) should display integrals. The integral signs

should render in proper textbook style.

10. Quit the browser to abandon the test. If you made it this far and saw the items indicated above,

your installation has passed the basic functionality test.

2.4 Reinstalling Maple T.A.

The Maple T.A. installer will not overwrite an existing Maple T.A. database or an existing database user (as the admin user specified during installation). Therefore, to re install with the same names (the normal case) you need to remove these items. This procedure requires the use of PostgreSQL tools. See “Appendix D - Using PostgreSQL Tools” if you are not familiar with these tools.

The reinstallation steps are:

1. Undeploy Maple T.A. from Tomcat. a. Log in to the Tomcat Manager application (see “Appendix B – Using the Tomcat

Manager Facility “).

b. Click the mapleta “Undeploy” link. c. When Tomcat has completed the Undeploy, the mapleta entry will disappear from the

Application list in the Tomcat Manager display.

d. If the <Tomcat>/webapps/mapleta folder has not been completely removed by the

Undeploy, remove it manually.

2. Uninstall Maple T.A. a. Move the file <Maple T.A.>/license/license.dat to a temporary location. You will use it in

step 5.

b. Under Windows, use [Control Panel][Add/Remove Programs] to remove Maple T.A.

Under Linux, run the uninstall binary in the <Maple T.A.>/bin folder.

c. If the <Maple T.A.> installation folder has not been completely removed by the

uninstaller, remove it manually.

3. Remove the mapleta database from PostgreSQL. a. Using the pgAdmin tool:

i. Right click on the mapleta database node in the pgAdmin tree view.

ii. Select Delete/Drop.

b. Alternatively, using psql:

+ 42 hidden pages