Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

This article is under construction. Use the information herein with caution until this message is removed.

These instructions cover the installation of the Ubuntu Server 20.04 LTS 64 bit operating system and WeBWorK 2.15 using the WeBWorK Virtual Machine Image.

The WeBWorK Virtual Machine Image is an .ova file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, AWS, Google Cloud, etc. This image file has been tested on VirtualBox 6.

This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MySQL, R server, lighttpd, log rotation, etc.) installed and configured.

Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

Overview

After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 20.04 LTS system with WeBWorK, Apache2, MySQL, R server, lighttpd, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user wwadmin (who has sudo privileges), for the MySQL user webworkWrite, and for the WeBWorK user admin who has professor privileges (see below). Finally you will have to install OpenSSH (since this has to be done locally) to gain SSL access to your server and you should set up SSL (https) access to WeBWorK if students will be using your server.

There are more detailed instructions for Ubuntu Server 20.04 and WeBWorK 2.15 at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server.

Download the ova image

There is only a 64 bit distribution. The 64 bit distribution should work with most modern cpu's. Download the md5 check sum and .ova file from the site below. The ova is a 3.6 GB file.

• MAA

1. http://webwork.maa.org/ww-downloads/WW2.15_Ubuntu20.04_Server.ova.mda
2. http://webwork.maa.org/ww-downloads/WW2.15_Ubuntu20.04_Server.ova

• Verify the MD5 checksum of your downloaded file agrees with the above. For information on how to verify the MD5 checksum, see e.g. https://help.ubuntu.com/community/HowToMD5SUM

Installing the WeBWorK Virtual Machine Image

Import the file WW2.15_Ubuntu20.04_Server.ova into your virtualization software package (e.g. VMware, VirtualBox). The ova file was created on VirtualBox and has been tested on VirtualBox. After importing, your virtual WeBWorK server will be identical to a system created by following the instructions Installation_Manual_for_2.15_on_Ubuntu_20.04_Server with all Optional Configurations A-E implemented except that

1. openssh-server is not installed and
2. Optional C (SSL) is not implemented

Both the installation of openssh-server and the implementation of Optional C (SSL) and must be done locally (see below)

Note that on some virtual environments, you may need to take additional actions. See the section Other Virtual Environments below.

You should read through the instructions Installation_Manual_for_2.15_on_Ubuntu_20.04_Server to understand how your server has been set up. Especially look at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Terminal Window Notation and Use to understand the notation we use in these instructions.

Processors, Memory, Hard Disk

The WeBWorK Virtual Machine Image was created from a machine with 4 processors, 8 GB of memory and a 20 GB dynamically allocated hard drive in VMDK format. Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they will for VirtualBox running on a Windows host). Adjusting the number of processors and memory should be straightforward. Expanding the hard disk may be more complicated (consult the documentation for your virtual machine environment). For information on networking, see Accessing your server below.

Boot your server

You should see a login prompt (you may have to press <Enter>). Before you login here is some information on accessing your server.

Accessing your server

The ova virtual machine image was created on VirtualBox 6 running on a Windows 10 host with the network adapter set to NAT and certain port forwarding rules in effect. Assuming you have not changed things when importing the image, some of these network setting may remain in effect (they will for VirtualBox running on a Windows host). See Other Virtual Environments below for more information. The port forwarding rules the image was created with are the following:

Port Forwarding

Name	Protocol	Host IP	Host Port	Guest IP	Guest Port
lighttpd	TCP	127.0.0.1	8080	10.0.2.15	8080
ssh	TCP	127.0.0.1	2222	10.0.2.15	22
ssh2	TCP	127.0.0.1	443	10.0.2.15	443
web	TCP	127.0.0.1	80	10.0.2.15	80

The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command

$ ip address show

and looking at the output, something like

 link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff
 inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33

(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 .

If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine (or from the terminal on the guest once you login). We have not yet installed openssh so the secure connections ssh and ssh2 don't work at this point. Assuming your WeBWorK server is set up as above, from a web browser running on your host machine connect to http://127.0.0.1/webwork2 (http://localhost/webwork2 also works) and you should see the "Welcome to WeBWorK!" page. If all you want to do is test out WeBWorK yourself without any other users, you are all set at this point but please read the rest of these instructions so that you understand how insecure your WeBWorK server is right now. Lighttpd is also running (it is only used for internal WeBWorK calls) and you can test it by connecting to http://127.0.0.1:8080/webwork2_files or http://localhost:8080/webwork2_files and you will see the WeBWorK Placeholder page.

Log into your server

1. Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges.
2. If your network uses DHCP, networking will be automatically configured for your system.

Install openssh-server

We need to install the openssh-server so that you can ssh into your server from your host or remote locations.

$ sudo apt install openssh-server
[sudo] password for wwadmin: <wwadmin password>

Now you can connect remotely to your server with ssh but you may have to reboot your server for this to take effect.

Accessing Your Server from a Terminal Emulator on your Host

At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program.

You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with copy from the Edit menu or ^C) and paste them into a terminal window (with paste from the Edit menu list or <Shift> <Ctrl> <V> or <Shift> <Insert> depending on your application).

