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

From WeBWorK_wiki
Jump to navigation Jump to search
Construction.png 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 VMware Workstation 15 Player and 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

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 and VMware Player. Note on VMware Player you will get a warning message but on retry it will work. 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.

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 "inet 10.0.2.15/24 ..." (not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 10.0.2.15.

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).

Assuming your network has been set up automatically, port forwarding has been set up and uses same ip address and ports as above, set up a SSH connection with

  1. Remote host set to localhost (you can also use 127.0.0.1)
  2. Username set to wwadmin (or you can leave it blank and enter it at login)
  3. Port set to 2222 (this is important, it will probably be set to the default 22)

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

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 (five being root, mysql.session, mysql.sys, mysql.infoschema 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> UPDATE mysql.user SET authentication_string=PASSWORD('<database_password>') WHERE host='localhost' and user='webworkWrite';

where of course you should replace <database_password> by whatever you used above.

mysql> FLUSH PRIVILEGES;

Now 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
$


and test that all is well:

$ sudo /etc/init.d/mysql restart
[sudo] password for wwadmin: <wwadmin password>
$ sudo mysql

You should see

Welcome to the MySQL monitor ...
mysql>

and exit

mysql>bye
$

Change the password for admin

To change the passwords for the WeBWorK user admin, log into the WeBWorK admin course (http://localhost/webwork2/admin) and myTestCourse (http://localhost/webwork2/myTestCourse) and change the passwords from admin to something more secure.

Setting up networking using a static IP address

  1. select Dash Home and type Network Connections
  2. Select the wired connection under Ethernet and hit Edit and look and see if everything is set up correctly and correct any errors
  3. If no connection is set up click Add and then enter your servers IP address, Netmask (usually 255.255.255.0 but possibly 255.255.0.0) and Gateway address (often the same as the IP address with the last number replaced by 1). Important: after entering a number hit the <Enter> key so that the change is recorded.
  4. Next enter the IP address(es) of your DNS server(s)separated by spaces. You need to enter at least one DNS server
  5. Finally enter the search domain Hosts
  6. Click Save
  7. Enter <wwadmin password> and click Authenticate
  8. Click Close

Your network connection should start up almost immediately. If you are still having problems first try rebooting (click on the power button button icon in the upper right hand corner, then select Restart) and if that doesn't work it's time to investigate further or seek help.

Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the hostname commands below.

Run the command

sudo hostnamectl set-hostname webwork
[sudo] password for wwadmin: <wwadmin password>

where of course you should replace webwork by whatever your server's name is (of course webwork is a very good and common name for a WeBWorK server).


You can check these settings by running the commands

$ hostname --fqdn

and

$ hostname

The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).

Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.

For some of these changes to take effect you have to restart your server. So restart the server and then 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 page It works! indicating that Apache is running.

You can check Apache's status by connecting to "http://localhost/server-status" using a browser on your machine.

Further test Apache by connecting to "http://localhost/server-info" using a browser on your machine and you will see a page listing various information about Apache. In particular under Server Settings you should see something like

Server Version: Apache/2.2.22 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.5 Perl/v5.14.2

indicating that both mod_apreq2 and mod_perl are installed. If you want to be able to access "server-status" and "server-info" from a remote location, see the section Installation_Manual_for_2.13_on_Ubuntu_16.04#Apache_2_and_mod_perl

Finally you can find out what ip address your server is using by running the command ifconfig in a terminal window and then in the eth0 section looking at inet addr:

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. Note that this is not the same as the <mysql root password> which is the password the MySQL root user uses. 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.

File and Directory Locations and System Information

This installation of WeBWorK and Ubuntu follows the instructions given in Installation_Manual_for_2.13_on_Ubuntu_16.04. You can look there to find the locations of the WeBWorK files. The option Optional A is implemented (with the wwtmp directory set up as a separate directory but not as a separate partition) but options Optional B and Optional C are not. You can implement these if you choose (you should at least look at them to see what they do). All system files are in their standard Ubuntu locations. The Ubuntu installation is identical to that obtained from the Ubuntu 16.04 desktop LiveDVD distribution with some updates included. If you see the update manager pop up, you should install the recommended updates. Or you can install them by using the Software Updater. To find this select Dash Home and type update.

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's ESXi 5.5 Server

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