Sakai 2.x Administrator's Guide

This is a single-page version of the Sakai 2.x Administrator's guide, which is intended to be more useful for printing and exporting the document in PDF format. To export in PDF format, click the PDF icon () that appears in the top right side of each Confluence page.

You can also view the guide in sections.

Introduction

This document covers the basics involved in moving from limited exploration of Sakai to something that can be used reliably by a larger group of users. The document will take as a given a working Sakai installation that uses the out of the box defaults.

This document assumes you have already been able to successfully install Sakai. It is also recommended that you take a moment to familiarize yourself with using the application before exploring the topics in this guide.

If you get stuck during the installation or configuration process, please start by searching this site and/or an archive of the sakai-dev list (such as gmane). If all else fails, join the Sakai developer list (sakai-dev) or the Sakai production list (production) and ask for help. For more information, see the "Joining the Community" section of this document.

The sakai.properties file

As mentioned in other areas, the sakai.properties file is a central configuration file that is typically stored in a sakai subdirectory relative to the tomcat home directory ([here are details on changing the default location]). All settings in the sakai.properties file are only read on startup, thus any changes you make will only take effect when you restart tomcat.

The sakai.properties file is a non-XML text file containing a series of key/value pairs that can be read using the load method of java.util.properties.

The first type of simple property (used to set booleans, simple strings, integers, etc.) is set simply by separating a key from a value with an equal sign, along the lines of:

Sakai makes use of hierarchical lists of property values, which require that you specify a "count" variable indicating the total number of values. The values themselves are defined by appending a number after each instance of the key. Here's an example:

Configuring the sakai.properties file

An option set in the sakai.properties file is only meaningful if one or more sections of the Sakai code base read and make use of the option and its configured value. There are at present over 250 configuration options used by portions of the Sakai 2.4 code base.

To assist users in setting the most important of the options, an example sakai.properties file is included with the Sakai source, in the directory reference/docs relative to the root of the source directory. The demo and binary distributions are distributed with a basic sakai.properties file as well, which should be stored in the sakai directory relative to the tomcat install included with the distribution.

Starting with this file, it is most critical to review and edit the following settings:

• Branding/Identity
• Database
• Filesystem
• Mail

These and other configuration settings are mentioned throughout the remainder of this document. For a full glossary of available configuration options, consult the Sakai Properties Reference.

The Configuration Viewer tool

There is an optional tool available to provide a detailed guide to the sakai.properties file. For more information, visit the Config Viewer Tool home page.

This tool includes a complete list of known sakai properties, which you can download independently of the tool and open using Excel or any spreadsheet program that can open tab-delimited text files. The latest version of the sakai properties data can be found here:

https://source.sakaiproject.org/contrib//config-viewer/trunk/properties/src/org/sakaiproject/configviewer/configViewer.txt

Branding and Identity

sakai.properties settings

There are a number of configuration options found in the sakai.properties file that control branding and identity. These settings are responsible not only for changing the cosmetic wording that end users see in the web interface, but also for customizing information found in logs and email messages.

Skinning

To further change the look of a Sakai installation, it is possible to "reskin" the installation using a series of style sheets and/or updated graphics, which are typically stored in TOMCAT_HOME/webapps/library/skin. For more information about skinning your Sakai installation, visit the "Reskinning Sakai" section of the Sakaipedia. A guide is also available.

Binary Content and Filesystem Settings

Binary content (files) uploaded into Sakai can either be stored in the database itself, or on the filesystem. By default, binary content is stored in the database.

Storing binary content on the filesystem

To use the filesystem to store binary content, add properties like the following to your sakai.properties file:

Note that Sakai only balances content between active volumes. Sakai doesn't check the availabilty of disk space on each volume. So, for example, if you have a single volume containing 100Mb of filesystem content and add four additional volumes, when another 400Mb of files are added, the distribution is likely to be something like 180Mb on the first volume and 80Mb on each of the new volumes.

Storing binary content in the database

To use the database to store binary content, comment out the directives mentioned above in your sakai.properties file. Any content already located on the filesystem will remain on the filesystem.

Migrating from database storage to filesystem storage