I am assuming your network has been set up automatically.

The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command

$ ip address show

and looking at the output, something like

 link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff
 inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 

(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 .

If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine (or from the terminal on the guest once you login). Assuming your WeBWorK server is set up as above, from a web browser running on your host machine connect to http://192.168.76.128/webwork2

and you should see

the "Welcome to WeBWorK!" page. If all you want to do is test out WeBWorK yourself without any other users, you are all set at this point but please read the rest of these instructions so that you understand how insecure your WeBWorK server is right now. Lighttpd is also running (it is only used for internal WeBWorK calls) and you can test it by connecting to http://192.168.76.128:8080/webwork2_files and you will see the WeBWorK Placeholder page.

1. Username set to wwadmin (or you can leave it blank and enter it at login)

Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.

Set the Timezone for your server

To find out what timezone your server is set to run the command

$ timedatectl

and you will probably see

...
Time zone: America/New_York (EDT, -0400)
...

which may not be where you live. The timezone naming convention uses a “Region/City” format and to find the correct one for your location run the command

$  timedatectl list-timezones

Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.

$ sudo timedatectl set-timezone America/Los_Angeles
[sudo] password for wwadmin: <wwadmin password>

and then

$ timedatectl

to check it was set correctly.

Checking for and installing hotfixes

Follow the instructions at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Checking for and Installing Hotfixes

Passwords

It is imperative that you CHANGE THE PASSWORDS for the OS user wwadmin (which has sudo privileges) and also for the WeBWorK user admin which has professor privileges both in the admin course and in the myTestCourse. Otherwise anyone can connect to your server and pretty easily gain root access.

Change the password for wwadmin

$ passwd
Changing passwd for wwadmin:
(current) UNIX password: wwadmin
Enter new UNIX password: <new wwadmin password> 
Retype new UNIX password: <new wwadmin password>
passwd: password update successfully
$ 

Do not forget the <new wwadmin password> that you just entered.

Change the password for webworkWrite

Now we change the passwords for the MySQL user webworkWrite. First we edit site.conf.

$ cd /opt/webwork/webwork2/conf
$ nano site.conf

Search for $database_password = "wwadmin"; and replace this by
$database_password = "database_password"; where of course you should replace 'database_password' with your own password. We refer to this password as <database_password>. Remember it as we will need it shortly. Then save the file and Quit.

Then restart Apache so the changes take effect.

$ sudo apache2ctl graceful
[sudo] password for wwadmin: <wwadmin password>
$

and start MySQL

$ sudo mysql
[sudo] password for wwadmin: <wwadmin password>

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users.

mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;

You will see a table with six users (debian-sys-maint, mysql.infoschema, mysql.session, mysql.sys, root and webworkWrite). You should see that five users have a valid password (which will be displayed in encrypted form) and root is authenticated by a socket.

Now we will change the password for the webworkWrite User

mysql> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';

where of course you should replace <database_password> by whatever you used above (use the single quotes but no angle braces). Then

mysql> FLUSH PRIVILEGES;
use your up arrow key to run the command
mysql> SELECT Host, User, authentication_string FROM mysql.user;

and you should see that webworkWrite has a new passwords (which will be displayed in encrypted form).

Then exit MySQL

mysql> exit
Bye
$

If you want to check that you set the password correctly, do the following:

mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp
Enter password: <database_password>

and you should see

Welcome to the MySQL monitor ...
mysql>

Now exit

mysql> exit
Bye
$

Finally a note on the MySQL root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MySQL root user is set to authenticate using the auth_socket plugin by default rather than with a password. However in securing MySQL (see Installation Manual for 2.15 on Ubuntu 20.04 Server#MySQL Security and Performance Issues) we had to set a password for the MySQL root user and that password was set to "wwadmin" even though it is not used.

Change the password for admin

Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (http://localhost/webwork2/admin) and myTestCourse (http://localhost/webwork2/myTestCourse) with Username "admin" and Password "admin". Then change the passwords from "admin" to something more secure.

Set up Access to Apache's server-info and servo-status

Now we will edit configuration files info.conf and status.conf to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using nano. Note that you have to be root to edit these files. First we edit info.conf

$ cd /etc/apache2/mods-available
$ sudo nano info.conf
[sudo] password for wwadmin: <wwadmin password>

I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the # from)

	Require ip 192.0.2.0/24

and then replace 192.0.2.0/24 by .math.yourschool.edu where of course you should edit .math.yourschool.edu appropriately.

Then save the file and quit (press ^X, Y, <Enter>).

Now we edit status.conf

$ cd /etc/apache2/mods-available
$ sudo nano status.conf
[sudo] password for wwadmin: <wwadmin password>

Edit the

 #Require ip 192.0.2.0/24

line just as you did for info.conf. Then save the file and quit. And restart Apache so that the above changes take effect

$ sudo apache2ctl restart
password:<wwadmin password>

Test your server by connecting to "http://localhost/" and/or connecting to your server from a browser on a remote machine. You should see the Apache2 Ubuntu Default Page indicating that Apache is running.

You can check Apache's status by connecting to "http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.

Further test Apache by connecting to "http://localhost/server-info" using a browser on your machine (or or from a browser on a remote machine in the math.yourschool.edu domain) and you will see a page listing various information about Apache. In particular under Server Settings you should see

Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0

(or something very similar) indicating that both mod_apreq2 and mod_perl are installed.

System Configuration

Most WeBWorK configuration is done in the files /opt/webwork/webwork2/conf/site.conf and /opt/webwork/webwork2/conf/localOverrides.conf. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the course.conf file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in localOverrides.conf) in the course.conf file. An instructor can edit the course.conf file for herself (for her own course) but most things instructors may want to customize and many others (language, timezone, permissions, display modes, email, ...) can be set using the Course Configuration page from within the course and such setting override those in the configuration files.

Actually there are three main configuration files, site.conf, defaults.config and localOverrides.conf. The reason there are three configuration files is to make upgrading WeBWorK easier.

• site.conf: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWoeK but it's distribution version, site.conf.dist will be.
• defaults.config: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.
• localOverrides.conf This is where you should add all local customizations. It will not be overridden when you update WeBWoeK but it's distribution version, localOverrides.conf.dist will be.

There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options.

Edit the site.conf file

Now edit site.conf

$ cd /opt/webwork/webwork2/conf
$ gedit site.conf

First we have to add information about the Apache2 server setup. Search for server_root_url and edit the line so that it reads:

$server_root_url   = "http://yourserver.yourschool.edu";

where of course you should edit yourserver.yourschool.edu appropriately or you can keep this set to localhost

Note that above we already set the password that WeBWorK uses when it communicates with the MySQL database. This is set with $database_password and it is not a bad idea to double check that it is correct.

WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the From address on the mail message). Edit the lines

$mail{smtpServer} = ;  # e.g. 'mail.yourschool.edu' or 'localhost'
$mail{smtpSender} = ;  # e.g.  'webwork@yourserver.yourschool.edu'

entering the appropriate information.

WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see DateTime::TimeZone::America::New_York and you should enter $siteDefaults{timezone} = "America/New_York"; which is the default. Read the documentation in this section of the the site.conf file for more information on selecting timezones and formatting dates.

Search for $siteDefaults{timezone} and enter your local timezone if it is not correct.

Then save the file and Quit.

The defaults.config file

If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in defaults.config, you will see the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

But we are not supposed to edit the defaults.config file, so if we want to do this, we will copy this to localOverrides.conf and edit it appropriately. Note that we should probably move this setting to the site.conf file.

Edit the localOverrides.conf file

$ cd /opt/webwork/webwork2/conf
$ gedit localOverrides.conf

As we said above, if you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in localoverrides.config, add and then edit the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

removing the # and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this should be set in course.conf (which you find in the course directory) to the addresses of professors of each course. Note that the settings in course.conf override the settings in site.conf, default.conf and localOverrides.conf so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.

After you have used WeBWorK for awhile, you may want to change the default header files in defaults.config. Search for $webworkFiles{screenSnippets}{setHeader} and $webworkFiles{hardcopySnippets}{setHeader} in localOverrides.config. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in course.conf.

Also now there are several versions of the classlist editor, homeworkset editor, library browser and pgproblem editor. Which ones are available in a course is determined by the settings for %showeditors in localOverrides.conf. As above, if you want to customize what is available for an individual course (e.g. one professor may want to try out the new editors and others may not), copy the %showeditors structure to course.conf and then edit it to make available the desired editors.

Set up WeBWorK to use SSL

This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. Follow the instructions at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Implement Optional C (SSL)

File and Directory Locations and System Information

This installation of WeBWorK and Ubuntu follows the instructions given in Installation_Manual_for_2.15_on_Ubuntu_20.04_Server. You can look there to find the locations of the WeBWorK files. All optional configurations (A-E) are implemented except that

1. Optional A is implemented with the wwtmp directory set up as a separate directory but not as a separate partition and
2. Optional C is not implemented. Optional C configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. You may have already implemented this.

All system files are in their standard Ubuntu locations. The Ubuntu installation is identical to that obtained from the Ubuntu 20.04 Server LiveDVD distribution (specifically ubuntu-20.04-live-server-amd64.iso).

Consult for other WeBWorK documentation for system administrators.

Other Virtual Environments

Below you will find additional information about installing the ova on other virtual environments.

VMware Workstation 15 Player

Port Forwarding

If you want to set up Port Forwarding, find or download the vmnetcfg.exe program. This does not come with Workstation Player but it does come with Workstation Pro. Download Workstation Pro (Do not install it) and look for this program where you installed things. Run the command as root (or as administrator in a Windows powershell)

vmnetcfg.exe

and configure NAT for port forwarding. Say localhost:2222 to e.g. 192.168.76.128:22

VMware's ESXi 5.5 Server

These notes are very old but may still be useful.

Jay A. Hightman <jhightman@mbc.edu>, Systems Administrator at Mary Baldwin College, reports that it is not possible to directly import the "WW2.9_Ubuntu14.04_Vanilla.ova" virtual machine directly in to VMware's ESXi 5.5 Server. There may be a similar problem with "WW2.13_Ubuntu16.04_Vanilla.ova". He sent us the following work around. Thanks Jay.

One gets the following error:

There are three offending sections in the OVA file, which I have highlighted
in red:
     <System>
       <vssd:ElementName>Virtual Hardware Family</vssd:ElementName>
       <vssd:InstanceID>0</vssd:InstanceID>
<vssd:VirtualSystemIdentifier>WW2.9_Ubuntu14.04_Vanilla</vssd:VirtualSystemI dentifier>
       <vssd:VirtualSystemType>virtualbox-2.2</vssd:VirtualSystemType>
     </System>

     <Item>
       <rasd:Address>0</rasd:Address>
       <rasd:Caption>sataController0</rasd:Caption>
       <rasd:Description>SATA Controller</rasd:Description>
       <rasd:ElementName>sataController0</rasd:ElementName>
       <rasd:InstanceID>5</rasd:InstanceID>
       <rasd:ResourceSubType>AHCI</rasd:ResourceSubType>
       <rasd:ResourceType>20</rasd:ResourceType>
     </Item>

     <Item>
       <rasd:AddressOnParent>3</rasd:AddressOnParent>
       <rasd:AutomaticAllocation>false</rasd:AutomaticAllocation>
       <rasd:Caption>sound</rasd:Caption>
       <rasd:Description>Sound Card</rasd:Description>
       <rasd:ElementName>sound</rasd:ElementName>
       <rasd:InstanceID>7</rasd:InstanceID>
       <rasd:ResourceSubType>ensoniq1371</rasd:ResourceSubType>
       <rasd:ResourceType>35</rasd:ResourceType>
     </Item>

A work around is to use the VMware OVF tool to convert the OVA to an VMX image.

Download VMware Open Virtualization Format Tool 3.5.2

https://my.vmware.com/web/vmware/details?downloadGroup=OVFTOOL352 <https://my.vmware.com/web/vmware/details?downloadGroup=OVFTOOL352&productId =353#product_downloads> &productId=353#product_downloads

C:\Program Files\VMware\VMware OVF Tool>ovftool.exe --lax "C:\Setup\MAA WeBWorK 2.9\WW2.9_Ubuntu14.04_Vanilla.ova" "C:\Setup\MAA WeBWorK 2.10\WW2.10_Ubuntu14.04_Vanilla.vmx"

Opening OVA source: C:\Setup\MAA WeBWorK 2.9\WW2.9_Ubuntu14.04_Vanilla.ova
Opening VMX target: C:\Setup\MAA WeBWorK 2.9\WW2.9_Ubuntu14.04_Vanilla.vmx

Warning:
- Line 25: Unsupported hardware family 'virtualbox-2.2'.
- Line 66: OVF hardware element 'ResourceType' with instance ID '5': No support
for the virtual hardware device type '20'.
- Line 83: OVF hardware element 'ResourceType' with instance ID '7': No support
for the virtual hardware device type '35'

Writing VMX file: C:\Setup\MAA WeBWorK 2.0\WW2.9_Ubuntu14.04_Vanilla.vmx

Transfer Completed

Warning:
- No manifest entry found for: 'WW2.9_Ubuntu14.04_Vanilla-disk1.vmdk'.
- No manifest file found.

Completed successfully

After doing this, I was able to upload the VMX and VMDK files which were created to storage on a VMware ESXi 5.5 Server, import the system, and continue the configuration of Ubantu as well as other installed applications used by WeBWorK.

My hope is this information will be useful to you as well as other users of WeBWorK virtual machine.

-- Main.ArnoldPizer - 10 May 2020