"private-key.pem": the private key to go with "server-cert.pem". Whereas "server-cert.pem" gets distributed to students with the handin client, "private-key.pem" is kept private.

The following keys can be used:

• active-dirs — a list of directories that are active submissions, relative to the current directory or absolute; the last path element for each of these (and inactive-dirs below) should be unique, and is used to identify the submission (for example, in the client’s submission dialog and in the status servlet). If a specified directory does not exist, it will be created.

• inactive-dirs — a list of inactive submission directories (see above for details).

• port-number — the port for the main handin server; the default is 7979.

• use-https — determines whether to start an embedded web server for handin status reports; the default is #t.

• session-timeout — number of seconds before the session times-out. The client is given this many seconds for the login stage and then starts again so the same number of seconds is given for the submit-validation process; the default is 300.

• session-memory-limit — maximum size in bytes of memory allowed for per-session computation, if per-session limits are supported (i.e., when using GRacket and Racket with the (default) exact garbage collector and memory accounting); the default is 40000000.

• allow-web-upload — either #f (to disable upload via the HTTPS status server) or a non-empty list of suffix strings (to enable uploads for active assignments and force the uploaded file to have one of the suffixes); the default is #f. The suffix strings should include a ., as in ".rkt".

• default-file-name — the default filename that will be saved with the submission contents. The default is "handin.rkt".

• max-upload — maximum size in bytes of an acceptable submission; the default is 500000.

• max-upload-keep — maximum index of submissions to keep; the most recent submission is "handin.rkt" (by default), the next oldest is in "BACKUP-0/handin.rkt", next oldest is "BACKUP-1/handin.rkt", etc. The default is 9.

• user-regexp — a regular expression that is used to validate usernames; alternatively, this can be #f meaning no restriction, or a list of permitted strings. Young students often choose exotic usernames that are impossible to remember, and forget capitalization, so the default is fairly strict— #rx"^[a-z][a-z0-9]+$"; a + is always disallowed in a username, since it is used in a submission username to specify joint work.

• user-desc — a plain-words description of the acceptable username format (according to user-regexp above); #f stands for no description; the default is "alphanumeric string" which matches the default user-regexp.

• username-case-sensitive — a boolean; when #f, usernames are case-folded for all purposes; defaults to #f (note that you should not set this to #t on Windows or when using other case-insensitive filesystems, since usernames are used as directory names).

• allow-new-users — a boolean indicating whether to allow new-user requests from a client tool; the default is #f.

• allow-change-info — a boolean indicating whether to allow changing user information from a client tool (changing passwords is always possible); the default is #f.

• master-password — a string for an MD5 hash for a password that allows login as any user; the default is #f, which disables the password.

• log-output — a boolean that controls whether the handin server log is written on the standard output; defaults to #t.

• log-file — a path (relative to handin server directory or absolute) that specifies a filename for the handin server log (possibly combined with the log-output option), or #f for no log file; defaults to "log".

• web-log-file — a path (relative to handin server directory or absolute) that specifies a filename for logging the internal HTTPS status web server; or #f (the default) to disable this log.

