LON-CAPA on the Linux Filesystem

Scott Harrison, freeware volunteer, sharrison@sourceforge.net
June 4, 2002

 Contents 1. Introduction 2. The LON-CAPA Source Files 3. Active Filesystem Directories of Importance 4. The Installation Mechanism 5. Automated Testing 6. Software Packages 7. Security on the Filesystem 

1. Introduction

LON-CAPA currently consists of 695 files placed in 56 different directories on a linux filesystem. There are also 9 different symbolic links. There are 11 different file ownership/permission categories under which files are securely installed.

For the last 2 years, an average of 1 new file per day was included into the LON-CAPA distribution. A conservative estimate is that 10 files were modified each day in the LON-CAPA source tree. In order to maintain a robust build-installation framework consistent with the many changes, all information pertaining to the LON-CAPA installation has been kept in a well-formatted XML-valid document. The XML document "renders" LON-CAPA from a CVS source tree to the Linux filesystem (the XML document can also be used to build RPMs, display documentation, and conduct status-checking reports). There have been few, if any, bugs related to the XML specification of the LON-CAPA software. Thus, throughout the software development and version releases of LON-CAPA, there has most always been a complete, bug-free specification of what files comprise the LON-CAPA software. For more information about this XML-based approach, please visit http://lpml.sourceforge.net/.

LON-CAPA is well-supported on RedHat Linux operating systems version 6.2 and version 7.3. LON-CAPA is also known to run well on Mandrake and Debian, however there is no specified installation procedure for these operating systems (a Debian installation procedure is currently under development). There currently do not exist LON-CAPA installations on BSD-UNIX or MacOS/X systems (I remain curious though as to whether a programmer or institution will pioneer this strategy). Given the current level of new LON-CAPA feature requests and frequency of new software versions, we suggest that most users plan on using RedHat so as to reduce high-frequency system administration overhead.

LON-CAPA is interdependent with a variety of Linux operating system services and software packages. Thus, a challenge exists to maintain the correct set of software packages (e.g. with RedHat, software packages are called RPMs) with the correct configurations. Past efforts have sought to completely automate the handling of software packages and their configuration. The new existing strategy is to test for proper operation of system services (architecturally termed as "horizontal layers") and make recommendations (to a knowledgeable linux administrator) as to how software packages or configurations should be adjusted.

2. The LON-CAPA Source Files

Of the 695 files which make up the LON-CAPA distribution, 492 of these files can be thought of as interface widgets or templates. The widgets and templates are organized into ten different file "globs".