If you have previously stored your binary content in the database and would like to move that content to the filesystem, add the following directive to your sakai.properties file and restart:

There is currently no conversion route to move from storing content on the filesystem to storing content in the database.

Antivirus Scanning

The Rsmart group has developed a wrapper for content hosting that uses ClamAV to scan incoming binary content before it is stored. Source code can be found at:

https://source.sakaiproject.org/contrib/rsmart/antivirus/

Email Configuration

Out of the box, Sakai uses incoming mail to receive content that will be viewed using the Mail Archive tool, and to receive delivery failure notifications for outgoing messages. Outgoing mail is used for notification purposes, bug reporting, and to deliver content received by the Mail Archive tool.

You need to change a handful of settings within and outside of sakai to get mail working. Most of the changes are in sakai.properties, and will require you to stop Sakai, remove the sakai-mailarchive-james directory under webapps (but leave sakai-mailarchive-james.war), and then start Sakai again.

Outgoing Mail

For outgoing mail, you'll also need to set smtp.dns.1 and smtp.dns.2 to your DNS servers, and to set smtp@org.sakaiproject.email.api.EmailService to a host that handles SMTP in your environment. James can also handle outgoing mail for Sakai, but that this should only be used for small scale installations, as James will not provide the same level of robustness as a dedicated mail server. In particular, James will not handle delivery failures nicely, which makes it unsuited for a real deployment.

You'll probably also want to set setup.request so that informational messages either appear to come from a meaningful address (such as helpdesk@your.institution) or to clearly not come from a usable address (such as noreply@your.sakai.hostname).

You can make all the changes at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Outgoing Mail Using a Notification

The simplest way to test outgoing mail is to add a guest user to a site and enable notification:

1. Log in to Sakai as an administrator (or at least a site maintainer)
2. Navigate to a worksite
3. Open the "Site Info" tool
4. Click the "Add Participants" Link
5. Enter a valid email address that you have the ability to check under the "Guest(s) Email Address" heading (the lower text area), then click "Continue"
6. Select a site role (usually "access" or "maintain"), then click "Continue"
7. Tick the "Send Now" radio button and hit "Continue"
8. Click "Finish"

A mail message should have been sent to the email address you entered for the guest account.

Incoming Mail

To receive mail, you need to set smtp.enabled to true. You'll also need to set serverName to the service name of your installation (as in sakai.your.institution), so that James knows what messages it should field. You should also set serverId to the real hostname of the individual machine (or at least the unique part of it).

If you don't already have a mail transport agent (ala sendmail or postfix) and can bind to port 25, you should change smtp.port to 25. If you already have a mail agent, you'll need to find some way to move the appropriate mail from port 25 to 8025 (where james lives). You can use a NAT rule, or can configure sendmail or postfix to do the forwarding for you:

Sendmail Integration Instructions: http://bugs.sakaiproject.org/confluence/display/ENC/Sendmail+integration

Postfix Integration Instructions: http://article.gmane.org/gmane.comp.cms.sakai.devel/6139/

Postfix Integration Instructions Alternate: Postfix Email Configuration

Exim Integration Instructions: Exim Configuration

The following is a sample section of sakai.properties including all of the above changes:

You can make these changes all at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Incoming (and outgoing) Mail Using James

Once you get all that done and start Sakai, you should be able to test the your configuration as follows:

1. make sure James is listening on the right port

   1. telnet {the value you used for serverName} 8025 [or 25 if you've set it to that]

   2. you should see a status message from the server indicating the server name and the MTA. The server name should match what you put in for serverId (plus a domain), and should be followed by something like

      (James SMTP Server 2.1.3) ready {date and time}

2. Set up a site for testing the mail archive tool
   1. Create a new site that includes the mailarchive tool.
   2. Open the mailarchive tool in the new site. You should see the value of serverName as configured in sakai.properties.
   3. Change the options for the mailarchive tool to accept mail from anyone (this makes it easier to test things).
   4. Enroll a user in the test site with an email address you can monitor. Once this is done, you should get a copy of your test messages.
3. Test James from the command line using telnet
   1. Connect to James using the port you set up above and a command like the following:

      telnet {your hostname, or localhost} 8025

   2. Now type:

      EHLO {your service name, ala sakai.your.institution)

   3. You should see a response like:

      250 {serverID.domain} Hello {serverName} (localhost [127.0.0.1])

   4. Now type:

      MAIL FROM:<{your.email@your.institution}>

      and hit enter.
   5. You should see a receipt like:

      250 Sender <{your.email@your.institution}> OK

   6. Now type:

      RCPT TO:<{the email address you entered for the mailarchive tool in your site}>

      and hit enter.
   7. You should see a receipt like:

      250 Recipient <{email address for the mailarchive tool in your site} OK

   8. Now type:

      DATA

      and hit enter.
   9. Now type:

      Subject: test...

      (or something like that) and hit enter twice.
   10. Now type the body of your message as in:

       This is a message I am using to test James.

       When you're done entering the body of the message, hit enter twice.
   11. Now hit enter, enter a single period, then hit enter.
   12. You should see a receipt like:

       250 Message received

   13. Now type:

       QUIT

       and hit enter.
   14. Check the mailarchive tool to see if your message made it in.
   15. If that doesn't work, go back and check your settings. The log files logs/catalina.out and sakai/logs/james-DATE may help figure out what's wrong.
4. If you have a separate mail transport agent (i.e. sendmail or postfix), try the same steps as above, but with the port for the MTA (25) instead of James.
5. Check to see that you've received a copy of the messages. If you haven't, check the logs and look for details in the returned message that will eventually be sent to the MAIL FROM: address you entered.

Delivery Failure Notifications

If you wish to receive delivery failure notifications, abuse notifications, etc. for mail sent from your Sakai installation, you should make sure that postmaster@{your service name} is a working email address. It is also advisable to set meaningful email addresses for the postmaster and admin users included with Sakai. If you are using James as a standalone mail server or forwarding all mail for your service host name to James, you may wish to configure an instance of the Email Archive tool to receive, display, and forward all mail for postmaster. By default, the alias "postmaster" is reserved (to prevent site maintainers from assuming that address). In order to set up an instance of the Email Archive tool to handle the postmaster address, you will need to manually remove the entry for the postmaster address from the sakai_alias table. You should then immediately add an instance of the Email Archive tool to a site of your choice (either the Admin Workspace or a dedicated site). Messages received for postmaster by James will then be viewable in the instance of the Email Archive tool you've set up. You should configure that instance of the Email Archive tool to accept messages from anyone.

Email Archive Tool Alias Naming Limitation

As noted above, Sakai includes a postmaster account for use by James. As a consequence, the alias "postmaster" is reserved and should never be used as an Email Archive Tool alias. Doing so will result in Sakai throwing a runtime error.

Configuring Sakai from within the Web Application

Once Sakai is up and running and you are familiar with the basic operation of the software, there are few common administrative tasks that you may wish to perform.

Adding Administrative Users

If you wish to delegate administrative permissions to a range of users and wish a clearer audit trail for admin changes, you may want to set up additional administrator accounts. To add a new administrative user:

1. Log in as an existing administrator
2. Under the "Administration Workspace" site, open the "Users" tool.
3. Click the "New User" link.
4. Enter the new user's information and set their type to admin (mostly a nicety to help remember who the admins are)
5. Click "Save Details"
6. Open the "Worksite Setup" tool. Check the box next to the "Administration Workspace" site, then click "Edit".
7. Click "Add Participants" then enter the username you created earlier in the "Username(s)" text area (the upper of the two). Click "Continue".
8. Tick the radio button for the "admin" role, then click "Continue".
9. Select your notification options if desired, then click "Continue".
10. Click "Finish" to add the user to the Administration Workspace as an admin.

If you wish to give a user superadmin privileges without adding them to the Administrative Workspace site:

1. Create a new user following the first 5 steps above.
2. Under the "Administration Workspace" site, open the "Realms" tool.
3. Enter "/site/!admin" in the search field and hit the "Search" link.
4. Click the "/site/!admin" link that appears in the list of results.
5. Click the "Grant Ability" link at the top of the screen that appears.
6. Enter the id of the user created above in the "User Id:" text box, select the "admin" role, then click "Done".

Manually Adding a Tool to a Sakai Site.

By default, a number of provisional tools are included with Sakai, but can only be added to a site manually. This process is detailed in the SakaiPedia entry "Manually Adding a Tool to a Sakai Site".

Displaying dynamic HTML within the gateway and other sites.

By default, the gateway site displayed before users logged in displays a two-column layout containing the latest message of the day and the content of the location specified by server.info.url in your sakai.properties file. The default location for server.info.url points to a static HTML file bundled with a standar Sakai installation. Administrators are likely to prefer a message that can be updated without requiring a restart. Here's an approach to making the server info displayed in the gateway dynamic:

1. Open the "Administration Workspace"
2. Open the "Resources" tool
3. Click on the "public" directory.
4. Use the triangle to the right of the Add button to select the "Create HTML Page" option.
5. Enter your content, then click "Continue.
6. Select a name and copyright options for your page, then click "Finish".
7. Once the page is saved, copy and paste the URL for your page into memory (the URL will typically be something like http://hostname/public/Your File Name.
8. Edit your sakai.properties file and set server.info.url to the URL specified above (the protocol and port are optional).
9. Restart Sakai

A similar approach can be used to prepare public content for use in any site or template. As above, create public content from the "Administration Workspace" site. Once you've saved your content, simply add an additional "Web Content" tool to the site in question. Here's an example in which we add a custom page to the default template for new "My Workspace" sites (useful for training materials, etc.):

1. Follow the steps to create a dynamic page as in the previous examples.
2. Open the "Sites" tool
3. Open the "My Workspace" template (!user)
4. Click the "Pages" button
5. Click the "New Page" link
6. Enter a name for your new page (this will appear in the list of pages in the navigation bar).
7. Click the "Tools" button
8. Click the "New Tool" link
9. Select the radio button next to the "Web Content" tool
10. Scroll down and enter the URL you copied above into the "source" field.
11. Click "Done" to save your changes.

Template sites only show up in the "Sites" tool. For individual sites, you can simply add the dynamic content as follows:

1. Follow the steps to create a dynamic page as in the previous examples.
2. Open the site
3. Open the "Site Info" tool
4. Click the "Edit Tools" link
5. Select the "Web Content" tool, then click "Continue"
6. Enter the URL you copied above into the "URL" field, then click "Continue", then "Finish"

Permissions

The permission to view, edit, delete, and otherwise manage the data associated with Sakai tools is managed using realms, which are most commonly associated with a site. Each realm has one or more roles to which a user can be assigned. Permissions are managed using the Realms tool in the administrative workspace.

Examples of roles would be instructor, student, teaching assistant, grader, site maintainer, site accessor. A role is typically given a single word name like "instructor", "student", "ta", "grader", "maintain", "access". Each role specifies explicitly all of its permissions, and one set of permissions does not imply another (for example, "add" for a given tool does not imply "edit" or even "read" for the same tool).

The default permissions for a realm are inherited from the most appropriate realm template for a given site at the time the site is created. A site with a type of "project" would inherit from the realm !site.template.project realm if it exists, or from the !site.template realm if !site.template.project realm does not exist.

JVM Tuning

JVM tuning is an ever-evolving process that changes with each version of Java. Even for development instances, you'll need to read through and apply the basic JVM tuning suggestions below.

Basic JVM Tuning

The default JVM settings are not adequate to run Sakai. At a minimum, you need to increase the overall heap size and the maximum size allowed for the permanent generation. This can be done as follows.

Mac/Linux: Create the file TOMCAT_HOME/bin/setenv.sh containing a line like the following:

Windows(PC): Create the file TOMCAT_HOME/bin/setenv.bat containing a line like the following:

Advanced JVM Tuning

For more information, please see:

• Tuning Garbage Collection with the 5.0 Java (Sun)
• Java Tuning Whitepaper (Sun)

Load Balancing and Scaling

Introduction

Although Sakai can be run on a single server which houses all database and filesystem content, many sites will want to consider growing their installation beyond the confines of a single server. This section of the admin guide will outline the basic approach to scaling up your sakai installation. When deciding which approach is best for you, you should consider the information below. Whatever solution you choose should be tested for performance and tuned as needed. For more information on tuning, see the Sakai Admin Guide - JVM Tuning and Sakai Admin Guide - Database Configuration and Tuning sections of the admin guide.

Standalone Server

The simplest option is to run all components of Sakai on a single server. As indicated by the asterisks in the diagram, Apache and filesystem storage are optional components, as Sakai can run with Apache (using Tomcat to handle requests directly) and can be made to store binary content in the database.

This configuration entails installing a database server locally or using the default Hypersonic SQL implementation bundled with Sakai. This option offers the least benefits in terms of scalability and redundancy.

However, this configuration is highly portable, and can be set up on a reasonably powerful laptop. Thus it is ideally suited for a standalone development environment, which allows a developer to write and test tools and modules for Sakai without even a network connection. This is also a good option when demonstrating Sakai in environments without reliable networking.

Thin client configuration

A "thin" client is simply a server which only runs the application component of Sakai, and which does not house any database or filesystem content. This solution allows institutions with existing database and distributed storage resources to take advantage of their existing infrastructure. It may be acceptable to run a limited demonstration or pilot with this configuration, but a load balanced solution is recommended for anything beyond that (see below).

Load balanced thin client

A load balanced collection of thin clients is one of the scalable options for Sakai. It offers load balancing to distribute large volumes of traffic. It also offers redundancy, which allows for the more seamless management of hardware failures and preventative maintenance. In this configuration, each application server is pictured as only running tomcat, which is the minimum required to run Sakai.

Thicker client

A "thicker" client is simply an application server that runs one or more tomcat instances behind an apache instance. Adding Apache allows you to take advantage of the configurability and maturity of Apache, and also to set up clients that contain more than one instance of tomcat. A key reason to consider this information is the hard limit of memory usage on 32-bit hardware. The 32-bit JVM is only capable of addressing around 2G of RAM, which is tight for a full Sakai installation. You can install multiple tomcats on a single application server, and thus take better advantage of the memory available.

Big Iron

A number of sites have chosen to run with a smaller number of more powerful servers (as few as one), which are divided up into a series of virtual machines using solutions like VMWare. Although this may create a single point of failure for instances with only one large server, it offers the ability to dynamically allocate CPU and RAM among multiple virtual machines. It also has great advantages for change management, as a single node can be updated, tested, and then cloned into the appropriate number of updated application servers. Also, the state of a node can be saved for rolling back major changes if problems are detected later on.

Load Balancing Solutions

Sites running sakai in production have chosen to handle load balancing in a multitude of ways. These can roughly be divided into software solutions, which run on existing hardware, and hardware solutions, which run software on dedicated hardware, typically provided by a commercial vendor.

Software Solutions

The simplest software solution is to use an instance of Apache to balance traffic between multiple tomcat installations using mod_jk (apache 1.3 and 2.0) or mod_proxy_ajp (apache 2.2 and higher). Apache 2.2 or higher also offer the ability to use mod_proxy_balancer to balance multiple apache or tomcat installations. For more details on setting up tomcat with mod_proxy_ajp, see the Sakai Admin Guide - Advanced Tomcat (and Apache) Configuration section of the admin guide.

Hardware Solutions

There are a number of dedicated solutions provided by commercial vendors such as Big5 Networks and Zeus. Some solutions offer only the ability to load balance HTTP traffic (comparable to mod_proxy_balancer), while others offer the ability to use AJP (comparable to mod_jk or mod_proxy_ajp). Any solution that provides compatible sticky sessions (see below) should be capable of working with Sakai.

Sticky Sessions and Sakai

Whatever load balancing solution you choose, you must ensure that each client remains on the same app server for the life of their session. There are multiple approaches for monitoring and maintaining sticky sessions. Solutions that use IP-based sessions have problems with virtual private networks and proxies. Solutions that use dedicated cookies seem to work best for most people, but may cause problems with web services calls and some DAV clients. Whichever method you choose, be aware that the sticky session timeout is one of the factors controlling how long idle sessions remain active, as users will be required to log in again if they are sent to a different node after their sticky session times out.

Cluster Options in the sakai.properties File

Key portions of Sakai are designed to be cluster-aware. There are a handful of settings in the sakai.properties file that control the way in which clustering is managed.