| Hi all,
Last week we moved to a new server here, and as an exercise to try for
better understanding of it all I did a clean install and took careful
notes. The following are my install notes, which include information
about how I configured the authentication to run through the secure
(slower) port of the server while running everything else through the
standard unencrypted port. I post it all here in case it's useful for
anyone else. Please let me know if you have questions or comments.
I am verbose => these are quite long. The most interesting parts are
in the "SSL Customization" and "Moving Logfiles From /opt/www/webwork"
sections.
Gavin
install notes
Clean install of Webwork 1.6.04 on a Solaris 8 system running
apache 1.3.20 + mod_ssl
There are a couple of places where this is nonstandard. Most of these
are noted as we go along. One that is worth noting at the outset is
that while the default Webwork script directory alias is
/cgi-bin/webwork/system, I don't see the need to make it be a sub-
subdirectory of /cgi-bin (other than to mirror the structure of the
Webwork directory). I therefore make the directory alias
/cgi-bin/webwork-cgi instead.
Installation:
First, download the latest webwork tarball. At the time of writing,
this was webwork_1.6_04-[date].tar.gz. I downloaded this into the
/tmp directory of my server. Then, unpack it:
% gzip -dc webwork_1.6_04* | tar -xvf -
(Note: a '%' prompt means that I'm working as any old user; a '#'
prompt says I'm the root (super-)user on my server. A '$' prompt
means that I'm the Webwork administrative user.) This unpacks a
bunch of readme files and the webwork.tar file. I've read the readmes
before, so I continue. My web server (apache) lives in /opt/www, so
I put webwork there to keep it all together.
% /bin/su
# cd /opt/www; mkdir webwork; chown wwadmin webwork
this just makes the directory webwork in /opt/www for webwork to live
in, and makes the webwork administrator, "wwadmin" own it, so that we
are allowed to unpack webwork there.
# /bin/su wwadmin
$ tar -xvf /tmp/webwork.tar
Because we're in /opt/www and because the webwork.tar archive unpacks
into ./webwork, this puts all of the webwork files in the webwork
directory just created. Apache needs a link in its cgi-bin to let it
serve the webwork cgi scripts, and a link in the default documents
directory to the webwork system html directory. Because the apache
directories are owned by root, we go back to being root to do this.
$ ^D
# cd /opt/www/cgi-bin
# ln -s ../webwork/system/cgi ./webwork-cgi
# cd /opt/www/htdocs/
# ln -s ../webwork/system/system_html ./webwork_system_html
Configuration:
Next, we can run the webwork setup program. The first line of the
system_webwork_setup.pl program says "#!/usr/bin/perl": use the Perl
program from /usr/bin. That works for me, so I can just use it as it
is (if my perl were in another place, say, /usr/local/bin/perl, I'd
have to change that line).
# cd /opt/www/webwork/system/
I want to run this as a webwork administrator, so
# /bin/su wwadmin
$ ./system_webwork_setup.pl
My responses to the prompts from this are
working or demo version? w
server running in chroot? n
full path to perl? /usr/bin/perl
webwork cgi-url? /cgi-bin/webwork-cgi/
webwork html-url? /webwork_system_html
group name? other
set course permissions? y
set group for all? y
set system permissions? y
Note: the group name given above is the group of all webwork admin
users. My system is unconventional in that I am the only admin
user, and so rather than create a specific user group for this, I use
the default group "other." In general, I'd want to create a group, eg
"wwadmgrp," containing all "wwadmin" users and would use that instead
of "other." After running the system_webwork_setup.pl script, I
tweaked the permissions on things a little to make them a little more
secure; because I'm the only user who needs to change the files,
there's no reason for the group other to have this authority, so I
take it away. If I needed other people to be able to edit the files,
I'd not take this step.
$ chmod -R g-w *
Now I need to correct some paths in various scripts.
$ cd scripts
I edited makePDF, makePS, and gif2eps so that the paths to latex,
dvips, and ps2pdf are correct. To reduce later errors, I also added
the directory where these scripts and their supporting programs are
found to the PATH variable at the top of each script (e.g., if these
scripts were all in the directory /usr/local/bin, I'd change the PATH
variable to
PATH=$PATH:/usr/bin:/usr/local/bin
from its original value). Similarly, I need to correct the file
displayMacros.pl.
$ cd ../courseScripts
(and edit displayMacros.pl to correct the path to latex2html in the
5th line from the bottom of the file.) I also had to add the line
$ENV{'PATH'} .= '/usr/local/bin'
(where I'm pretending /usr/local/bin is the location of latex and the
netpbm binaries) to get latex2html to work for typeset mode.
Probably as a result of the vagueries of my installation of
latex2html, I found that I had to add
$METAFONT_DPI=600;
at the end of the /opt/www/webwork/system/latex2html.init.98.1 file,
and ended up changing the call to latex2html in displayMacros.pl to
include the command line options
-transparent -image_type gif
to get images generated with transparent backgrounds.
Webwork uses tth to generate its html-formatted text, so we make that
available in the scripts directory. (The official documentation says
to copy it there, but I use a link to avoid duplicating a 1MB file.)
$ cd ../scripts
$ ln -s /usr/local/bin/tth ./tth
Next, there are some changes to make in the global configuration file
Global.pm.
$ cd /opt/www/webwork/system
And search for "feedbackAddress". I make the following changes:
$feedbackAddress = 'math-itc@umich.edu';
$webmaster = 'math-itc@umich.edu';
$smtpServer = 'ect.math.lsa.umich.edu';
The e-mail address math-itc@umich.edu is the mail alias for the math
instructional technology consultant (me), who is in charge of the
on-line homework for us, and the SMTP server is our mail server. A
bit further down, I also changed
$logAccessData = 1;
to log all accesses, which means I'll get very big log files but can
track down to the last keystroke what students entered on any attempt.
SSL Customization
Because I'm running a version of apache that includes mod_ssl, I want
to force all authentication exchanges to occur through the SSL port on
the webserver. To do this, I move the authentication script
(login.pl) into a "secure" subdirectory of the webwork cgi directory,
and require SSL to access that directory. This requires that we
change the calls to login.pl to be https calls, and calls of scripts
after that to be normal http calls.
$ cd /opt/www/webwork/system/cgi
$ mkdir secure; chmod 755 secure
$ mkdir secure/cgi-scripts; chmod 755 secure/cgi-scripts
$ mv login.pl secure/
$ mv cgi-scripts/login.pl secure/cgi-scripts/
Next we need to make sure that all calls of login.pl are done using
https and that all scripts following login.pl are called using
standard http. I do this by defining the secure and normal server URL
in Global.pm:
$ cd ..
and edit Global.pm to include, after the $feedbackAddress and related
variables,
$secureServer = 'https://instruct.math.lsa.umich.edu/';
$normalServer = 'http://instruct.math.lsa.umich.edu/';
I also add a secure CGI URL variable; this is right after $cgiWebworkURL:
$cgiSecureWWURL = '/cgi-bin/webwork-cgi/secure/cgi-scripts/';
</pre
and change $loginURL to
$loginURL = "${cgiSecureWWURL}login.pl
Then, in /opt/www/webwork/system/cgi/secure/cgi-scripts/login.pl all
instances of "start_form" that don't require SSL are changed from
${Global::cgiWebworkURL}scriptname.pl
to
${Global::normalServer}${Global::cgiWebworkURL}scriptname.pl
(or ${Global::normalServer}$Global::welcome_CGI). This is true for
profLogin.pl, TALogin.pl, welcome_CGI, change-email.pl, and the Fast
Login option, $scriptURL. Calls that require SSL are changed to use
$cgiSecureWWURL:
${Global::cgiWebworkURL}scriptname.pl
becomes
${Global::cgiSecureWWURL}scriptname.pl
This is true for change-passwd.pl.
Similarly, in cgi-scripts/change-password.pl,
${Global::cgiWebworkURL}login.pl
becomes
${Global::cgiSecureWWURL}login.pl
To make sure that all calls to login.pl are done via https, we add
this to the call to login.pl in each of the scripts in the webwork cgi
scripts directory that call login.pl. Thus in TALogin.pl,
profEditCourseFiles.pl, profBuildProblemSetPage.pl,
profHousekeeping.pl, profLogin.pl, profSendMail.pl, and welcome.pl I
change
${cgiURL}login.pl
to
${Global::secureServer}${Global::cgiSecureWWURL}login.pl
and in change-email.pl, we change
${Global::cgiWebworkURL}login.pl
to
${Global::secureServer}${Global::cgiSecureWWURL}login.pl
The one other place where login.pl is called is in the index.html
file, which is located in /opt/www/webwork/courses/Ma215/html. The
form action is changed to
https://server/cgi-bin/webwork-cgi/secure/login.pl
Finally, to force SSL for the "secure" webwork script directory, we
add a stanza in apache's httpd.conf file:
<Location "/cgi-bin/webwork-cgi/secure">
AllowOverride None
Options None
Order allow,deny
Allow from all
SSLRequireSSL
</Location>
At this point we have a working SSL Authentication scheme. However,
it's a little ugly because the default background and header for the
pages generated by login.pl are gifs, which are in directories that
the secure server doesn't see. Thus the login and 'welcome' pages
are the browser default color (grey for Netscape) and feature broken
images. To get around this, we hack the subroutine htmlTOP in
scripts/HTMLglue.pl and change login.pl and change-password.pl a
little more. This is a rather ugly kludge, but c'est la vie. In
login.pl, sub login_form, change the call of &htmlTOP from
&htmlTOP('WeBWorK Login Page','','Pragma: no-cache')
to
&htmlTOP('WeBWorK Login Page','secure:white','Pragma: no-cache')
in sub success_form, make the call be
&htmlTOP('Login Valid','secure:white')
and in sub failure_form,
&htmlTOP('Login Invalid', 'secure:#ff6767')
Similarly, in change-password.pl, change the call of &htmlTOP in sub
change_pw_form to
&htmlTOP('Change Password Page', 'secure:white')
in sub success_form to
&htmlTOP('Password Changed', 'secure:#33f433')
and in sub error_form to
&htmlTOP($title, 'secure:#ff6767')
Then, in scripts/HTMLglue.pl, change the first two lines of
sub htmlTOP to
my ($title, $bg_url, @headers) = @_;
# my $background_url = $bg_url || $Global::background_plain_url;
my $background_url = '';
my $background = ''; my $isNormal = 1;
if ( defined($bg_url) && $bg_url =~ /^secure:(.*)/ ) {
$background = "bgcolor=\"$1"";
$isNormal = 0;
} else {
$background = 'background="';
$background .= $bg_url || $Global::background_plain_url;
$background .= '"';
}
my $hdrimg = ($isNormal)?"<IMG SRC=\"$Global::headerImgUrl" BORDER=1 ALT=
" WeBWorK">":'';
And in $out, change the <body> tag to
<body $background>
and the header image tag to $hdrimg.
Course Configuration
First, this is a production server, so I don't need the default
demoCourse that webwork installs by default. I archive the course,
but otherwise remove it from operation.
$ cd /opt/www/webwork/courses
$ tar -cvf - ./demoCourse | bzip2 > ../demoCourse.tar.bz2
$ rm -r ./demoCourse
$ rm ../system/courses/demoCourse
In general, I would leave this as a template for new courses. As it
is, I install a new class that I've developed from a different server;
this is equivalent to copying the demoCourse with
$ cp -Rp ./demoCourse ./Math215
There are several links that allow the webserver to find and serve
course documents which we next create
$ cd ../system/courses
$ ln -s ../../courses/Math215 ./Math215
$ cd /opt/www/htdocs/
$ mkdir webwork; chmod 755 webwork
$ cd webwork; ln -s ../../webwork/courses/Math215/html ./Math215
$ cd ../../webwork/courses/Math215
Then we run the course setup script
$ ./course_webwork_setup.pl
The responses to prompts in this script are
"working" or "demo"? w
create missing dirs? y
course url? /webwork/Math215
webwork cgi url? /cgi-bin/webwork-cgi
course link name? Math215
group? webgroup
The group "webgroup" is a group that includes the webserver and all
users who will be editing the course. In that I'm relying on the
administrative user to do this, I set this to the group that the web
server runs as ("nobody").
save old webworkCourse.ph? y
save old index.html? y
set the group? y
set default working perms? y
Residual configuration:
$ chmod g+s templates
(this ensures that files and directories created in templates will
also be in "webgroup," so that the webserver can read and write
them as appropriate.
Installing Users
Because this is a brand-spanking-new course with no users predefined,
we create a couple using the import_classlist-database.pl script.
$ cd /opt/www/webwork/courses/Ma215/templates
here, edit a file to list the users, say, 215.lst, in the format
SID,LastName,First Names,C,,Section#,Recitation#,e-mail,username
(Recitation# may be left blank) and run
$ ../../../system/scripts/import_classlist-database.pl Ma215 215.lst
Then give someone professorial permissions with
$ ../../../system/scripts/setProfPermissions.pl Ma215 username
To build problem sets, we use the professor tools page after logging in.
Moving Logfiles From /opt/www/webwork
Because /opt is supposed to be a static directory, while /var contains
things which change, I want the log files for my webwork courses and
the gif images generated when viewing assignments in typeset mode to
be created under /var/www. I do this by making the corresponding
directories links to locations in /var/www.
$ ^D
# cd /var/www
# mkdir webwork; chmod 755 webwork; cd webwork
# mkdir Ma215; chmod 755 Ma215
# cd Ma215
# mv /opt/www/webwork/courses/Ma215/logs .
# mv /opt/www/webwork/courses/Ma215/html/tmp .
# mv /opt/www/webwork/courses/Ma215/DATA .
(the following isn't necessary:
# chown -R http:nobody logs/ tmp/ DATA/
(apache runs as the user HTTP and with the group "nobody").)
# cd /opt/www/webwork/courses/Ma215
# ln -s /var/www/webwork/Ma215/logs ./logs
# ln -s /var/www/webwork/Ma215/DATA ./DATA
# cd html
# ln -s /var/www/webwork/Ma215/tmp ./tmp
end install notes
<| Post or View Comments |>
|