EECS Technical Database

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Labtest Mode ======

The purpose of this document is to provide an explanation of what labtest mode is, how to request it for your course, how to set it up, and how to check that it is setup correctly.  If you have any questions about labtest, or if this documentation is unclear to you, please contact tech.  Your feedback allows us to improve our documentation and make it easier for everyone to understand.

====== Introduction ======

Labtest mode provides a secure computing environment for in-lab testing.  In labtest mode, students have access to either all or a limited of software on EECS systems and a course specific labtest web site.  They lose access to all the files in their regular network-shared home directory, sending and receiving e-mail, printing, the external web (except as required), USB key/cdrom/floppy access, existing temporary files stored on the machine, and all access to the Internet including access to other EECS machines (except as required for services such as DNS, DHCP, etc.) and other York services like eClass (except where requested).

Faculty schedule labtests with the EECS tech team.  A labtest reservation sometimes spans multiple computer labs depending on the number of students that will write the labtest at once.  Faculty can schedule certain machines with extra time to accommodate students with alt exam requirements. 

Prior to labtest time, faculty create a web page for their labtest.  The page is only accessible to students on machines in labtest mode for that specific course.   Faculty can use this site to post their questions (often a PDF or HTML), or to host files that the students need for their labtest  (eg. data set).  Faculty can update this page any time before or during the labtest.  Using SecureQ, faculty can provide a different labtest based on the machine name to ensure students sitting side by side write a different test.

Several minutes prior to labtest, students using the lab machines will receive a warning message on their display that the machine will be going into labtest mode and that they need to save their files. After the grace period (default of 5 minutes), the machines will all be rebooted into labtest mode.

Once a machine boots into labtest mode, the login screen displays a banner that indicates that the machine is in labtest mode.  If required, faculty can restrict which user can login to each host.

When students login, they are placed in the default desktop environment. A temporary home directory that is used for their work during labtest mode will be created. A web browser will automatically open and start at the default labtest home page.  A description of labtest mode is displayed, and a disclaimer about remote monitoring.   Students click the “Start Lab Test” button, and are taken to the labtest start page for the given booking.

Faculty can customize what happens when a student logs in to a machine.  For example, they can copy in starter code into the student directory.  A database could be initialized and pre-populated with data.  A certain application can be started automatically.

If there is a power failure during labtest, then after power is restored, students can log back in and continue working on their labtest  (if the labtest is not over).

If there is a hardware failure during labtest, then the student can move to another machine, and when they login, the TA will be prompted to authenticate, and the student data can be restored from anywhere they were previously working.

During labtest, student home directory data is synchronized to a repository every 15 minutes.  Faculty can access the repository at any time and data is maintained for many months.  If students fail to submit, faculty can restore the student work from the repository.

Students will continue to work on their labtest for the duration of the test. Students use either command line submit, web submit, or in some cases eClass to submit their completed work.

During labtest, faculty can use remote monitoring software to monitor student screens in the lab.  They can take complete control of the student lab computer, or lock their screen. They can capture a screenshot.  They can do this all from in the lab, or from home via the web.

A few minutes before the end of the labtest, students will receive a warning message on their display that the labtest is about to end. At the end of the labtest, all the machines are automatically rebooted and placed back into their original mode (Linux or Windows). When a machine is switched back to the standard operating mode, the temporary labtest home directories will be removed, but the final copy of the student data will be synced to the repository.

Faculty can configure a custom list of websites that labtest machines can access during their test with complete URL control.  They can permit or reject whole websites, or even parts of a website using labtests secure proxy.
 
When Faculty are using eClass quizzes in labtest, access to messaging, "private files", and other course pages are automatically blocked.  For all labtests, certain general URLs are permitted such as the ones for PassportYork or DUO Authentication.

During a labtest, faculty can access a web interface to extend the test duration.  For example, if there is no lab booking following the labtest, but a faculty member needs to give the students 15 minutes extra due to a power failure, they can do that without involving tech.

Faculty can test their labtest via the web using labtest cloud (ltcloud) service.  They can access ltcloud from home, or from York.  This crucial service allows faculty to develop and test their labtest in stages, as a student (ltstu).  Before ltcloud came along, labtests would frequently have problems with inaccessible files, or user errors, but now that faculty can test their test as a student, the success rate of labtest is near perfect!

====== Labtest Setup with Labtest Assistant ======

Setting up a labtest requires creating many files and directories on our system.  Labtest Assistant is a tool which will help you setup and manage your labtest with ease.

===== Usage =====

