Backend exam server.

VirtualExam (vx)
Operation

1. For full details on the files and scripts mentioned here, please consult files and locations.
2. As a general rule, a gaol does not come into existence until a student successfully logs in with their zID and zPass.
   • Under normal circumstances, the gaol is destroyed automatically when the student session ends, regardless of whether it ends due to an error — such as network failure — or when the student finishes the exam.
   • The student is provided with a home directory (actually located outside of the gaol in the class exam account home directory) which is persistent.
   • This persistent home directory allows an exam to be resumed by a student, and provides storage for the exam product of the student.
3. The normal startup sequence:
   1. The invigilator logs in to the student-exam computer using an unprivileged or kiosk account,
   2. The local X server is started either by the invigilator or automatically and connects to the class exam account on the backend exam server using plink or ssh,
   3. The .ssh/rc script in the class exam account's home directory is run automatically by sshd as the connection is established. This saves the session's unique X11 $DISPLAY and X11 cookie in /home/<class-exam-account>/var/<hostname>-<sessionid>/x. hostname is the name of the backed exam server to which the connection is established. sessionid is the unique login session ID (from /bin/ps --no-heading -o sid --pid $$)
   4. /home/vx/bin/vxstart is started as the class exam account user. This creates a unique and unshared .Xauthority file for this user for this session. It then runs the vxuserlogin script in an xterm to get the user's zID and authenticate them.

   5. /home/vx/bin/vxuserlogin prompts the user for their zID and zPass. kinit is used in the script to authenticate them, and getent is used to check that they have a CSE account. Their zID and UID are written into appropriately-named files in /home/<class-exam-account>/var/<hostname>-<sessionid>.

      For testing purposes, if a file called ~/currentexam/etc/autologin exists in the class exam account, vxuserlogin will not prompt, and a fake, but usable, zID and UID will be created instead.

   6. vxstart then runs priv startexam which directly executes /home/virtualexam/bin/priv.startexem which then runs /home/virtualexam/bin/vxgaolsetup.
   7. vxgaolsetup reads vx.conf in /home/virtualexam/etc and in /home/<class-exam-account>/currentexam/etc (if it exists), and all the files (dereferencing symbolic links) in the directory /home/<class-exam-account>/currentexam/etc/vx.conf.d (if it and they exist) and uses their content to construct the non-user parts of the gaol environment. This includes the directory structure from / down, /lib, /lib64, /usr/lib, /usr/share, /dev, /proc, etc. and also includes importing a limited set of binaries such as /bin/sh, /bin/less, /bin/ps, etc. It does not create /etc/passwd or /etc/group or the home directory which the student will use. These are done later (see below).
   8. Next, vxgaolsetup launches /home/virtualexam/bin/vxgaolsetup-userhome. This is the script which sets up /etc/passwd, /etc/group and the home directory which the student will use in the goal. It then starts the gaol, which basically says "go" to the student. In a little more detail vxgaolsetup-userhome does the following:
      1. Allocates a unique UID and GID for the student in the exam environment/gaol. This is the student's real UID plus 900000,
      2. Creates a /etc/passwd and /etc/group in the gaol with these values,
      3. Copies /home/virtualexam/etc/startup and startup-session into /etc in the gaol,
      4. Copies /home/<class-exam-account>/currentexam/etc/startup, if it exists, as /etc/startup.class in the gaol,
      5. Bind mounts /home/<class-exam-account>/currentexam/class at /home/class in the exam environment. It then creates a home directory for the student with their zID in /home/<class-exam-account>/currentexam/work and bind mounts this with the same name at /home in the gaol,
      6. Copies the .Xauthority file created earlier into the home directory.
      7. Creates/sets $DISPLAY, and
      8. Then uses the chroot command to bring the gaol to life and begin executing /etc/startup. When /etc/startup later exits the gaol (chroot) terminates.
   9. /etc/startup does things various, then runs /etc/startup-session, which then runs the class-specific /etc/startup-class (which should do exam-specific setup and then start the student's X11 window manager and let the student get going.
   10. The student writes their results into their home directory (which actually leaves them in the class exam account).
   11. The student's window manager exits, startup/startup-session/startup.class exit, chroot exits, vxgaolsetup-userhome exits, and vxgaolsetup deletes the gaol.