RunScript - the "Check All Submitted Files" facility

The RunScript facility works with the CS TigerFile system to provide assignment submission pages with an optional "Check All Submitted Files" button. When a student clicks on this button, CS TigerFile sends the submitted files to a separate server where an instructor-provided script is invoked. The output of the instructor-provided script (stdout and stderr) is transmitted back to the CS TigerFile web server where it is then presented to the student.

If you wish to use this optional facility for your course, please contact CS Staff. We will create a ~courseuser/RunScript directory structure. In this directory will be a README file with information on how to write your scripts.

In a nutshell, instructors create symbolic links in the ~/RunScript/Links directory that point to executable scripts elsewhere (typically in the ~/RunScript/Scripts directory). The name of these symbolic links must match the assignment name portion of the assignment URL (spaces in the assignment name will be replaced by underscores in the script name). For example, an assignment named "Hello World" would use the link named Hello_World. Scripts are run as the course user (e.g., cos126) with a working directory of ~/RunScript. The "Hello World" script would be invoked for a user with NetID "joeuser" as:

    ./Links/Hello_World Temp/joeuser

Note that the script should expect a single argument which will be the name of the temporary directory containing the students submitted files. It is the responsibility of the script to "cd" to this directory if needed. Also note that this temporary directory is removed by the server after the script finishes. Note also that students can "Check All Submitted Files" even if they have not submitted all the files necessary to complete the assignment. Your script should not fail if Temp/joeuser contains no files.

There are several timeouts in play that will have an impact on the time that course-provided scripts can run. Ultimately, this is due to the design constraint that no output is sent back to the student's browser until the script finishes. Each browser may have a different timeout while waiting for input, but we assume that end-user browser timeouts are greater than 185 seconds. Each previous stage has a slightly shorter timeout.

The php max_execution_time is 180 seconds. The is the maximum time the CS TigerFile server will run a PHP script.

The CURLOPT_TIMEOUT is 170 seconds. This is the maximum time the curl command inside the CS TigerFile PHP code will wait for a response from the RunScript server.

The RunScript server will terminate a course-provided script after 155 seconds. The server will then have a few seconds to package up the output generated at the point the script was terminated and send it back to the curl process on the CS TigerFile side.
Another timeout to note is that the javascript on the CS TigerFile side will throw a requester back to the user every 40 seconds indicating that there has been no response and give the user an opportunity to cancel the script (and get no output).

In addition to the time resource limit, there is a limit to the amount of output a script can generate. By default, the limit is 64K bytes. If a script generates more than this, it will be terminated and the output generated thus far will be sent back to the user.

If a script is terminated for taking too long or for generating too much output, the response back to the user will include an appropriate diagnostic message indicating this.

Log File Location and Format

RunScripts are actually run on hosts with names of the form fileboxN.  The corresponding log files for a given course are located in ~/RunScript with names of the form logfile_fileboxN. Individual "clicks" by students are load-balanced across the fileboxN servers using round-robin DNS responses.  Once a given script for a student is complete, an entry is appended to the log file for the server that ran the script.  Here is an example entry: - - [20/Mar/2018 13:05:41] filebox1 HTTPStatus.OK Hamming joeuser files=3 returncode=0 timing(secs): script=5.5223 response=6.5723 utime=9.2924 stime=0.9121 Load: 0.36 0.15 0.08 1/244

The components of the entry are as follows:

  • The IP address is where the request came from (generally this is the IP address of the web server running CS TigerFile)
  • The time stamp for when the script finished
  • The hostname for the server that ran the script
  • The HTTP status from the RunScript daemon
  • The name of the assignment
  • The NetId of the student
  • The number of files sent from CS TigerFile to the RunScript server
  • The Unix return code of the course-supplied script
  • The wall-clock time to execute the script
  • The wall clock-time to generate a response (including the time to execute the script)
  • The user CPU time of the script (utime)
  • The system CPU time of the script (stime)
  • The remaining entires are taken from /proc/loadavg (but without the PID).  See man proc for full details.
    • The system load averages for the past 1, 5, and 15 minutes.  See man uptime for a description of load averages.  Note that they are not normalized to the number of CPUs in the server.
    • The last entry is of the form N/M.  The number before the slash is the number of currently runnable kernel scheduling entities (processes, threads).  The value after the slash is the number of kernel scheduling entities that currently exist on the system.