In order to setup your labtest, login to an EECS system via [[https://remotelab.eecs.yorku.ca|remotelab]], then follow these instructions:

Open a Terminal, then start Labtest Assistant (labtest command) and pass in the concatenation of your course number and section (eg. 7777A for EECS7777A) followed by a space and then a test version name (eg. labtest1).  For example, for course EECS7777A if you're having a test that you want to call labtest1:

<code>    
% labtest 7777a labtest1
</code>

NOTE: The test version name can be whatever you choose.  In this case, we chose "labtest1".  Other names might be: labtest1-lab1, labtest1-lab2, midterm, final, or whatever other name you feel describes the purpose of the test. 

After you hit enter, this is what you will see:

<code>
There is no directory setup for this course. Create one ([y]/n) ?y

Creating /eecs/dept/www/course/7777A
Creating /eecs/dept/www/course/7777A/labtest
Creating /eecs/dept/www/course/7777A/labtest/labtest1
Creating /eecs/dept/www/course/7777A/labtest/labtest1/index.html
Creating /eecs/dept/www/course/7777A/labtest/labtest1/ltinit
Creating /eecs/dept/www/course/7777A/labtest/labtest1/labtest.allow

Would you like a submit directory to be set up for labtest1 ([y]/n) ?y

Creating /eecs/course/7777A/submit/labtest1

Welcome to Labtest Assistant. Type "help" for options.

Labtest (7777A) [labtest1] > 
</code>

Labtest Assistant recognized that no labtest had been previously setup for this course.  It created all the required labtest directories, a default labtest start page (index.html), and a directory for labtest submission. 

Now, let's edit the start page for your labtest using the gedit command:

<code>
Labtest (7777A) [labtest1] > gedit
</code>

By default, the default start page for your labtest is called "index.html".   It will be opened in a GUI HTML editor.  This makes it easy for you to edit the start page whether or not you know HTML.  If you prefer to use the "vi" text editor, use the "edit" command instead of "gedit":

<code>
Labtest (7777A) [labtest1] > edit
</code>

Modify the default page, and add your own information such as your rules for the test, and links to other content.  Change the index.html file, and customize it for your test.  By default, index.html includes a link to the file "labtest.pdf".  This file is intended to contain your labtest questions in PDF format.  If you don't want to use this filename, you can change the name to whatever you like.

NOTE: If you're creating a labtest which points to an eClass quiz, you'll want to include a link to your quiz directly on this page.  It will look like this: https://eclass.yorku.ca/mod/quiz/view.php?id=12345 (you'll need to find the ID for your quiz)

After you finish editing index.html, save the file.

Now, let's upload your labtest questions (eg. "labtest.pdf") to your labtest directory.  If you have the file on your PC, you can either sftp the file to indigo.eecs.yorku.ca, or, just drag the PDF from your desktop to your remotelab window.  The file will be placed into your home directory.

Once labtest.pdf is in your EECS home directory, use Labtest Assistant to upload it to your course labtest directory using the "put" command:

<code>
Labtest (7777A) [labtest1] > put labtest.pdf

Put success.
</code>

Labtest Assistant will ensure that file permissions are setup correctly.

Students will be able to submit their work to your labtest with [[https://wiki.eecs.yorku.ca/dept/tdb/services:submit:cli-submit|command line submit]] or [[https://wiki.eecs.yorku.ca/dept/tdb/services:submit:websubmit|web submit]].

When you create a new labtest, Labtest Assistant automatically asks you if you want it to set up a submission directory for your test:

<code>
Would you like a submit directory to be set up for labtest1 ([y]/n) ?y
</code>

If you choose "y", the submission directory will be created, and enabled.  It will have the same name as your test version name (eg. "labtest1").  When students are writing a test labtest1, they will only be able to submit to a submission directory called "labtest1".  

If you are doing an eClass based labtest, you might not need students to submit anything, so you'll answer the question with "n". 

If you make a mistake, it's easy to fix:

<code>
Labtest (7777A) [labtest1]  > submit add

Submit directory added.  It is enabled by default.

Labtest (7777A) [labtest1]  > submit del

Submit directory deleted.
</code>

The default labtest start page already includes a link to web submit: https://webapp.eecs.yorku.ca/submit

Congratulations!! Your labtest is now setup!  

Once you submit your [[https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#requesting_labtest_mode|labtest booking request]] to the tech team, they will give you a custom URL which you can use to test your test in [[https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#labtest_cloud_ltcloud|Labtest Cloud]].

===== Available Commands =====

Labtest Assistant provides assistance in many areas of labtest setup.  Use the "help" command for more information:

<code>
Labtest (7777A) [labtest1] > help

status                                       Display labtest status
list                                         List labtest files/directories
get <labtest-file> [<local-file>]            Download labtest file
put <local-file> [<labtest-file>]            Upload local file to labtest
rename <labtest-file> <labtest-file>         Rename labtest file
delete <labtest-file>                        Delete labtest file
edit [<labtest-file>]                        Edit labtest file (Default: index.html)
gedit [<labtest-file>]                       Edit labtest file in GUI editor (Default: index.html)
import <version>                             Import labtest version from current session
import <session> <term> <course> [<version>] Import labtest from another session/term (Default version: default)
files                                        Open labtest directory in file manager
ltcloud                                      Open Labtest Cloud web page
fix                                          Fix file permissions
restore <user>                               Restore files from <user>
clear                                        Clear the screen
quit                                         Quit

lock help                                    Display lock help options
ltinit help                                  Display ltinit help options
restrict help                                Display URL restriction help options
submit help                                  Display submit help options

help/?                                       Display this help text
</code>

A few notes:

  * You'll see that you can not only "put" files into your labtest, but you can get them out as well with the "get" command.
  * You can rename and delete files.
  * If you've taught the course before, and taken the time to setup a labtest, you can use the import command to copy the entire labtest from a different course directory, even if it's from a different session or term.  If you'd like to import a test from another test you've already created this term, you can use the import command with just a version.
  * You can use the "files" command to open up the file manager in the GUI so you can manipulate the labtest files easily.
  * You can use the "ltcloud" command to open up a web browser and go to the Labtest Cloud page.
  * You can use the "fix" command to check and fix all file and directory permissions in your labtest.  This is automatically run every time you exit the "labtest" command, so you don't have to run it manually.
  * You can use the "restore" command to restore student files should they forget to submit.

There are also a few subcommands in Labtest Assistant - lock, ltinit, restrict, and submit which will be described below.

===== Labtest Lock =====

<code>
Labtest (7777A) [labtest1] > lock help

Labtest Lock Mode Help:

In labtest lock mode, the student is placed in a limited environment
with no access to a terminal.  By default, the only application available
is Firefox web browser.  Additional applications can be made available.

lock enable                                 Enable lock mode
lock disable                                Disable lock mode
lock list                                   List apps in lock mode
lock add <app> [<opts>] [<display-name>]    Add app to lock mode
lock delete <app>                           Delete app from lock mode
lock help                                   Display this help text

NOTE: As there is no access to a terminal, apps must bring up a GUI.

Example:

Enable lock mode (by default includes Web browser access only):

> lock enable

Want to make Eclipse available in lock mode?

> lock add eclipse

Add Matlab to lock mode (requires the option -desktop):

> lock add matlab -desktop

DISCLAIMER: Not all applications are suitable for lock mode.  For example, VSCode
            requires access to the terminal for compiling and debugging code.
</code>

===== Labtest Init =====
 
<code>
Labtest (7777A) [labtest1] > ltinit help

Labtest Ltinit Help:

ltinit list                                 List files in ltinit
ltinit get <ltinit-file>                    Download file from ltinit
ltinit put <local-file> [<ltinit-file>]     Upload file to ltinit
ltinit rename <ltinit-file> <ltinit-file>   Rename file in ltinit
ltinit delete <ltinit-file>                 Delete file from ltinit
ltinit edit <ltinit-file>                   Edit file from ltinit
ltinit help                                 Display this help text
</code>

Using the "ltinit" subcommand, you can get, put, rename, delete, or edit files in your labtest ltinit directory.  The files in the ltinit directory are copied to each students ltinit folder when they login.  For more information on ltinit, see [[https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#custom_file_copy_on_user_login_optional|here]].  Use of ltinit in labtest is entirely optional.

===== Labtest Restrict =====

<code>
Labtest (7777A) [labtest1] > restrict help

Labtest URL Restriction Help:

restrict list                                List labtest URL restrictions (including line numbers)
restrict add <restriction> [<line number>]   Add labtest URL restriction <restriction>
restrict eclass                              Allow access to eClass (*)
restrict delete <line-number>                Delete restriction <restriction>
restrict edit                                Edit labtest restrictions
restrict help                                Display this help text

To allow access to www.w3schools.com, and validator.w3.org:

labtest> restrict add www.w3schools.com
labtest> restrict add validator.w3.org

To reject one page on www.w3schools.com:

labtest> restrict add -www.w3schools.com/html/html_editors.asp

(*) To allow access to eClass Quiz/VPL, please read the following web page:

https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#accessing_external_hosts_in_labtest_eclass_example

*** Don't forget - ALWAYS test your eClass quiz using ltcloud! https://webapp.eecs.yorku.ca/ltcloud ***
</code>

By default, labtest doesn't permit students to access external websites.  Using the "restrict" subcommand, you can allow access to other web sites if your labtest requires it.  For more information on the restriction format, please refer to this page:

  * https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#accessing_external_hosts_in_labtest_optional

For eClass specific restrictions, please refer to this page:

  * https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#accessing_external_hosts_in_labtest_eclass_example

Labtest restrictions are entirely optional.

===== Labtest Submit =====

<code>
Labtest (7777A) [labtest1] > submit help

Labtest Submit Directory Help:

submit status        Display submit directory status
submit add           Add labtest submit directory
submit delete        Delete empty submit directory
submit enable        Enable submission  
submit disable       Disable submission
submit files         Open submit directory in file manager
submit help          Display this help text
</code>

====== Requesting Labtest Mode ======

Each term, the technical team books a significant number of labtests.  Please help us to make the process more efficient by ensuring that your labtest booking request contains all the required information in the proper format.

The **first time** in a term when you book a labtest for a course, please provide us with:

  * Course Number (eg. EECS1012)
  * Course Section (eg. A)
  * EECS faculty admin user IDs (they will be able to check the test using our LTCloud service) (eg. bob) (*)
  * EECS TA user IDs (they will be able to help students move between machines in a labtest) (eg. johns, alicez, aigha) (*)

(*) Please make sure that you **only send us EECS user IDs** - not full names, not gmail, or other alternate email.  While EECS usernames should be the same as a users Passport York username, some TAs don't apply for an EECS account, and may not have one yet!  In this case, they won't be able to help your students move between machines during your test.  You can search for a users name [[https://webapp.eecs.yorku.ca/directory|here]] or by using the "finduser" command on our system (eg. finduser abc).  If you find that your TA doesn't have an EECS account, then please insist that they e-mail tech to request an account.  In this case, you can report their PPY username so that when their account is created, it will have access as an admin to your test.

For **subsequent** labtest bookings in your course, please always include in your booking:

  * Course Number (eg. EECS1012)
  * Course Section (eg. A)

You do not need to include EECS faculty admin user IDs or EECS TA user IDs with subsequent bookings, **unless they change**.

Please provide the details of your labtest booking **in this format only**, every time you book:

<code>
# <optional description>
#version: <optional labtest version name>
MM/DD/YYYY  HH:MM M labtest HOSTSPEC
MM/DD/YYYY  HH:MM M default HOSTSPEC
</code>

... where:
  * <optional description> is just a description of your test (eg. labtest1-LAB1) - it's entirely optional, and you don't need to provide it.
  * If you have setup multiple versions of your labtest, you'll need to let us know the version name for this test.  (eg: #version: labtest1-lab1) -- if you configured your labtest to use a version name (eg labtest1-lab1), and you don't include the version name in your booking, then labtest will not display the right start page! Remember - if you don't specify a version name, a version name of "default" is automatically assumed. 
  * MM/DD/YYYY - month, day, and year for your labtest (eg. 06/20/2023)
  * HH:MM - hour:minute hour of your test (note that this is impacted by the next field)
  * M - number of minutes of warnings to send to students before system will reboot (usually 5) - NOTE: If M=5, machines will REBOOT at HH:MM + 5 MIN, NOT at HH:MM
  * HOSTSPEC - lets us know which hosts you want to book. <HOSTSPEC> can contain:
    * individual machines separated by commas: ea01,ea02,ea03
    * groups of machines: 
      * To specify machines ea01-ea78 use: ea 01-78
      * To specify machines ptl01-ptl10p use: ptl 01-10
    * You can even exclude machines using a minus (-):
      * To include machines ea01-ea78, but exclude ea10 and ea11: ea 01-78,-ea10,-ea11

Here's information on the machines typically booked for labtest:

^Room^Hosts^# Hosts^HOSTSPEC^
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:1002.pdf|LAS1002]]|ptl01 - ptl32|32|ptl 01-32|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:1002b.pdf|LAS1002b]]|ptlb01 - ptlb25|25|ptlb 01-25|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:1006a.pdf|LAS1006]]|ea01 - ea78|78|ea 01-78|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:1004.pdf|LAS1004]]|gsp01 - gsp32|32|gsp 01-32|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:wsc105lab.pdf|WSC105]]|wsc105-01 - wsc105-48|48|wsc105- 01-48|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:wsclab.pdf|WSC106]]|wsc106-01 - wsc106-49|49|wsc106- 01-49|
|[[https://wiki.eecs.yorku.ca/dept/tdb/_media/services:wsclab.pdf|WSC108]]|wsc108-01 - wsc108-49|49|wsc108- 01-49|

**NOTE:** Click on the room name to see the room layout.
 
**NOTE:** The "Hosts" column refers to hosts you want to book.  The "HOSTSPEC" column tells you how to specify those hosts in your booking request.

Please only submit your labtest booking request including times **reserved for your course**.  That is, if you have reserved LAS1006 for 9:00 AM to 10:00 AM, please do not submit a labtest booking requesting 9:00 AM - 12:00 PM unless you first confirm with tech that the space can be reserved for you for the additional time that you require. 

Here's an example labtest booking to get you started:

<code>
# labtest1-LAB1
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea 01-78
06/20/2023   11:45 5 default ea 01-78
</code>

Description:

  * On June 20, 2023 at 9:54 AM, machines ea01-ea78 in las1006 will display (to logged in users) a warning that the machines will reboot in 5 minutes into labtest mode.  The machines will remind students once per minute until the 5 minutes have elapsed.
  * The machines will reboot into labtest mode at 9:59 AM, so they should be ready by 10:00 AM.
  * On June 20, 2023 at 11:45 AM, machines ea01-ea78 in las1006 will display (to logged in users) a warning that the machines will reboot back to Linux mode in 5 minutes.  The machines will remind students once per minute until the 5 minutes have elapsed.
  * At 11:50 PM, machines will reboot from Labest mode back to Linux mode.

**Please ensure that your labtest ends 10 minutes prior to the end of your lab booking time.**  For example, if your lab time is 10:00 AM - 11:30 AM, then the students should receive their 5 minute warning at 11:45 AM, then the machines will reboot at 11:50 AM. 

If you used a labtest version name of labtest1-lab1 for this booking, you would add the additional version line to the booking request:

<code>
# labtest1-LAB1
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea 01-78
06/20/2023   11:45 5 default ea 01-78
</code>

If you have students with different accommodations for extra time, please submit a **separate** block for each accommodation type.  Here's the same booking request above with 5 machines getting an extra hour, 2 machines getting 30 minutes extra, and 1 machine getting 20 minutes extra.  **Accommodations cannot exceed your lab booking time.  In order to book machines past your lab booking time, please consult with tech.**

<code>
# labtest1-LAB1 MAIN
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea 01-70
06/20/2023   11:45 5 default ea 01-70

# labtest1-LAB1 ACCOMMODATION - 5 machines getting extra hour
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea 71-75
06/20/2023   12:45 5 default ea 71-75

# labtest1-LAB1 ACCOMMODATION - 2 students getting extra 30 minutes
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea 76-77
06/20/2023   12:15 5 default ea 76-77

# labtest1-LAB1 ACCOMMODATION - 1 student getting extra 20 minutes
# version: labtest1-lab1
06/20/2023   09:54 5 labtest ea78
06/20/2023   12:05 5 default ea78
</code>

**Remember - your labtest booking must end 10 minutes before your lab booking.**

Notice that the start and end blocks must be grouped together.  Please do not group all the start blocks, then all the end blocks separately.

If you are booking back to back labtest sessions (eg. 9:00 AM - 11:00 AM, then 11:00 AM - 1:00 PM), you have two choices:  You can reboot machines between sessions (this is why we end the first session 10 minutes before the end of the lab time):
<code>

# labtest1-LAB1
# version: labtest1-lab1
06/20/2023   08:55 5 labtest ea 01-78
06/20/2023   10:45 5 default ea 01-78

# labtest1-LAB2
# version: labtest1-lab2
06/20/2023   11:00 0 labtest ea 01-78
06/20/2023   12:50 5 default ea 01-78
</code>

...  or you can create one long session 9:00 AM - 1:00 PM, but you will have to clear the lab manually between sessions yourself:

<code>
# labtest1-LAB1 and LAB2
# version: labtest1
06/20/2023   08:55 5 labtest ea 01-78
06/20/2023   12:45 5 default ea 01-78
</code>

After you have submitted your labtest booking, someone from tech will get back to you to confirm your booking.  If you don't get back a confirmation email from tech, then your session has **not** been booked.  You can check the labtest booking schedule [[http://www.eecs.yorku.ca/schedule/pcmode/|here]] at any time.

If you have any questions about labtest booking, please e-mail the technical team.

====== Basic Labtest Setup ======

Now that we've seen how to setup a labtest using Labtest Assistant, we'll look at how to setup a labtest manually.  Of course if you're using Labtest Assistant, you **do not** have to complete these steps!!

In order to setup a basic labtest, you must complete the following 4 basic steps:

===== 1.  Create Directories =====

First, if you haven't done so yet, create a course directory for your course.  For example, if your course was "EECS9999A", you would:

  mkdir /eecs/dept/www/course/9999A

Now create a subdirectory in the course web directory called "labtest":

  mkdir /eecs/dept/www/course/9999A/labtest

Inside the labtest directory, create a directory for each version of the test that you will have.  If you will only have one test version (which is the most common scenario), this directory is called "default":

  mkdir /eecs/dept/www/course/9999A/labtest/default
  
If you have a course with multiple labs at different times throughout the week, you may choose to have different test versions.  You can create a directory for each version (instead of creating the "default" directory):

  mkdir /eecs/dept/www/course/9999A/labtest/test1
  mkdir /eecs/dept/www/course/9999A/labtest/test2
  mkdir /eecs/dept/www/course/9999A/labtest/test3

NOTE: For the purposes of simplicity, this documentation will frequently refer to /eecs/dept/www/course which is a shortcut that refers to the course web directories for the current session and term. If you would like to refer to a course directory by its full path, you may use instead: /eecs/dept/www/course_archive/SESSION/TERM/COURSE.  For example, /eecs/dept/www/course_archive/2018-19/F/9999A.
 
===== 2.  Create a Labtest Start Page =====

Students will see the labtest start page when they begin your labtest.  Create an HTML start page in your "labtest" directory, and call it "index.html".  

If you have only one test version, the full path to the file might be: /eecs/dept/www/course/9999A/labtest/default/index.html

If you have three test versions, you would have: /eecs/dept/www/course/9999A/labtest/test1/index.html, /eecs/dept/www/course/9999A/labtest/test2/index.html, /eecs/dept/www/course/9999A/labtest/test2/index.html

==== Basic Start Page ====

Here's a basic example of a labtest start page:

<code>
<!DOCTYPE html>
<html>
<body>
<h1>EECS1234</h1>

<p>Welcome to the labtest for EECS1234</p>

<p>You could write a lot of introductory stuff here, or even write your question using HTML on this page.</p>

<p>Click <a href="test.pdf">here</a> for your labtest question.</p>

<p>You could include links to other resources on this page that could be available in labtest.</p>

</body>
</html>
</code>

On your start page, you can include information about the test, your rules and policies, the labtest questions (or a link to a PDF with the questions), and links to additional useful resources (such as PDFs) which you can include in your labtest directory.

For your convenience, you may choose to provide a link to "/common" on your index page.  This link contains the Java API, and other documentation that is useful across labtests.  In non-labtest mode, the information appears [[http://www.eecs.yorku.ca/teaching/docs|here]].  
 
Note: You cannot include links to content outside your labtest web directory.  Your regular course directory, or other Departmental web links will not be available during labtest.

==== eClass Quiz Start Page ====

If you are hosting your labtest as an eClass quiz, then your start page can redirect the student to the eClass quiz page like this:

<code>
<!DOCTYPE html>

<html>
<head>
<meta http-equiv="refresh" content="5; URL= https://eclass.yorku.ca/mod/quiz/view.php?id=12345" />
</head>
<body>

<p>Redirecting you to eClass. If you are not redirected in 5 seconds, <a https://eclass.yorku.ca/mod/quiz/view.php?id=12345">click here</a>.</p>

</body>
</html>
</code>

NOTE: Replace "12345" with the quiz ID of your eClass quiz.

===== 3.  Create and/or Install Additional Content =====

Create additional HTML pages to be part of your labtest, copy in images, PDFs, etc.  

Note:  "/" in a link refers to your labtest web directory.  Links that do not start with a "/" refer to files/directories in the current directory.  Links may never start with "http:" as external web links will not be accessible in labtest mode.

===== 4.  Fix File and Directory Permissions =====

The web server serving your files is running as user labtest and group labtest.  All faculty are in group labtest.  Ensure that files and directories are accessible by group labtest so that the web server can serve them.  

Make sure that your course directory is accessible to the labtest user:

  chmod 755 /eecs/dept/www/course/9999A

Make sure that your labtest directory and all subdirectories and files are group labtest:

  chgrp -R labtest /eecs/dept/www/course/9999A/labtest

Make sure that your labtest directory is accessible to everyone:

  chmod 755 /eecs/dept/www/course/9999A/labtest

Make sure that each of your labtest version directories are accessible to only you and group labtest:

  chmod 750 /eecs/dept/www/course/9999A/labtest/*

Make sure that your index.html is readable by group labtest.  For example:

  chmod 640 /eecs/dept/www/course/9999A/labtest/default/index.html

You will also want to make sure the other files and directories inside your labtest folder are also readable by group labtest.

Be very careful with your labtest directory permission!  Failure to set the permission correctly could allow students to access content unintentionally.

An automatic system process which runs every hour will check and fix your top-level labtest directory permission if set incorrectly.

If you have any doubt about your labtest directory and file permissions, please consult with tech.

You can fix all labtest directory permission for your course with the "ltfix" command: 

  ltfix /eecs/dept/www/course/9999A
  
... it will ensure that the outer labtest directory is mode 755.  It will check that the internal labtest version directories are mode 750.  It will ensure that file and directory permissions specified for "user" and duplicated to group and other.

====== Submit ======

During labtest, your students will submit their work using one of two methods:

  * [[services:submit:cli-submit|Command line submit]]
  * [[services:submit:websubmit|Web Submit]]

If they use web submit, they will be automatically logged in.

===== Submit Directory Setup =====

Whether your students will be submitting via command line submit, or web submit, you must follow this procedure to setup a submit directory to accept lab submissions:

1.  Create and set permissions on a "submit" directory in your course directory: 

  mkdir /eecs/course/9999
  mkdir /eecs/course/9999/submit
  chmod 755 /eecs/course/9999
  chmod 755 /eecs/course/9999/submit 

2.  Create a lab submission directory inside the "submit" directory and set permissions accordingly: 

  mkdir /eecs/course/9999/submit/lab1
  chmod 770 /eecs/course/9999/submit/lab1
  chgrp labtest /eecs/course/9999/submit/lab1

**IMPORTANT** Students will **only** be able to submit in labtest mode to lab submission directories that are group labtest.  

NOTE: If you get an error when trying to change group ownership of the lab submission submit directory to group "labtest", please contact tech.  

===== Submission =====

In labtest mode, students can submit their work via the command line like this:

  submit <course> <assignment> <file1> <file2> <file3>
-OR-
  submit <course> <assignment> <dir1> 

When your labtest is setup, it will be connected to a specific session, term, and course.  The submit command will only allow submission to the submit directory in that one session, term, and course. If you are holding a deferred test, and you need students to submit their work to the submit directory in a course directory from a previous session and term, be sure to let tech know this at the time of your booking, or submission will fail.  Read more information on command line submit [[services:submit:cli-submit|here]].

Students can also submit using [[https://webapp.eecs.yorku.ca/submit|web submit]].  They will be automatically logged in.  If your link to web submit includes the actual submit folder name, that submit folder will be automatically selected.  For example: https://webapp.eecs.yorku.ca/submit?assignment=labtest1

Like command line submit, the session, term, and course directory will not be switchable by the student, and must be configured at the time of your labtest booking.  Read more information on Web Submit [[services:submit:websubmit|here]].

===== Returning Labtest Submissions to Students Following Labtest =====

Sometimes, following a labtest, faculty want students to be able to retrieve their labtest submission.  

In order to make this possible, complete the following steps:

Copy the files from the labtest submit directory to a different directory - for example:

  cd /eecs/course/9999A/submit
  cp -pr labtest1 labtest1-return
  
Make all the files in the new submit directory readable by group "submit":

  chgrp -R submit labtest1-return
  
Finally, ensure that students can only retrieve their submission, and not re-submit:

  chmod 750 labtest1-return

Now, when students login to web submit outside of labtest, and choose their course, they will see an assignment "labtest1-return", and will be able to retrieve their submitted files. Since the directory is not writable, the students will not be able to modify and re-upload their submission.

====== Unsubmit (optional) ======

In labtest mode, students start with an empty home directory.  The optional unsubmit component of labtest enables faculty to provide students with access to previously submitted content which can be used for reference or a starting point for a test.

NOTE: unsubmit is not available to students using the generic "user" account.

===== Enabling Unsubmit =====

To enable unsubmit, please follow these four steps:

1) Check to ensure that the permission of your course submit directory allows access by anyone in group submit:

  % ls -ald /eecs/course/9999/submit
  drwxr-xr-x 10 bob faculty 4096 Sep  3 23:31 /eecs/course/9999/submit

This submit directory is owned by user bob, group faculty, and allows "r-x" for other,  hence anyone in group submit would be able to access this directory.

2) Check to ensure that the permission of any assignment subdirectories in the submit directory for which you wish to allow unsubmit are readable and executable by the submit group:

  % ls -ald /eecs/course/9999/submit/a1 /eecs/course/9999/submit/a2
  drwxr-x--- 107 bob submit  4096 Sep 14 11:30 /eecs/course/9999/submit/a1
  drwxr-x---  38 bob submit  4096 Sep 19 12:10 /eecs/course/9999/submit/a2

Both a1 and a2 are group submit, and r-x.

3) Create a file called "unsubmit" in each of the submit assignment subdirectories in the submit directory for which you wish to allow unsubmit:

  % touch /eecs/course/9999/submit/a1/unsubmit /eecs/course/9999/submit/a2/unsubmit

4) Ensure that the unsubmit files created above are readable by everyone:

  % chmod 644 /eecs/course/9999/submit/a1/unsubmit /eecs/course/9999/submit/a2/unsubmit

That's it!  Unsubmit is now setup.  However, please continue reading this document for other important details about unsubmit.

===== What Can Students Expect? =====

When a student logs in during a labtest for which unsubmit has been enabled, the student will see an "unsubmit" directory in his home directory containing his previously submitted work.  For example:

  % ls
  unsubmit
  % cd unsubmit
  % ls
  A1 A2
  % cd A1
  % ls
  a1.java

It is important to note that the contents of the unsubmit directory are **READ ONLY**.  If a student wishes to modify previously submitted work, he **must** copy it out of the unsubmit directory.  For example:

  % cp unsubmit/A1/a1.java ~/newa1.java
  % jedit ~/newa1.java

If the student tries to modify the copy of a1.java in the unsubmit directory, he will get "permission denied" errors.  

===== Additional Important Details on Unsubmit =====

  * Submit data is copied from submit directories to a local unsubmit cache **before** students get the "Your machine will be rebooted in 5 minutes" message, just prior to their test.  **Anything** that students submit **after the reboot warning** will **not** be available in the unsubmit cache without additional intervention by you (see below).  As a result, students must be made aware that they should submit anything that they expect to be able to unsubmit **10 minutes** prior to the beginning of the test.
  * The contents of your submit directory **must** be readable by the group "submit" including the "unsubmit" file.  <fc red>Failure to set the correct permissions on all files before your test begins will mean that your students will not be able to unsubmit without additional work by you (see next point).</fc>
  * If you do not setup your unsubmit directory properly, or you forgot to remind your students to submit their data 10 minutes prior to the test, you can refresh the unsubmit cache by logging in to https://webapp.cse.yorku.ca/pcmode (from a machine not in labtest mode), and click the "Refresh Unsubmit Cache" button at the bottom of the screen.  Students will need to log out and back in to have the local copy of their unsubmit cached refreshed.
  * The "unsubmit" directory that students see when they login is READ ONLY.  If students wish to make changes, they need to copy the data out, and modify it accordingly.
  * Only text files will be unsubmittable.  Any other files (eg. .class, .jar) will not be copied to the users unsubmit directory.

====== User Restriction Setup (optional) ======

By default, when you reserve the lab for Linux or Labtest mode, your booking will have no user restrictions.  That is, any student can login to any lab machine including students who are not even part of your course.  In this case, you or your TAs will need to check attendance and ensure that all students who are in the lab should be there.

Sometimes, you may wish to automatically restrict who can login to lab machines during your test.  For example, if your course has multiple sections, and you want to ensure that  students in each section can only write at their respective time, you can setup user restrictions.

Setting up user restrictions requires the following process:

  - Determine which method of user restriction you will use:
    * Allow Multiple Users To All Hosts: You provide a list of usernames allowed to login to all the systems in your test.
    * Allow Multiple Users to Custom Hosts: Maybe you've reserved extra time on a few workstations for individual users.  Reserve login to those hosts to just those users while still applying default restrictions to the other hosts.
    * Allow Single User Per Host: You specify a user for each host in the lab.  Users can only login to the machine reserved for them.
    * Print Name Only: You specify a name to be printed on the login screen.  No real restrictions apply. This is used primarily for first year courses where all students login with the "user" account.
  - Setup user restriction
  - Ask tech to enable your booking with user restrictions.  Note that if you don't do this, any user restriction setup that you do will be ignored by the system.

Let's look a the different user restriction types:

===== Restriction Type: Allow Multiple Users =====

With this restriction type, you provide a list of usernames allowed to login to all the systems in your test.

Place a file called //users.allow// in your course directory - /eecs/course/<COURSE>.  This file contains one username that is allowed to login per line.  For example, if only users bob and sally are allowed to login during your booking for EECS9999, then /eecs/course/9999/users.allow would contain:

  bob
  sally

The users.allow file may also contain an optional "#include" directive to include users from other files.  For example:

  #include /eecs/course/9999/users.contest
  #include /eecs/course/9999/otherusers

**IMPORTANT NOTE:**  The //users.allow// file **must** be readable by the system, or it will be ignored and your restrictions will not be followed.  To make the //users.allow// file for EECS9999 readable by the system: chmod o+r /eecs/course/9999/users.allow

When the machines boot into Linux or Labtest mode, a "RESERVED" message will appear on the login screen.  If a student who is not in the allow list tries to login, he will see a message as follows:

  The computer that you are trying to use has been reserved and 
  is not available for your use at this time.  Sorry for any
  inconvenience.

If you want to allow access to your test to only users who are enrolled in your course, then you can extract this information from the distribution list prior to your test.  For example:

<code>
% awk '{ print $1 }' /eecs/dept/dist/EECS9999 | grep -v "<NO-CS-ACCT>" > /eecs/course/9999/users.allow
% chmod 644 /eecs/course/9999/users.allow
</code>

===== Restriction Type: Allow Multiple Users to Custom Hosts =====

With this restriction type, you provide a list of usernames allowed to login to particular hosts. 

Place a file called //users.allow.<HOSTNAME>// in your course directory - /eecs/course/<COURSE>.  This file contains one username per line that is allowed to login to host <HOSTNAME> during your test.  For example, if only users bob and sally are allowed to login to ea01 during your booking for EECS9999, then /eecs/course/9999/users.allow.ea01 would contain:

  bob
  sally

You can still include a default //users.allow// file to apply restrictions to all the other hosts in the lab.

For more information, see the above section on "Restriction Type: Allow Multiple Users".

===== Restriction Type: Allow Single User Per Host =====

With this restriction type, you specify which one user can login to each host.  Place a file called //users.allow.byhost// in your course directory - /eecs/course/<COURSE>.  This file is of the following format:

  <hostname>,<user>

For example:

<code>
ea01,bob
ea02,sally
</code>

When ea01 boots, in addition to the "RESERVED" banner on the login screen, a message will appear on the screen: 

  Reserved For: Bob Smith

User bob's full name is read from the system.

When ea02 boots, in addition to the "RESERVED" banner on the login screen, a message will appear on the screen:

  Reserved For: Sally Mojo

User sally's full name is read from the system.

User "bob" can only login to ea01.  User "sally" can only login to ea02.

The //users.allow.byhost// file may also contain an optional "#include" directive.  For example:

  #include /eecs/course/9999/users.contest
  #include /eecs/course/9999/otherusers

A few important notes:

  * If you have a //users.allow.byhost// file, any //users.allow// or //users.allow.<host>// files will be ignored.
  * If the //users.allow.byhost// file does not exist, anyone can login. 
  * If you restrict users to one particular host, and that one particular host goes down, the student won't be able to login to any other host in the lab without either you or your TAs intervention (by updating the users.allow.byhost file).
  * If a hostname is not included in the list, anyone can login to it.  You may want to choose a host that you setup specifically like this, and use it as a "backup" in case one of the hosts goes down during your test.
  * **IMPORTANT NOTE:**  The //users.allow.byhost// file **must** be readable by the system, or it will be ignored and your restrictions will not be followed.  To make the //users.allow.byhost// file for EECS9999 readable by the system: chmod o+r /eecs/course/9999/users.allow.byhost

When the machines boot into Linux or Labtest mode, a "RESERVED" message will appear on the login screen.  If a student tries to login to a system that is reserved for a different user, he will see a message as follows:

  The computer that you are trying to use has been reserved and 
  is not available for your use at this time.  Sorry for any
  inconvenience.

===== Restriction Type: Print Name Only =====

This isn't really a user restriction type.  First year courses have students login with a generic "user" account.  Often, these courses assign students to individual hosts. Since all users login as "user" in these courses, it is sometimes convenient to be able to print a name on the display to help aid students in finding the right system.  In order to set this up, place a file called //users.allow.byhost// in your course directory - /eecs/course/<COURSE>.  This file is of the following format:

  <hostname>,<user>,<fullname>

Here, we remove the username from the list altogether, or use username "user".

With this line in //users.allow.byhost//, any user can login to ea01, but the login screen will include a message: "Reserved For: Bob Smith".

  ea01,,Bob Smith

Add user "user" in the second field to only allow login by user "user" on ea01:

  ea01,user,Bob Smith

Please read the notes from the section "User Restriction Type: Allow Single User Per Host" because they apply here as well.

===== Checking User Restrictions =====

If you wish to test whether a user will be able to login during your lab booking, you can use the //pcmode-allow// command.  This is the identical command used by the system during login to verify whether a user should be able to access a given machine. For example, assume that your booking has ID 6 (as per the pcmode schedule), and you want to check whether a user "bob" will be able to login to "ea01" during your test.  Execute the //pcmode-allow// command as follows:

  % /xsys/pkg/pcmode/bin/pcmode-allow -i 6 -h ea01 bob

Proper responses will be one of:

  * [if bob is in group tech/faculty/submit]: user bob is a member of a system group exempt from pcmode access restrictions for host ea01 id 6 and can login.
  * [users.allow.byhost in use]: warning: host ea01 does not exist in restriction file /eecs/course/9999/users.allow.byhost - everyone will be allowed access
  * [users.allow.byhost in use]: user bob does not meet pcmode access restrictions in /eecs/course/9999/users.allow.byhost for host ea01 id 6 and cannot login
  * [users.allow.byhost in use]: user bob meets pcmode access restrictions in /eecs/course/9999/users.allow.byhost for host ea01 id 6 and can login.
  * [users.allow.<hostname> in use]: user bob does not meet pcmode host access restrictions in /eecs/course/9999/users.allow.ea01 for host ea01 id 6 and cannot login.
  * [users.allow.<hostname> in use]: user bob meets pcmode host access restrictions in /eecs/course/9999/users.allow.ea01 for host ea01 id 6 and can login.
  * [users.allow in use]: user bob does not meet pcmode access restrictions in /eecs/course/9999/users.allow for host ea01 id 6 and cannot login.
  * [users.allow in use]: user bob meets pcmode access restrictions in /eecs/course/9999/users.allow for host ea01 id 6 and can login.
  * warning: found no system readable restriction file for id 6 - everyone will be allowed access
  
NOTES:

  * Users who are in the tech, faculty, and submit system groups are automatically exempt from login restrictions.  These users do not need to be included in your //users.allow// or //users.allow.byhost// file.
  * If you have an empty //users.allow// file, then nobody can login (except as indicated above).
  * If you have an empty //users.allow.byhost// file, then everybody can login.
  * If your //users.allow// or //users.allow.byhost// file is missing, this has the same effect as no restriction at all - anyone can login.
  * If a student was forgotten from //users.allow// or a guest student showed up, you may edit //users.allow// or //users.allow.byhost// during the booking to correct the issue.
  * The permission of the //users.allow// or //users.allow.byhost// files are **very** important.  Each file **must** be readable by the system.  For example: chmod 644 //users.allow//. If you make the //users.allow// file writable by submit group, then your TA (who would normally be in the submit group) should be able to fix any last minute mistakes during the lab session.
  * At this time, users restrictions are available for Labtest or Linux modes, but not Windows.
  * Please note that if you enable user restrictions on your booking, you need to be **extra careful** to ensure proper syntax in //users.allow// and //users.allow.byhost//, and that your //users.allow// or //users.allow.byhost// file includes ALL users who need to login.  TAs need to be aware of user restrictions so that they do not panic if a student is unable to login.

** DISCLAIMER: **

Please note that once you enable user restrictions, there is always the potential to inadvertently restrict students from logging in who should otherwise be able to login.  For example, if you've verbally told a student they can attend a different sections test, but you forgot to add the student to the allow list for the alternate test, then they won't be able to login.  Once you enable user restrictions, you and your TAs are responsible for ensuring who can login. 

====== Custom File Copy on User Login (optional) ======

If you want to be able to initialize a students labtest home directory with certain files  or directories when he logs in, simply create a directory called "ltinit" in your labtest directory (/eecs/dept/www/course/<COURSE>/labtest/ltinit).  The directory should be group labtest. ALL the files and directories in this directory readable by group labtest will be automatically copied to the ltinit directory in the student account when they login.  Student files will never be overwritten, so if a student modifies files in the ltinit directory, and they log back in, the file will not be recopied from the server.

For example:

<code>
cd /eecs/dept/www/course/9999/labtest/ltinit
mkdir -p a1
chmod 750 a1
cp ~/a1/a1.java a1
chmod 640 a1/a1.java
chgrp -R labtest ltinit
</code>

When the student logs in, he will have a directory in his home directory called "ltinit".  It will contain a directory "a1". That will contain "a1.java".

If you are experimenting with this functionality for your course, please consult with tech. 

====== Custom Shell Script Execution on User Login (optional) ======

Labtest can run a custom shell script on login in order to initialize a student home directory.  You can use this functionality to customize the student account.  The shell script must be called "labtest.sh" and must be located in the ltinit subdirectory of your labtest web directory (/eecs/dept/www/course/<COURSE>/labtest/ltinit/labtest.sh). 

Let's assume a course of EECS9999.  Let's say you have a folder called "a1" in /eecs/dept/www/course/9999/labtest/<version>/ltinit/a1.  You want this folder to be copied directly to the users home directory (not in the ltinit subdirectory).  You would create /eecs/dept/www/course/9999/labtest/<version>/ltinit/labtest.sh containing:

<code>
#!/bin/sh

cp -r ~/ltinit/a1 ~
</code>

Now let's assume you have a zip file called "project.zip" in /eecs/dept/www/course/9999/labtest/ltinit.  You want to create a directory called "project" in the users home directory, and unzip project.zip into this directory.  You would create /eecs/dept/www/course/EECS9999/labtest/ltinit/labtest.sh containing:

<code>
#!/bin/sh

mkdir ~/project
cd ~/project
unzip ~/ltinit/project.zip
</code>

In order to ensure that labtest.sh is executed when the user logs in, you must set the correct file group and permission.  The file must be group labtest, and readable and executable:

<code>
chgrp labtest /eecs/dept/www/course/9999/labtest/ltinit/labtest.sh
chmod g=rx /eecs/dept/www/course/9999/labtest/ltinit/labtest.sh
</code>

If you are using commands from /eecs/local/bin in ltinit, please ensure that you set the PATH variable accordingly in your labtest.sh script. For example, if you were installing a custom extension for vscode, and you want to use the "code" command in your script, ensure that /eecs/local/bin is in the PATH:

<code>
#/bin/sh

PATH=/eecs/local/bin:$PATH; export PATH
code --install-extension ~/ltinit/myextension.vsix
</code>

If you are experimenting with this functionality for your course, please consult with tech. We can review your script with you before your test, and place a machine into labtest mode to check that it works the way you expect.

====== Labtest Lock Mode (optional) ======

By default, users in labtest can still use any software on our systems.  If you enable locked mode, you'll be able to restrict students to using only particular software, or even just a web browser! Use of locked mode is entirely optional.

To enable locked mode with just a web browser only, touch the file "lock" in your labtest directory.  For example:

  % touch /eecs/dept/www/course/9999/labtest/default/lock
  % chmod 644 /eecs/dept/www/course/9999/labtest/default/lock
  
Now if you test your labtest in ltcloud, the user will only be able to access the Firefox web browser.

If you want additional software to be accessible in labtest, it must use a GUI.  You add to the lock file lines of the following format:

  <app name>,<OPTIONAL app arguments>,<OPTIONAL app display name>

For example, if you want Eclipse to be available in lock mode, you would add to the lock file:

  eclipse

By default, there are no optional arguments, and if no alternate display name is mentioned, then it will appear in the menu with the same name as the command name, but with the first letter capitalized ("Eclipse").

If you want to add Matlab:

  matlab,-desktop

In order to run "Matlab", we have to pass "-desktop".  It would appear in the menu as "Matlab".

On the other hand, if you wanted to include Visual Studio Code, you would add:

  code,,Visual Studio Code

Now, "Visual Studio Code" will be displayed in the menu, but it will execute the command "code".

In labtest lock mode, the window environment is a little different in order to support the locked down nature of the environment.    

When labtest mode is started, a web browser will appear with the labtest start page.  Additional software will be available by right clicking the desktop, or by clicking on the "Apps & Logout" menu in the bottom left corner of the desktop.

Please ensure that you're careful when allowing access to software in lock mode.  Giving access to additional software may have unintended side effects.  For example, if you allow access to Eclipse, then students can compile and run code which can give access to system resources that would otherwise not be available.  Access to a terminal is still blocked.

====== Accessing External Hosts In Labtest (optional) ======

Your labtest may require students to access external websites.  For example, if you're teaching a course on web development, you may want your students to be able to access https://www.w3schools.com during your labtest. You can restrict access to a complete website, or even a part of a website!  In the next section we'll even cover restricting access to an eClass quiz. 

With host level access control, you can give your labtest access to specific websites such as https://www.w3schools.com.  Students will be able to access any URL on the given sites.

Let's say you're teaching a course EECS9999, and you want students in your labtest to be able to access "https://www.w3schools.com" and "https://validator.w3.org" web sites during your test:

**Setup With Labtest Assistant**

From within Labtest Assistant, use the "restrict" command:

<code>
Labtest (9999) [labtest1]  > restrict add www.w3schools.com

Restriction www.w3schools.com inserted.

Labtest (9999) [labtest1]  > restrict add validator.w3.org

Restriction validator.w3.org inserted.
</code>

You can use "restrict edit" to edit the restriction list in a text editor, or "restrict list" to list restrictions.  Use "restrict help" for more information on the options that are available.

**Setup Manually**

If you are setting your labtest up manually, create a file called "labtest.allow" in your labtest web directory (/eecs/dept/www/course/<COURSE>/labtest/labtest.allow).  Include in this file complete website names that you want students to be able to access during your test, one per line.  For example:

<code>
www.w3schools.com
validator.w3.org
</code>

Ensure that the labtest.allow file is readable by group labtest:

<code>
chgrp labtest /eecs/dept/www/course/9999/labtest/labtest.allow
chmod g=r /eecs/dept/www/course/9999/labtest/labtest.allow
</code>

**Please note that if the web site you are trying to access includes links to other sites that you want to work, or includes files from other sites (eg. css style file or font file), then you may need to add additional entries to your labtest.allow file.  Contact tech for assistance.**

Labtest also makes it possible to implement partial access to a website.  For example, if you wanted your students to only be able to access https://www.w3schools.com/html during your test (and not the main page https://www.w3schools.com, or https://www.w3schools.com/css, https://www.w3schools.com/jss, etc), then you set it up like this:

**Setup with Labtest Assistant**

From within Labtest Assistant, use the "restrict" command again:

<code>
Labtest (9999) [labtest1]  > restrict add www.w3schools.com/html

Restriction www.w3schools.com/html inserted.

Labtest (9999) [labtest1]  > restrict list

     1	www.w3schools.com/html
</code>

**Setup Manually**

Add "www.w3schools.com/html" to your labtest.allow file instead of "www.w3schools.com" alone.

Now, during your labtest, if you try to visit anything but "https://www.w3schools.com/html", you will receive an error: "Access to this URL is blocked.".

However, you will also notice that the page doesn't display properly.  If you look at the page source you will realize that this is because the page is trying to access fonts from "https://www.w3schools.com/lib", and CSS from "https://www.w3schools.com/plus".  You can easily add these additional entries:

**Setup with Labtest Assistant**

Once again, use the restrict command:

<code>
Labtest (9999) [labtest1]  > restrict add www.w3schools.com/lib

Restriction www.w3schools.com/lib inserted.

Labtest (9999) [labtest1]  > restrict add www.w3schools.com/plus

Restriction www.w3schools.com/plus inserted.

Labtest (9999) [labtest1]  > restrict list

     1	www.w3schools.com/html
     2	www.w3schools.com/lib
     3	www.w3schools.com/plus
</code>

**Setup Manually**

Add "www.w3schools.com/lib" and "www.w3schools.com/plus" to labtest.allow.  It will now look like this:

<code>
www.w3schools.com/html
www.w3schools.com/lib
www.w3schools.com/plus
</code>

Now, let's say there's a particular URL under https://www.w3schools.com/html that you don't want the student to be able to access (eg. https://www.w3schools.com/html/html_editors.asp).  This can easily be handled as well:

**Setup with Labtest Assistant**

Again, use the restrict command:
<code>
Labtest (9999) [labtest1]  > restrict add -www.w3schools.com/html_editor.asp

Restriction -www.w3schools.com/html_editor.asp inserted.

Labtest (9999) [labtest1]  > restrict list

     1	www.w3schools.com/html
     2	www.w3schools.com/lib
     3	www.w3schools.com/plus
     4	-www.w3schools.com/html_editor.asp
</code>

**Setup Manually**

Add the following rule to labtest.allow:

  -www.w3schools.com/html/html_editors.asp

NOTE: Rejected URL fragments are processed before accepted URL fragments.  Add this rule to the bottom or top of your labtest.allow file, and it will have the same effect.

A few important notes:

1) For every website that students needs to be able to access during labtest, you must either use "restrict add <site>" in Labtest Assistant to add the restriction, or manually add the restriction to the labtest.allow file.  You may include just the website name (in which case all URLs on that site will work), or you may include the URLs on that website that you want to be accessible. 

2) All external pages are rejected by default.

3) Reject fragments are processed before accept fragments.  The moment a match is found, processing stops.

4) You need to accept not only the pages that the student will view, but the pages required to display the web page properly.

5) Always test your labtest in ltcloud every single time!  Just because your labtest.allow rules work for one test doesn't mean that the resources that you're trying to allow access to haven't changed between tests.  Testing your labtest in ltcloud ensures the smoothest experience for you and your students.

====== Accessing External Hosts In Labtest (eClass Example) ======

eClass is the name of the Moodle-based Learning Management System (LMS) used at York University.  Many faculty use eClass quizzes from within labtest.  This poses a few challenging problems:

  * Students can upload files to eClass under "Private Files" before a quiz, then access those files during the quiz.  
  * During a quiz, students have access to all course materials posted to any eClass course page where the student is registered.  The faculty member will not know what materials students can access.
  * Students have access to eClass course forums.
  * Students have access to eClass communication and can chat with other students.

In this section, we will configure labtest to provide secure access to an eClass quiz.

===== 1.  Allow Lab Machines Limited Access To eClass In Labtest Mode =====

First, you need to allow the lab machines limited access to eClass in labtest mode.

If you're using Labtest Assistant, use the "restrict eclass" command:

<code>
labtest> restrict eclass
</code>

If you're not using Labtest Assistant, you need to create a labtest.allow file in your labtest directory which includes the allowed URL parts for eClass:

<code>
eclass.yorku.ca/login
eclass.yorku.ca/auth
eclass.yorku.ca/pluginfile.php
eclass.yorku.ca/theme
eclass.yorku.ca/lib
eclass.yorku.ca/local
eclass.yorku.ca/repository
eclass.yorku.ca/course/switchrole.php
dm7crvy4e45rz.cloudfront.net
eclass.yorku.ca/mod/quiz/startattempt.php
eclass.yorku.ca/mod/quiz/attempt.php
eclass.yorku.ca/mod/quiz/processattempt.php
eclass.yorku.ca/mod/quiz/summary.php
eclass.yorku.ca/mod/quiz/review.php
eclass.yorku.ca/mod/quiz/autosave
</code>

===== 2. Determine Your eClass Quiz URL =====

Visit your eClass quiz from your machine that is **not** in labtest mode. Grab the quiz URL from the URL bar in your web browser.  The URL will look something like this: https://eclass.yorku.ca/mod/quiz/view.php?id=12345

You can also get this link in eClass if you go to: Activities >> Quizzes then hover your mouse over your quiz.

===== 3. Allow Access To Your eClass Quiz ID In Labtest Mode =====

If you're using Labtest Assistant, use the following command to allow access your eClass quiz in labtest:

<code>
labtest> restrict add eclass.yorku.ca/mod/quiz/view.php?id=ID
</code>

Replace ID with your eClass Quiz ID.

If you're not using Labtest Assistant, add the following line to the end of your labtest.allow file in your labtest directory:

<code>
eclass.yorku.ca/mod/quiz/view.php?id=ID
</code>
  
Replace ID with your eClass Quiz ID.

Ensure that the labtest.allow file is readable: <code>chmod 644 /eecs/dept/www/course/COURSE/labtest/labtest.allow</code>

===== 4. Provide a Link to Your eClass Quiz in Your Labtest Start Page =====

Your labtest start page (eg. /eecs/dept/www/course/<COURSE>/labtest/index.html) (or a PDF that your start page refers to) **must** include a direct link to your specific eclass quiz. You found this URL in step 2.

If you're using Labtest Assistant, open your labtest start page using the "gedit" (GUI editor) or "edit" (text editor) commands and add a link to your eClass quiz on the page.  For example:

<code>
Click <a href="https://eclass.yorku.ca/mod/quiz/view.php?id=12345">here</a> to take the quiz.
</code>

If you're not using Labtest Assistant, open the index.html file in your labtest directory, and add the link manually.

**IMPORTANT** If students try to access "https://eclass.yorku.ca" in their web browser during your labtest, **they will be blocked**.  Students can **only** visit your quiz by clicking on the link to the quiz from your labtest start page. 

===== 5. Restrict IP Addresses Which Can Access Your eClass Quiz From Within eClass =====

Login to eClass.  Restrict access to your eClass quiz to the IP addresses of the lab machines where the students will be writing the quiz.  If you don't do this, even though your in-lab students will be limited in the proper way, students who are outside of the lab would also be able to write your quiz.  Go to: Activities >> Quizzes >> Settings >> Extra restriction on attempts >> Show more... >> Require network address.  Please copy and paste the specific address list below:

^Lab Location^IP Restriction^
|LAS1002|130.63.96.168/29,130.63.96.176/28,130.63.96.192/29|
|LAS1002B|130.63.96.203/32,130.63.96.204/30,130.63.96.208/28,130.63.96.224/30|
|LAS1004|130.63.96.131/32, 130.63.96.132/30,130.63.96.136/29,130.63.96.144/28,130.63.96.160/31,130.63.96.162/32|
|LAS1006|130.63.96.48/28,130.63.96.64/27,130.63.96.96/28,130.63.96.112/29,130.63.96.120/30,130.63.96.124/31|
|LAS2007|130.63.96.230/31,130.63.96.232/29,130.63.96.240/31|
|WSC105|130.63.131.34/31,130.63.131.36/30,130.63.131.40/29,130.63.131.48/28,130.63.131.64/28,130.63.131.80/31,130.63.131.19|
|WSC106|130.63.131.84/30,130.63.131.88/29,130.63.131.96/27,130.63.131.128/30,130.63.131.132/32,130.63.131.19|
|WSC108|130.63.131.135/32,130.63.131.136/29,130.63.131.144/28,130.63.131.160/28,130.63.131.176/29|
|LTCLOUD|130.63.94.193/32,130.63.94.194/31|

NOTES: 
  * If you are using all 3 of WSC105, WSC106, AND WSC108, use instead: 130.63.131.0/24
  * If you are testing in ltcloud, please ensure that you include both the IP range for the required lab followed by a comma followed by the ltcloud range.
  * If your test is being conducted in several labs, you can join two IP ranges with a comma in between them.  Note though that if the number of IP ranges separated by commas exceeds 18, the IP restrictions will not function correctly due to an eClass bug.  Please consult with tech to test your IP range prior to your test.

===== 6. Limit the Start and End Time of Your Quiz in eClass =====

You will need to limit the start and end time of your quiz in eClass.  If you don't do this, then students on the lab machines will be able to access your quiz **before** your labtest!  Go to: Activities >> Quizzes >> Settings >> Timing and configure the "Open the quiz" and "Close the quiz" times.  Note that if students try to access the quiz before the open time, they will be denied because eclass will try to redirect them back to the course eclass page which has been blocked.  They should try again at the start time of your test.

Final Notes:

  * Some faculty would like to use eClass "assignment" in labtest. Note that eClass assignments do not permit IP address restriction.  A quiz with 1 question can replace an "assignment".
  * If you're using VPL, you'll need to allow access to the following URL fragments with either "restrict add" in Labtest Assistant, or manually in your labtest.allow file:
    * eclass.yorku.ca/mod/vpl/view.php?id=ID
    * vpl1.eecs.yorku.ca
  * **Always test your eClass quiz using ltcloud!  Don't assume that just because it works fine from your unrestricted PC that it will work fine in labtest. Ensuring that your quiz works in ltcloud will guarantee an improved experience in your test session. **

====== SecureQ Setup (optional) ======

SecureQ can be used together with labtest to provide a facility for ensuring that students working side by side during a test are not working on identical questions.

===== Before Setting up SecureQ =====

In order to setup SecureQ, you must know the following:

1.  What labs will be used for your test? 

For example - there are 78 ea hosts in LAS 1006, ea01 through ea78.   There are 32 gsp hosts in LAS 1004, gsp01 through gsp32.  There are 32 ptl hosts in LAS 1002A, ptl01 through ptl32.

2.  Who will be allowed to write your test? 

By default, everyone with a valid EECS username and password who is logging into a machine in labtest mode that meets the lab specification above can write your test.  This is usually sufficient.  However, you can restrict access to your site further should you so choose.  For example, you can limit the site to only students officially enrolled in your course, users in a particular unix group, etc. (This functionality is not available in WSC labtest mode.)

3.  How many questions (or unique sets of questions) do you have for your test?

In general, 2 sets of questions should be more than enough to ensure that students working side by side are not working on the same test, but you can have as many sets of questions as you like.  In fact, you can even have different sets of questions in each lab!

===== Setting up SecureQ with mksecureq =====

In order to setup SecureQ, use the "mksecureq" command as follows:

  % mksecureq -l <lab> -n <number of sets of questions> <labtest dir> 

Use the -l option to specify the labs you will be using.  You can use more than one -l option if you are using multiple labs for your test.  Here are a few options for -l:

  * -l ea refers to the hosts in LAS1006
  * -l gsp refers to the hosts in LAS1004
  * -l ptl refers to the hosts in LAS1002A
  * -l ptlb refers to the hosts in LAS1002B
  * There are many other groups of hosts available.  Run the mksecureq command with no options for a list of additional labs.

If you do not specify the -l option,  the default is just "-l ea -l ltcloud".  This includes the machines in LAS1006, and the machines in LTCloud available for testing your labtest. If you specify your own -l options, "-l ltcloud" is always added automatically.  This allows you to test your labtest via [[https://wiki.eecs.yorku.ca/dept/tdb/services:labtest:start#labtest_cloud_ltcloud|LTCloud]].

For example, to create a secureq directory with 2 default questions for ea lab for course 9999:

  % mksecureq /eecs/dept/www/course/9999 
  
If you are using machines outside of the list of labs available to mksecureq, then you will need to manually add them to SecureQ.  More details on this will be provided below.

Use the -n option to specify the number of sets of questions that you will be generating for your test.  If you do not specify the -n option, the default is 2 question sets.

<dir> is the full path to the root of your labtest directory. For example: /eecs/dept/www/course/9999/labtest.  mksecureq will create <dir> if it does not already exist, as long as you have access to create it.

(optional) mksecureq uses mkhtaccess to restrict who can get a question from your SecureQ site. The default arguments passed will be -S which means that anyone with a valid EECS account can get a question from your site. Add the -p option if you wish to specify different arguments to the mkhtaccess command.  In general, this is usually unnecessary.  If you need assistance, please contact tech.

mksecureq creates a default index.html file in <labtest dir> if one does not already exist. This is normally where your default labtest start page will be, and if you already have an index.html file there, it will not over-write it. On the default index.html start page, you will see a link to SecureQ that looks like this:

  To get your question, click <a href="secureq.cgi">here</a> 

If you already had a default index.html file, you will need to add a link to secureq on your own as above.

Please Note: After running mksecureq, the files in your directory will be group labtest. If you use "emacs" to edit any of those files, it will reset the group permission on files that you edit to your primary group (eg. "faculty") which will cause labtest to fail. You must reset the group on all files back to "labtest" for labtest mode to work. 

===== SecureQ Directory Structure =====

Inside the secureq directory you will find three directories - log, map, and questions. 

The "questions" directory contains the question sets. You specified the number of question sets using the "-n" option to mksecureq.  For example, if you ran mksecure with "-n 2" (the default), then you will find two files in the "questions" directory after running mksecureq - 1.html is automatically used for question set 1, and 2.html is used for question set 2.  These are straight HTML files, and you can put whatever content you want inside.
 
Also inside the "questions" directory is the file "questions.conf".  questions.conf is a text file that maps questions to the lab machines that you specified using the "-l" option to mksecureq!   The format of the file is:

  machine (space or tab) question set file

For example, if ea01 is assigned "1.html", then you will see an entry in questions.conf that looks like this:

  ea01 1.html

By default, mksecureq simply creates a list of all the machines from all the labs that you specified with -l,  and assigns the questions as follows -- first machine gets the first question set, the second machine gets the second question set, and so on until the list of questions is exhausted, and then it starts over.

NOTE: Any documents other than the question files themselves that are placed into the questions directory will NOT be accessible in labtest mode.  If your question files need additional support files (PDFs, images, etc.) then place those outside of the questions directory.

The "log" directory (which will initially be blank) will contain one file per user, with the name of the user who successfully logs into SecureQ. The log entries will look something like this: 

<code>
Tue Feb 21 15:31:24 EST 2006 user: bob, host: ea05, question: 2.html
Tue Feb 21 15:34:14 EST 2006 user: bob, host: ea06, error: user assigned question 2.html, but machine question is 1.html
</code>

The first log entry here says that user "bob" was assigned question 2.html on ea05.  The user bob then tried to login a few minutes later to ea06 to see if he could get a different question set!  The second log entry shows that bob tried to view the question set assigned to ea06, but was denied.  In the event that bob's machine malfunctions, logging into another machine will give bob a message that tells him which other machines are assigned his identical question.

The "map" directory (which will also be initially blank) will contain one file per user with the name of the user who has successfully been assigned a question set by SecureQ. The file will only contain the filename of the question set that the user has been assigned. For example, in the case above, "map/bob" exists and contains:   

  2.html 

This means that bob was assigned question set "2.html".  Again, if bob tries to login to any other machine that has not been assigned to 2.html, he will not be able to see the questions there.

NOTE: If, during the test, you need to have the user assigned a different question set, you can modify the students map file "map/bob" manually, and adjust it to point to another question, but be careful because if you make a typo, bob won't be able to get any question!  Alternatively, you can delete the map/bob file altogether, and now bob can login to any machine and will be assigned the question set assigned to that machine.

All files and permissions are automatically generated by the mksecureq utility. Furthermore, a .htaccess file is placed in the secureq directory which denies web access to the files and directories. An .htaccess file is also placed in the root of your labtest site which limits access to your labtest based on your access specifications. 

If you happen to delete a file from the SecureQ tree, you can simply re-run mksecureq. It will only create files or directories that do not exist. 

**WARNING: **  Before you can re-use the same secureq directory for another test, at a minimum, you must move any existing "secureq/map" directory out of the way. This directory contains files which track which question each of your students received on the test, and on what machine.  This will limit which question they can receive on your new test, and on what machine they can work.

===== SecureQ Security =====
 
SecureQ will only work from EECS department machines. If you try to use SecureQ from outside of the department, you will get a message as follows: 

<code>
secureq is not available from this host. 
</code>

The secureq directory must retain its 770 mode, and group labtest ownership, or SecureQ will not run. 

A secureq.cgi wrapper file is copied to your top-level labtest directory. It must not be deleted, or SecureQ will not run. It exists mostly so that when you are testing your site in your own personal web area, the web server can run SecureQ as you. The script must be owned by you, and your primary unix group (eg. faculty). The script file must be mode 755, and the directory that the script file is in must not be writable by group/other. 

Inside the secureq directory, the internal directories log, map, and questions should retain their 770 mode, and group labtest. The files in the "log", and "map" directories will always be generated with mode 660, and group labtest. The question files and question configuration files in the questions directory will be mode 640, and group labtest. 

**IMPORTANT TO CLEAR LOGS/MAPS BEFORE A TEST**
\\
WARNING: Before you can re-use the same secureq directory for another test, at a minimum, you must move any existing “secureq/map” directory out of the way. This directory contains files which track which question each of your students received on the test, and on what machine. This will limit which question they can receive on your new test, and on what machine they can work

====== Labtest File Synchronization (ltsave) ======

During labtest, student home directories are stored locally on the machine where each student is working.   Lab machines will send a compressed copy of each local labtest home directory to the file server under these circumstances:

  * Every time a user logs out of a machine that is in labtest mode.
  * Every time a machine is restarted that is in labtest mode. 
  * Every 15 minutes when a machine is in labtest mode. (In order to ensure that not all machines are sending data to the file server simultaneously, each machine will choose a random time to synchronize for the first time within the first 4 minutes, and will then syncronize every 15 minutes thereafter.)

Accessing ltsave data might be helpful for a number of reasons, including:

  * Monitoring student progress during a test.
  * Retrieval of forgotten submissions. 
  * Enabling students to move between machines during a test.

===== Accessing Ltsave Data (ltrestore) =====

Use the //ltrestore// command to access saved user labtest data.

Usage is as follows:

<code>
ltrestore <course> <user> - view all saves for <user> in <course>
ltrestore <course> <user> <id> <host> <timestamp> - restore <user> data
</code>

Let's say your student "bob" forgot to submit a file "labtest1.zip" in the labtest for course EECS9999.  First, let's see what data is available to restore for user "bob" in EECS9999 labtests:

<code>
% ltrestore 9999 bob 

Available restore points:

9999 bob 134 ea02 02-08-2024-10:11:13
9999 bob 134 ea02 02-08-2024-10:26:27
9999 bob 134 ea02 02-08-2024-10:41:41
9999 bob 134 ea02 02-08-2024-10:56:54
9999 bob 134 ea02 02-08-2024-11:12:09
9999 bob 134 ea02 02-08-2024-11:27:23
9999 bob 134 ea02 02-08-2024-11:42:38
9999 bob 134 ea02 02-08-2024-11:50:23
</code>

We can see that there are actually 8 different restore points!  However, all we really care about is the last one.  Simply run ltrestore again, and this time paste in the data from the last line above:

<code>
% ltrestore 9999 bob 134 ea02 02-08-2024-11:50:23
Creating /cs/home/jas/ltrestore
Creating /cs/home/jas/ltrestore/9999-bob-134-ea02-02-08-2024-11:50:23 ...
Restoring /eecs/ltsave/course/9999/134/ea02/bob/02-08-2024-11:50:23.txz ...
Done.
</code>

Now, all you need to do is change into the newly created "ltrestore" directory in your home directory, and you'll find the restored user data:

<code>
% cd ~/ltrestore
% ls
9999-bob-134-ea02-02-08-2024-11:50:23/
% cd 9999-bob-134-ea02-02-08-2024-11:50:23/
% ls
Desktop/  eclipse-workspace/  ltinit/  mail/
</code>

Now let's search for the file "labtest1.zip":

<code>
% find . -name "labtest1.zip"
./ltinit/labtest1.zip
</code>

We found it!  The file could be restored.

If necessary, you can restore multiple restore points as well:

<code>
% ltrestore 9999 bob 134 ea02 02-08-2024-10:11:13
...
% ltrestore 9999 bob 134 ea02 02-08-2024-10:26:27
...
% ltrestore 9999 bob 134 ea02 02-08-2024-10:41:41
...
</code>

===== Location of Ltsave Data =====

Faculty have direct access to the ltsave data in the /eecs/ltsave directory on EECS tech-supported Linux systems.  While it is easier for Faculty to use the //ltrestore// command to restore student data, they also have direct access to the data in the filesystem if they choose.

The path right up to the student files will look like this:

  /eecs/ltsave/course/<COURSE>/<ID>/<HOST>/<USER>/MM-DD-YYYY-HH:MM:SS.txz

For example, the submission for course 9999, labtest ID 103, host ea01, user jas, taken November 11, 2014 at 17:28:40 would be stored in the file /eecs/ltsave/course/9999/103/ea01/jas/06-01-2009-12:25:25.txz.

The ".txz" extension on the timestamp stands for "tar" and "xz".  tar is a method of storing many files together in a single archive, while xz is a compression format much like "zip", used because of its high compression ratio.

NOTE: Files are tarred and compressed on the local machine.  In order to save space, and minimize load and network traffic to the file server, if two simultaneous synchronizations are identical, the second one will be dropped.

===== Find A Student Ltsave Data =====

If you know the course, and labtest ID, and want to find a students ltsave data, you do it like this:

  % find /eecs/ltsave/course/9999/103 -maxdepth 2 -name "jas"
  /eecs/ltsave/course/9999/103/ea01/jas

Here, we can see that for course "9999", labtest ID "103", machine "ea01", user "jas" was logged in.

===== List All Ltsave Data For A Student =====

Once you've identified the directory containing the ltsave data for a student, simply list the files to view all the data for that student:

  % ls /eecs/ltsave/course/9999/103/ea01/jas
  11-11-2014-17:13:27.txz  11-11-2014-17:19:53.txz  11-11-2014-17:28:40.txz 

Here we can see 3 ltsave archives.

===== Listing Files Inside an Ltsave Archive =====

To see a list of files in an ltsave archive:

<code>
% tar --force-local -tf /eecs/ltsave/course/9999/103/ea01/jas/11-11-2014-17:28:40.txz
./
./.cshrc
./file1
./file2
./file3
</code>

NOTE: The --force-local option is required because tar considers files with a : in their name to be on a remote server.

===== Extracting Files From an Ltsave Archive =====

You can extract all the files from an ltsave archive like this:

<code>
% cd /tmp
% mkdir restore
% chmod 700 restore <- ensure the privacy of the restore directory 
% tar --force-local -xf /eecs/ltsave/course/9999/103/ea01/jas/11-11-2014-17:28:40.txz
% ls
file1 file2 file3
</code>

You can also selectively extract files as well:

<code>
% tar --force-local -xJf /eecs/ltsave/course/9999/103/ea01/jas/11-11-2014-17:28:40.txz ./file1
</code>

NOTE: If you will be extracting multiple student submissions, be sure to extract each submission into a different directory.  Otherwise, files and directories from one submission may over-write the files and directories with subsequent restores.

NOTE: It is significantly easier to use the //ltrestore// command to restore student data instead of using //tar// directly.

===== Retention =====

Ltsave data that is copied to /eecs/ltsave **will be saved for 60 days ONLY** after which it is deleted, and not recoverable.  **Labtest data is NOT backed up as part of our daily backup routine.**

====== Moving Students from One Machine to Another ======

Sometimes, during labtest mode, you may require a student to move from one machine to another machine.  This may be because the student is in the wrong area of the lab, or because there is some failure on the machine (eg. monitor).  Labtest home directories are stored on the local machine, and not a network drive.  Moving a student to another machine without some mechanism to copy student files from one machine to the other would mean starting with a brand new home directory, no files, and an unhappy student! 

When a student moves from one machine to the another, and logs in, the system will check if the student has files from another machine stored in the labtest save cache.  If they do, the student will see the following message: "Welcome!  It seems you have worked on this labtest on another machine.  You may ask one of the test supervisors for approval to transfer your work to this machine, or, hit Cancel to start again.".  At this point, if the student hits "Cancel", then they are logged in with a new environment without restoring their files.  If they want to restore their files from another machine, they need either **your** or your TAs approval!

To restore a students files from another machine, you will need to enter 3 pieces of information -- Labtest Admin (userid), Password, and Restore Machine.  Select the labtest admin from the dropdown list.  The labtest admins are specified by you when you request labtest mode.  The admins are also displayed in the pcmode schedule.  It's important that you check the list of admins before every labtest because neither the lab monitor nor tech staff will be able to restore a students files.   After selecting your name from the admin list, enter your system password.   Next, under "Restore Machine", a dropdown box lists all the machines where the student has been.  Select a machine from which you wish to restore the students files, and click "OK".  

After the system has verified your identity, the next screen will give you a list of all the last (up to) 15 date and times of syncs made from this students account on the selected machine.  For simplicity, the most recent sync will be first.  Select the date and time fo which you wish to restore the students files, and click "OK".  The files will be restored.  
Hit "Cancel" to return back to the main menu to select a different machine.

Every (approximately) 15 minutes in labtest mode, a copy of the student files are stored in the ltsave cache.  In addition, every time a student logs out, or a machine is rebooted, a sync is also performed.   Please note that if a machine seems totally hung, you can try the key sequence CTRL-ALT-BACKSPACE.  This kills the X session which will immediately sync the students files to the ltsave cache as well.  If you see the login screen again, you will know that the students files have been synced.  On the other hand, if the machine is REALLY hung, and won't respond to any input, then the only way to sync the student files to the cache is to turn the machine off and back on.  Once the machine boots up, the students files will be synced.  

Students should always be made aware that they should be saving their files on a regular basis.  If a machine crashes, and the student has not saved their files, obviously they won't be able to get them back.

Finally, keep in mind that if your labtest is using your own custom scripts that verify which machine a student is logging in to, and and will not allow a student to submit from more than one location, you may need to make manual adjustments to make this work.

If you have any questions, please feel free to e-mail tech.

====== Extending a Labtest ======

You can extend the time on a labtest for up to 2 hours using the pcmode webapp.  

Login to the pcmode webapp here:

https://webapp.eecs.yorku.ca/pcmode

Presently, only faculty, grads, and tech staff can login.  

Once you login, you will see a list of active jobs in the "Active Bookings" section that you are able to control.  If there is more than one active booking, you will be able to select which booking you wish to control.

In the second part of the screen, you will see some basic booking details (date and time for the booking, mode, and hosts).  This table is not meant to contain all the details of the booking.  It is meant to list the basics to help to distinguish one booking from another.

Finally, in the last part of the screen, you will see the "Booking End Time by Host" table.  This table will give you a list of all hosts that are part of this booking, and show you the current "End Time" for each host which will be either the real booking end time, or the extended time.  If a booking has been extended for, the "Extended By" column will show who extended the booking.  There will be one line in this table per host.

The screen looks like this:

{{:services:labtest:extend1.jpg|}}

===== Extending a Booking =====

1.  Hit the "View Schedule" button and view the pcmode schedule to ensure that your booking extension will not conflict with the next scheduled booking.

2.  Check off the hosts that you wish to extend in the "Booking End Time by Host" table.

3.  Select the duration of the extension from the "Extension" drop-down box.  You can extend the booking from anywhere between 5 minutes and 2 hours.

4.  Press the "Extend" button.  Your booking will be extended for the selected hosts.  The "Booking End Time by Host" table will show the new end time for the selected hosts.  It will also show who extended the time under the "Extended By" column.

**Please note:** When you extend a booking, you are always extending it from the original end booking time.  That is, if you extend your booking for 5 minutes two times in a row, you will only be extending the booking 5 minutes, and not 10 minutes.

If the end time comes for any part of your booking, the checkbox in the "Select" column will be replaced with the word "DONE", and you will no longer be able to control that part of the booking.

===== Canceling a Booking Extension =====

1.  Check off the hosts for which you wish to cancel the time extension.

2.  Press the "Cancel Extension" button.  The extended time on the selected hosts will be canceled.

====== Setting Up Deferred Exams ======

Deferred exams for a course are normally run in the following term.  For example if an exam is deferred from the winter term, the students will probably write the deferred exam at the start of the summer term.  By this time, /eecs/course has changed to point to the current term.  In the current term, the course directory may be owned by different faculty, or the course may not even be taught.  

When you book your deferred test, please provide to tech a session, term, and course.  When machines are placed into labtest mode, /eecs/course/COURSE will be pointing to your course directory from the previous session, and term, so submit will work perfectly fine.  Your course labtest web folder from the previous session and term will be mounted to /eecs/dept/wwww/labtest.
 
For example, assume that the current session in 2016-17 summer.  The course is 2031.  A deferred test is to be held for 2031 from the winter term.  Follow these steps:

1. Create a submit directory for your deferred exam: 

<code>
% cd /eecs/dept/course/2016-17/W/2031/submit <- you already have this directory from the previous session and term
% mkdir final <-- you can call your submit directory anything you like.
% chmod 770 final
% chgrp labtest final
</code>

2.  Configure your labtest questions:

<code>
% cd /eecs/dept/www/course_archive/2016-17/W/2031/labtest <- web folder from the previous term.

Modify index.html for your new test.

Instruct your student to submit like this:

<code>
submit 2031 final filename
              ^---- or whatever name you chose.
</code>

3.  E-mail tech to schedule your deferred exam.  Be sure to let them know that this is a deferred exam.  Provide them with the session, term, and course to ensure that the proper directories are mounted during your test.  

4.  Once tech has scheduled your deferred exam, consult the [[http://www.eecs.yorku.ca/schedule/pcmode|schedule]] and get your test ID.  Please arrange to test your test.  See the section entitled "Testing Your Labtest" for more details.

If you have any questions, please consult with tech.

====== Testing Your Labtest ======

Testing your labtest from a student account is extremely important.  It will help you uncover and correct any potential problems with your test including file and directory permissions, verification that all links are working, etc.  It will avoid having to deal with these problems on the day of your labtest, ensuring a much smoother labtest experience for both you and your students.

There are two ways to test your labtest:

  * Labtest Cloud 
  * Lab System

===== Labtest Cloud (LTCloud) =====

Labtest Cloud is the most ideal solution for testing your labtest at the university, or even remotely.  To access Labtest Cloud, you need to have:

  * An EECS account
  * A labtest Pcmode ID
  * Tech must have enabled your EECS account with Labtest Cloud access for the given labtest ID (this will happen automatically for Faculty).

Access the Labtest Cloud URL here:

  * https://webapp.eecs.yorku.ca/ltcloud

The best way to access ltcloud is directly from a web browser when you are connected to [[https://remotelab.eecs.yorku.ca|EECS Remotelab]].
If you want to access LTCloud directly from your home PC, you can use [[https://www.yorku.ca/uit/faculty-and-staff-services/internet-access/#vpn|York VPN]].

After connecting to the Labtest Cloud URL, you will be required to authenticate with your EECS username and password.  After you successfully authenticate, the system will take about 10 seconds to setup your Labtest Cloud instance.  Click on the "Connect to Labtest Cloud" button, and, right from your web browser, you'll be connected to a virtual system running labtest!  You will be logged in as "ltstu" (labtest student) which is a ugrad account.  Testing as a student is the best way to test your labtest.

If the Labtest Cloud web connection doesn't work for you, or if you prefer to use a local VNC client to access the Labtest Cloud, then please click the "Toggle Connection Details" button.  This will reveal the VNC connection details including hostname, port (always 5900), and password.  You can use these details to connect to the Labtest Cloud directly from your local computers VNC client.  If you are on a MAC, click on the vnc URL which should open the local VNC client.  If you're on a Windows PC, you can use the VNC client in [[https://mobaxterm.mobatek.net/|MobaXterm]] or [[https://www.realvnc.com/en/connect/download/viewer/|RealVNCs VNC Viewer]].

When you're done with your Labtest Cloud instance, please be sure to logout.  This ensures that your cloud instance will be free for someone else to use.  To logout, click the small arrow at the top right corner of the screen, click on "Labtest Student", then "Logout".  You can also double click the "Logout" icon on the desk.  Your Labtest Cloud session will be terminated after 30 minutes of inactivity, or when you log out of the system.  All files will be lost at that time.  Note that if you close the Labtest Cloud window without logging out, someone will have to wait for your session to timeout before the host is available for use again.

===== Lab System =====

The next best way to test your labtest is on a lab system.  Consult with tech, and we will place a lab system into labtest mode for your test at a specific scheduled date and time.  Unless you are connecting hardware directly up to the lab machine, it's always preferable for you to use Labtest Cloud instead.

====== Labtest under Windows ======

Labtest is available for limited use under Windows, but requires consultation with tech.  Machines will boot first into Linux labtest mode, and then Windows will run in a [[http://www.virtualbox.org/|VirtualBox]] session.  Students login to what appears to be a Linux system, but after logging in, the VirtualBox session is immediately started, and Windows boots taking over the full screen.  With labtest running underneath, we get these benefits:

  * A web browser is started and will display the labtest start page, much like under Linux.
  * All firewall limitations on what can/cannot be done automatically restrict the Windows configuration without additional changes.
  * Students have access to their standard labtest home directory including any special additions for labtest mode (eg. "unsubmit").
  * Student files will continue to be synced to our server every 15 minutes.

A few present limitations:

  * We do not have a specific mechanism for students to "submit" their work from Windows.  However, since all student data is copied to /eecs/ltsave anyway, it can be extracted from there. 
  * The software base for Windows labtest is very limited right now.  Software includes Java, Eclipse, Firefox, and some other limited applications.  If you need a particular application under Labtest for Windows, please consult with tech.
  * VirtualBox image files are distributed to each of the local machines, but the files are quite large.  Since we do not create a large image PER student, the Windows image is "immutable".  That is, when the student logs out, their changes to the local system are lost.  Changes to their "home" directory remain.
  * This functionality is not available in WSC labtest.