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

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 who has access to MySQL, for the WeBWorK user admin who has admin privileges and for the WeBWorK user profa 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 sha1 checksum and the .ova file from the site below. The ova is a 4.3 GB file.

  • MAA
  1. http://webwork.maa.org/ww-downloads/WW2.15_Ubuntu20.04_Server.ova.sha1
  2. http://webwork.maa.org/ww-downloads/WW2.15_Ubuntu20.04_Server.ova
  • Verify the SHA1 checksum of your downloaded file WW2.15_Ubuntu20.04_Server.ova agrees with the one in WW2.15_Ubuntu20.04_Server.ova.sha1.

OVA and OVF Files

The .ova file is simply a tar bundle containing an .ovf file, one or more .vmdk files and a .mf file.

  • The .ovf file is an XML file which describes the packaged virtual machine and is human-readable.
  • The .vmdk file(s) contain the disk images(s).
  • The .mf file contains SHA1 checksums for the above files.

You can import a virtual machine either from an .ova file or from the .ovf, .vmdk, .mf collection. Sometimes importing from the .ova file may fail whereas importing from the .vmdk file will succeed.

You can extract the files in WW2.15_Ubuntu20.04_Server.ova with the command 

$  tar -xvf WW2.15_Ubuntu20.04_Server.ova

You then can look at (and possibly edit) the human readable WW2.15_Ubuntu20.04_Server.ofv file. If you do edit the WW2.15_Ubuntu20.04_Server.ofv file, you will also have to compute the new SHA1 checksum and replace the old one in the WW2.15_Ubuntu20.04_Server.mf file for the files to be usable.

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 VMware Workstation 15 Player running on a Windows 10 host. It has been tested on

  • VMware Workstation 15 Player running on a Windows 10 host

See Specific Virtual Environments below for installation information on specific virtual environments.

Processors, Memory, Hard Disk

The WeBWorK Virtual Machine Image was created with the following parameters:

  • 12 GB dynamically allocated hard drive in VMDK format (single file)
  • 1 GB memory
  • 1 cpu

The above resources are very minimal and (except for maybe disk space) correspond to a AWS t2-micro level machine which is free.

Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they will for VMware Workstation 15 Player running on a Windows 10 host). You should be adjust these resources either when when you import the .ova file or later after you have tested things. 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). After you have expanded the hard disk, you will still have to make the extra space available to Ubuntu (see [[ ]] below).

Import the .ova File

There may be specific information for your situation below. See

Your Server

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
  2. Optional C (SSL) is not implemented
  3. The PGbasicmacros.pl file has been slightly changed (see PGbasicmacros.pl below)

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

PGbasicmacros.pl

The PGbasicmacros.pl file (in the directory /opt/webwork/pg/macros) has been slightly changed to fix a small bug. The original file is PGbasicmacros.pl.bak1 in the same directory. This may or may not be addressed in a WeBWorK 15 hotfix.

Boot your server

Log into your server

You should see a login prompt (you may have to press <Enter>).

  • Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges.

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. In the directions below, the <wwadmin password> is "wwadmin" until you change it. 

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

My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and you new server's ip address (not domain name). After that if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.

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, from a terminal emulator running on your host using ssh, or from the terminal on the guest once you login.

Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.


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 PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access. Also it is IMPERATIVE that you CHANGE THE PASSWORD for the MySQL user webworkWrite who has login privileges to MySQL. Otherwise anyone can connect to MySQL server and pretty easily gain access to the WeBWorK database. Finally it is IMPERATIVE that you CHANGE THE PASSWORD for the WeBWorK user admin who has admin privileges both in the admin course and in the myTestCourse and for the WeBWorK user profa who has professor privileges in the myTestCourse. Otherwise anyone can connect to WeBWorK server and pretty easily gain access and do anything they want.

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://.../webwork2/admin) and myTestCourse (http://.../webwork2/myTestCourse) with Username "admin" and Password "admin". Then change the passwords from "admin" to something more secure.

Change the password for profa

Change the passwords for the WeBWorK user profa. Login to myTestCourse (http://.../webwork2/myTestCourse) with Username "profa" and Password "profa". Then change the passwords from "profa" to something more secure.

Change the password for jsmith

Change the passwords for the WeBWorK user jsmith if you want. jsmith is just a regular student so she can't do any real damage but you may still want to change the password. Login to myTestCourse (http://.../webwork2/myTestCourse) with Username "jsmith" and Password "jsmith". Then change the passwords from "profa" to something more secure.

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)

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.

If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at /var/log/apache2/error.log. In the directory /var/log/apache2/ you can "less" through the error log (less error.log), look at the last few entries (tail error.log) or run the command tail -f error.log which will display new error messages as they are appended to the file. Use ^C to break out of tail -f . For example if you didn't set up access to "server-info", you can run 

tail /var/log/apache2/error.log

and in the output you should see something similar to 

...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations

indicating that both mod_apreq2 and mod_perl are installed and running.



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 (and optionally lighttpd) so that access to WeBWorK will

be through an encrypted connection (TLS/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 Category:Administrators for other WeBWorK documentation for system administrators.

Specific Virtual Environments

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

VMware Workstation 15 Player running on a Windows 10 host

Importing the ova File

For VMware Player select Player, File, Open and then browse to the location of the WW2.15_Ubuntu20.04_Server.ova file and open the file.

You will get a warning message but on retry it will work (strange since the ova image was created on VMware Player).

Accessing your server from your host

VMware Workstation 15 Pro

VirtualBox 6

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.


-- Main.ArnoldPizer - 10 May 2020

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Installing_from_WW2.15_Ubuntu20.04_Server_Virtual_Machine_Image&oldid=19142"