• extra-fields — a list that describes extra string fields of information for student records; each element in this list is a list of three values: the name of the field, the regexp (or #f, or a list of permitted string values), and a string describing acceptable strings. The default is

  (("Full Name" #f #f)

  ("ID#" #f #f)

  ("Email" #rx"^[^@<>\"`',]+@[a-zA-Z0-9_.-]+[.][a-zA-Z]+$"

  "a valid email address"))

  You can set this to a list of fields that you are interested in keeping, for example:

  (("Full Name"

  #rx"^[A-Z][a-zA-Z-]+(?: [A-Z][a-zA-Z-]+)+$"

  "full name, no punctuation, properly capitalized")

  ("Utah ID Number"

  #rx"^[0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]$"

  "Utah ID Number with exactly nine digits")

  ("Email"

  #rx"^[^@<>\"`',]+@cs\\.utah\\.edu$"

  "A Utah CS email address"))

  The order of these fields will be used both on the client GUI side and in the "users.rktd" file (see below).

  The second item in a field description can also be the symbol -, which marks this field as one that is hidden from the user interface: students will not see it and will not be able to provide or modify it; when a new student creates an account, such fields will be left empty. This is useful for adding information that you have on students from another source, for example, adding information from a course roster. You should manually edit the "users.rktd" file and fill in such information. (The third element for such descriptors is ignored.)

• hook-file — a path (relative to handin server directory or absolute) that specifies a filename that contains a ‘hook’ module. This is useful as a general device for customizing the server through Racket code. The file is expected to contain a module that provides a hook function, which should be receiving three arguments:

  procedure (hook   operation             connection-context             relevant-info)   →   void?

  operation : symbol?

  connection-context : (or/c number? symbol? false?)

  relevant-info : (listof (list/c symbol? any))

  The operation argument indicates the operation that is now taking place. It can be one of the following: 'server-start, 'server-connect, 'user-create, 'user-change, 'login, 'submission-received, 'submission-committed, 'submission-retrieved, 'status-login, or 'status-file-get.

  The connection-context argument is a datum that specifies the connection context (a number for handin connections, a wN symbol for servlet connections, and #f for other server operations).

  The relevant-info contains an alist of information relevant to this operation. Currently, the hook is used in several places after an operation has completed.

  For example, here is a simple hook module that sends notification messages when users are created or their information has changed:

  #lang racket/base

  (provide hook)

  (require net/sendmail)

  (define (hook what session alist)

  (when (memq what '(user-create user-change))

  (send-mail-message

  "course-staff@university.edu"

  (format "[server] ~a (~a)" what session)

  '("course-staff@university.edu") '() '()

  (map (lambda (key+val)

  (apply format "~a: ~s" key+val))

  alist))))

The Grading Utilities uses the following keys:

• deadline: sets a per-assignment deadline for submissions, while optionally allowing a number of days for late submissions.

• max-submissions sets a per-assignment limit to the quantity of submissions that users can send.

• report-delay-in-minutes: specifies the delay after which the report of the submission is written to the user folder of the corresponding assignment.

In addition, you can add your own keys — see get-conf for details.

Changes to "config.rktd" are detected, the file will be re-read, and options will be reloaded. A few options are fixed at startup time: port numbers and log file specs are fixed as configured at startup. All other options will change the behavior of the running server (but for things like username-case-sensitive? it would be unwise to do so). (For safety, options are not reloaded until the file parses correctly, but make sure that you don’t save a copy that has inconsistent options: it is best to create a new configuration file and move it over the old one, or use an editor that does so and avoid saving until the new contents is ready.) This is most useful for closing & opening submissions directories.

Usernames that begin with “solution” are special. They are used by the HTTPS status server. Independent of the user-regexp and username-case-sensitive? configuration items, usernames are not allowed to contain characters that are illegal in Windows pathnames, and they cannot end or begin in spaces or periods.

If the allow-new-users configuration allows new users, the "users.rktd" file can be updated by the server with new users. It can always be updated by the server to change passwords.

If you have access to a standard Unix password file (from "/etc/passwd" or "/etc/shadow"), then you can construct a "users.rktd" file that will allow users to use their normal passwords. To achieve this, use a list with unix as the first element and the system’s encrypted password string as the second element. Such passwords can be used, but when users change them, a plain md5 hash will be used.

Finally, a password value can be a list that begins with a plaintext symbol, which will be used without encryption. This may be useful for manually resetting a forgotten passwords.

Active and inactive assignment directories (which you can put in a nested directory for convenience, or specify a different absolute directory), as specified by the configuration file using the active-dirs and inactive-dirs. A list of active assignment directories (the last path element in each specified path is used as a label) is sent to the client tool when a student clicks Handin. The assignment labels are ordered in the student’s menu using string<?, and the first assignment is the default selection.

Within each assignment directory, the student id is used for a sub-directory name. Within each student sub-directory are directories for handin attempts and successes. If a directory "ATTEMPT" exists, it contains the most recent (unsuccessful or currently-in-submission) handin attempt. Directories "SUCCESS-n" (where n counts from 0) contain successful handins; the lowest numbered such directory represents the latest handin.

A cleanup process in the server copies successful submissions to the student directory, one level up from the corresponding "SUCCESS-n" directory. This is done only for files and directories that are newer in "SUCCESS-n" than in the submission root, other files and directories are left intact. If external tools add new content to the student directory (e.g., a "grade" file, as described below) it will stay there. If the machine crashes or the server is stopped, the cleanup process might not finish. When the server is started, it automatically runs the cleanup process for each student directory.

Within a student directory, a "handin.rkt" file (or some other name if the default-file-name option is set) contains the actual submission. A checker procedure can change this default file name, and it can create additional files in an "ATTEMPT" directory (to be copied by the cleanup process); see below for more details on handin-server/checker.

For submissions from a normal DrRacket frame, a submission file contains a copy of the student’s definitions and interactions windows. The file is in a binary format (to support non-text code), and opening the file directly in DrRacket shows the definitions part. To get both the definitions and interactions parts, the file can be parsed with unpack-submission from handin-server/utils.

To submit an assignment as a group, students use a concatenation of usernames separated by “+” and any number of spaces (e.g., “user1+user2”). The same syntax (“user1+user2”) is used for the directory for shared submissions, where the usernames are always sorted so that directory names are deterministic. Multiple submissions for a particular user in different groups will be rejected.

Inactive assignment directories are used by the HTTPS status web server.

"<active-assignment>/checker.rkt" (optional): a module that exports a checker function. This function receives two arguments: a username list and a submission as a byte string. (See also unpack-submission, etc. from handin-server/utils.) To reject the submission, the checker function can raise an exception; the exception message will be relayed back to the student. The module is loaded when the current directory is the main server directory, so it can read files from there (but note that to read values from "config.rktd" it is better to use get-conf). Also, the module will be reloaded if the checker file is modified; there’s no need to restart the server, but make sure that you do not save a broken checker (i.e., do not save in mid-edit).

The first argument is a list of usernames with at least one username, and more than one if this is a joint submission (where the submission username was a concatenation of usernames separated by “+”).

The checker function is called with the current directory as "<active-assignment>/<username(s)>/ATTEMPT", and the submission is saved in the file "handin", and the timeout clock is reset to the value of the session-timeout configuration. The checker function can change "handin", and it can create additional files in this directory. (Extra files in the current directory will be preserved as it is later renamed to "SUCCESS-0", and copied to the submission’s root ("<active-assignment>/<username(s)>/"), etc.) To hide generated files from the HTTPS status web server interface, put the files in a subdirectory, it is preserved but hidden from the status interface.

The checker should return a string, such as "handin.rkt", to use in naming the submission file, or #f to indicate that he file should be deleted (e.g., when the checker alrady created the submission file(s) in a different place).

To specify only pre/post-checker, use #f for the one you want to omit.

"<[in]active-assignment>/<user(s)>/<filename>" (if submitted): the most recent submission for <[in]active-assignment> by <user(s)> where <filename> was returned by the checker (or the value of the default-file-name configuration option if there’s no checker). If the submission is from multiple users, then “<user(s)>” is actually “<user1>+<user2>” etc. Also, if the cleanup process was interrupted (by a machine failure, etc.), the submission may actually be in "SUCCESS-n" as described above, but will move up when the server performs a cleanup (or when restarted).

"<[in]active-assignment>/<user(s)>/grade" (optional): the <user(s)>’s grade for <[in]active-assignment>, to be reported by the HTTPS status web server

"<[in]active-assignment>/solution*": the solution to the assignment, made available by the status server to any user who logs in. The solution can be either a file or a directory with a name that begins with "solution". In the first case, the status web server will have a “Solution” link to the file, and in the second case, all files in the "solution*" directory will be listed and accessible.