1.     Template files for generating new resources (28 files)
source-to-target: loncapa/loncom/homework/templates/* -> /home/httpd/html/res/adm/includes/templates/

2.     Icons for providing a HTML-tabled view of a course map (109 files)
source-to-target: loncapa/rat/images/*.gif -> /home/httpd/html/adm/rat/

3.     Icons to indicate an unexpected result (6 files)
source-to-target: loncapa/loncom/html/adm/lonKaputt/*.* -> /home/httpd/html/adm/lonKaputt/

4.     Logos and general widget icons (108 files)
source-to-target: loncapa/loncom/html/adm/lonIcons/*.* -> /home/httpd/html/adm/lonIcons/

5.     Miscellaneous resources (9 files)
source-to-target: loncapa/loncom/html/adm/lonMisc/*.* -> /home/httpd/html/adm/lonMisc/

6.     XML files which assign unicode numbers to mathematical symbols using <! ENTITY...> type syntax (26 files)
source-to-target: loncapa/loncom/MathML/*.ent -> /home/httpd/html/adm/MathML/

7.     Icons used for the entire LON-CAPA user interface (80 files)
source-to-target: loncapa/loncom/html/res/adm/pages/*.gif -> /home/httpd/html/res/adm/pages/

8.     Icons used for directory indexing (89 files)
source-to-target: loncapa/loncom/html/res/adm/pages/indexericons/*.gif -> /home/httpd/html/res/adm/pages/indexericons/

9.     Icons used for the bookmark portion of the LON-CAPA user interface (23 files)
source-to-target: loncapa/loncom/html/res/adm/pages/bookmarkmenu/*.gif -> /home/httpd/html/res/adm/pages/bookmarkmenu/

10.  Files associated with the scheme of displaying bookmarks (3 files)
source-to-target: loncapa/loncom/html/res/adm/pages/bookmarkmenu/*.html -> /home/httpd/html/res/adm/pages/bookmarkmenu/

A second grouping of files are the 124 scripts, documentation files, shared object libraries and other extraneous files for LON-CAPA.

A third (and highly important) grouping of files are the 77 mod-perl Apache web handler modules. These modules coordinate how the system interacts with the web interface delivered by the LON-CAPA system. For example, the spreadsheet, search engine, graphing, and homework formatting features of LON-CAPA are all transacted by different Apache web handler modules. More information on the LON-CAPA Apache web handlers can be read about in the section titled "LON-CAPA and the 77 Web Handlers".

In addition to the total 695 files of LON-CAPA, 9 symbolic links are also created. 7 of these links exist inside the /etc/rc.d/ directories and are used to facilitate the launching of LON-CAPA network services (i.e. lonc and lond). Another link makes LON-CAPA resources available in their "raw" format (/home/httpd/html/raw is linked to /home/httpd/html/res). Another link makes /etc/mime.types equivalent with /etc/httpd/conf/mime.types to support backwards compatibility with various software packages for various RedHat releases.

3. Active Filesystem Directories of Importance

Of the 56 different directory locations where LON-CAPA files are stored, there are about a dozen directory locations of high significance for both operating and understanding the LON-CAPA software

4. The Installation Mechanism

4.1 Standard procedure

To install LON-CAPA on a running RedHat Linux operating system, the procedure is as described at http://install.lon-capa.org/. The procedure is intentionally limited to an initial one-line command (for simplicity's sake). To summarize:

Download the most current loncapa.tar.gz.

wget http://install.lon-capa.org/versions/current/loncapa.tar.gz
tar xzvf loncapa.tar.gz
cd loncapa

The UPDATE command will refresh your filesystem with all the latest LON-CAPA software.

./UPDATE

Upon running the ./UPDATE command, the user is presented with questions regarding the set up of their LON-CAPA server. For instance, the following is a summary question which verifies the machine-specific configuration variables (that are stored inside /etc/httpd/conf/loncapa.conf):

 =============================================================================== This is now the current configuration of your machine. 1) Domain Name: msu 2) Machine Name: rawhidel1 3) System Administrator's E-mail Address: harris41@spock.lite.msu.edu 4) Role: library 5) Cache Expiration Time: 86400 6) Server Load: 2.00 7) Everything is correct up above ENTER A CHOICE OF 1-6 TO CHANGE, otherwise ENTER 7: 

The formatting and valid ASCII character usage are interactively monitored by the UPDATE script.

4.2 XML specification

loncapa/doc/loncapafiles/loncapafiles.lpml is an XML file that contains all the information pertaining to the LON-CAPA installation. Even though loncapa/doc/loncapafiles/loncapafiles.lpml is present in the "doc" directory of the LON-CAPA source tree, it is the most critical file of the software build-installation process. loncapa/doc/loncapafiles/loncapafiles.lpml is referenced by many different loncapa/loncom/build/Makefile targets.

An example entry inside loncapa/doc/loncapafiles/loncapafiles.lpml is:

 <file> <source>rat/lonwrapper.pm</source> <target dist='default'>home/httpd/lib/perl/Apache/lonwrapper.pm</target> <categoryname>handler</categoryname> <description> Wrapper for external and binary files as standalone resources. Edit handler for rat maps; TeX content handler. </description> <status>works/unverified</status> </file> 

LPML is an XML document-type definition which is described at http://lpml.sourceforge.net/.

4.3 Makefile

loncapa/loncom/build/Makefile is the "engine" of the source code tree (i.e. the aforementioned ./UPDATE script simply calls different Makefile targets consecutively). Ordinarily, only software developers bypass the ./UPDATE script and utilize the Makefile targets directly.

There are currently 40 targets present in the Makefile (each target is invoked with the syntax "make TARGETNAME" from the loncapa/loncom/build/ directory.. Of these targets, there are several targets of common usage. These common targets are described immediately below.

make install: this installs configuration files, non-configuration files, configures the Apache httpd.conf file, runs a sanity check on the operating system; generally speaking, this target does everything associated with installing and upgrading files on a LON-CAPA filesystem.

make rawinstall: this installs configuration files and non-configuration files (without extra bells-and-whistles such as configuring the httpd.conf file or running a sanity check).

make configinstall: this installs configuration files and is a sub-target of the rawinstall and install targets.

make build: this compiles all files that need to be compiled from the LON-CAPA source tree.

make test: this runs software functionality tests.

5. Automated Testing

The goal is to test for proper operation of system services and make recommendations (to a knowledgeable linux administrator) as to how software packages or configurations should be adjusted.

The importance of a diagnostic test tool is especially relevant when installing LON-CAPA on non-RedHat Linux systems, or for testing installation procedures for new RedHat version releases.

In terms of better developer-to-user interactions, the current experience is that automated testing has helped speed the identification of problems associated with the server configuration and software dependencies.

5.1 Standard Procedure for Testing

After running the ./UPDATE command from the loncapa.tar.gz LON-CAPA distribution, the user should then run the ./TEST command to ensure the continuing correct operation of the LON-CAPA software.

./TEST

Using the TEST command may be an iterative process. It is normal to expect that the ./TEST command will recommend for users to perform various steps to ensure optimal performance of their LON-CAPA server.

5.2 Testing the System Services (MySQL, perl libraries, etc)

Two of the most important (yet occasionally tricky) system services to handle are those involving 1) the MySQL database and 2) the dozens of perl software packages needed from http://www.cpan.org/ (as described in loncapa/doc/otherfiles/perl_modules.txt).

The testing of these system dependencies is performed inside the loncapa/loncom/build/system_dependencies/ directory.

MySQL testing checks for:

In the event of failed testing, the user is prompted as to what changes to make to their operating system.

LON-CAPA relies on the presence of multiple CPAN (http://www.cpan.org/) perl modules which are not ordinarily distributed with RedHat operating systems. Examples include Digest-MD5, Math-FFT, GDTextUtil, and Algorithm-Diff.

In the event of missing perl modules, the user is prompted to update their system with either a LON-CAPA-systemperl-*.*-rh72.i386.rpm package or a LON-CAPA-systemperl-*.*-1.i386.rpm package.

5.3 Testing the LON-CAPA Web Interface

The testing of the LON-CAPA web layer is performed inside the loncapa/loncom/build/weblayer_test/ directory.

Simulated web transactions are conducted; this ordinarily would be considered "black-box" testing. Currently, a test login has been implemented. The machine's host id and domain for LON-CAPA is determined (read from /etc/httpd/conf/loncapa.conf). A password is randomly generated and a test user with a name beginning with 'ZXQTEST' is created within the /home/httpd/lonUsers/ directory. A test login is run by using the LWP::UserAgent perl module. Password encryption that ordinarily occurs by javascript is simulated with the perl Crypt::DES module.

In the event of a failed login, the system administrator is prompted with corrective suggestions such as "Are lonc and lond running on the system?".

5.4 Testing the Installation Mechanism

The testing of the installation is performed inside the loncapa/loncom/test/ directory.

Since a great deal of the installation mechanism relies on the ability to compare the files inside the LON-CAPA source tree with the target filesystem, most of the tests relate to the file comparison utilities.

6. Software Packages

./CHECKRPMS

In addition to the ./TEST and ./UPDATE commands, there is a ./CHECKRPMS command. The ./CHECKRPMS command first attempts to contact different RedHat RPM mirrors. When successful contact is made, ./CHECKRPMS compares the RPM version numbers (based on an intelligent method designed by Martin Siegert at Simon Frasier University) and outputs a list of RPMs that the system administrator should update.

Updating RPMs is an important task to do for security. Quite often, even those RPMs that are not directly associated with system networking can present security holes (e.g. imlib, zlib, diffutils, and man all have had security updates in the last year).

./CHECKRPMS relies upon Martin Siegert's check-rpms script which exists in the loncapa/loncom/build/ source directory. For more information on the advanced usage of check-rpms:

cd loncapa/loncom/build; perldoc ./check-rpms

Some advanced usage hints:

To automatically update RPMs for a RedHat 6.2 system:

check-rpms -v -r --update -ftp rufus.w3.org/linux/redhat/updates/6.2/en/os

To automatically update RPMs for a RedHat 6.2 system:

check-rpms -v -r --update -ftp rufus.w3.org/linux/redhat/updates/6.2/en/os

To download needed RPMs for a RedHat 6.2 system:

check-rpms -v -r -d /var/tmp/rpms -dl -ftp

7. Security on the Filesystem

Multiple processes controlled by multiple entities exist on a LON-CAPA server system. On a typical LON-CAPA library server, many different members of an institution will have author accounts by which they can log onto the server. The goal is to prevent these different user accounts from accessing other user directories (or sensitive information files such as password-files) on a LON-CAPA system. Two things are done to accomplish this on the filesystem. 1) A typical user is a member of only his or her own group. 2) A user's home directory can only be read by the user or root or the web-server processes.

The web-server processes are owned by the 'www' user. In order for web-server processes to work with the home directories of each user, the 'www' user is made a member of each user's personal group. For example, on a system with korte, lucasm, and jensen as authors (and thus standard Linux account users with filesystem privileges), www would be a member of the 'korte' group, the 'lucasm' group, and the 'jensen' group as defined in the /etc/group and /etc/group- files.

Several system interactions require the 'www' user to have the ability of the all-powerful 'root' user. (Future plans are for this to be mediated by 'sudo'.) Currently, there are several setuid-root scripts described in loncapa/doc/loncapafiles/loncapafiles.lpml. These setuid scripts allow 'www' processes to add new system users, change passwords, and password authentication against shadow passwords.

In order to ensure proper access and execution rights to various LON-CAPA software files, multiple file ownership/permission categories are supported in loncapa/doc/loncapafiles/loncapafiles.lpml as shown in the table below.

Category Name

Permissions (development)

interface file

0644 www:www

setuid script

6755 root:root

handler

0600 www:www

static conf

0444 root:root

conf

0644 root:root

script

0700 www:www

graphic file

0400 www:www

doc

0644 root:root

system file

0644 root:root

root script

0700 root:root

symbolic link

root:root

standard

0755 root:root

server standard

0755 www:www

server readonly

0700 www:www

During a brand-new installation, in order to make LON-CAPA work on a system with shadow passwords, the system administrator must manually configure and compile a mod_auth_external software package. Instructions for this, as currently described on http://install.lon-capa.org/ are:

First ensure the existence of a 'www' user. If 'www' does not yet exist on the system, then create:

/usr/sbin/useradd www

Make a LON-CAPA system work with shadow passwords

Step #

Description

1

Is your system using shadow passwords? (Note: LON-CAPA will work with either MD5/non-MD5 configured systems). If your system is not using shadow passwords, then do not perform any of the additional steps. If your system is using shadow passwords, then you will need to perform the additional steps below.

How to detect:
command:
cat /etc/passwd | grep ':x:'

If there is output such as "root:x:0:0:root:/root:/bin/bash", then your system is using shadow passwords and you will need to continue with the steps below.

2

Retrieve the mod_auth_external source by running the following command

wget http://www.wwnet.net/~janc/software/mod_auth_external-2.1.13.tar.gz

3

Unpack the mod_auth_external source by running the following command

tar xzvf mod_auth_external-2.1.13.tar.gz

4

Go to the pwauth directory by running the following command

cd mod_auth_external-2.1.13/pwauth/

5

Edit config.h and change SERVER_UIDS definition

Determine the user id of 'www':
grep ^www /etc/passwd | cut -d':' -f3
Change the line
#define SERVER_UIDS 99 /* user "nobody" */
to be
#define SERVER_UIDS 513 /* user "www" */
where in this example 513 corresponds to the user id of 'www'.

6

Compile the pwauth executable by running the following command

make

7

Install pwauth by doing the following

cp pwauth /usr/local/sbin/
chmod 6755 /usr/local/sbin/pwauth

Edit (creating the file) /etc/pam.d/pwauth to have the contents:

         auth       required     /lib/security/pam_pwdb.so shadow nullok         auth       required     /lib/security/pam_nologin.so         account    required     /lib/security/pam_pwdb.so