On this page:

5 Server Setup

You must prepare a special directory to host the handin server. To run the server, you should either be in this directory, or you should set the PLT_HANDINSERVER_DIR environment variable.

This directory contains the following files and sub-directories:
  • "server-cert.pem": the server’s certificate. To create a certificate and key with openssl:
      openssl req -new -nodes -x509 -days 365 -out server-cert.pem -keyout private-key.pem

  • "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.

  • "config.rktd": configuration options. The file format is

      ((<key> <val>) ...)

    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"


          "Utah ID Number with exactly nine digits")



          "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:


      (hook operation    
        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))
           (format "[server] ~a (~a)" what session)
           '("course-staff@university.edu") '() '()
           (map (lambda (key+val)
                  (apply format "~a: ~s" key+val))

    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.

  • "users.rktd" (created if not present when a user is added): keeps the list of user accounts, along with the associated password (actually the MD5 hash of the password), and extra string fields as specified by the extra-fields configuration entry (in the same order). The file format is

      ((<username-sym> (<pw-md5-str> <extra-field> ...))


    For example, the default extra-field setting will make this:

      ((<username-sym> (<pw-md5-str> <full-name> <id> <email>))


    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.

    You can combine this with other fields from the password file to create your "users.rktd", but make sure you have information that matches your extra-fields specification. For example, given this system file:

      foo:wRzN1u5q2SqRD:1203:1203:L.E. Foo        :/home/foo:/bin/tcsh

      bar:$1$dKlU0OkJ$t63TzKz:1205:1205:Bar Z. Lie:/home/bar:/bin/bash

    you can create this "users.rktd" file:

      ((foo ((unix "wRzN1u5q2SqRD") "L.E. Foo" "?"))

       (bar ((unix "$1$dKlU0OkJ$t63TzKz") "Bar Z. Lie" "?")))

    which can be combined with this setting for extra-fields in your "config.rktd":


      (extra-fields (("Full Name" #f #f)

                     ("TA" ("Alice" "Bob") "Your TA")))


    and you can tell your students to use their department username and password, and use the Manage ... dialog to properly set their TA name.

    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.

  • "log" (or any other name that the log-file configuration option specifies (if any), created if not present, appended otherwise): records connections and actions, where each entry is of the form

    [<id>|<time>] <msg>

    where <id> is an integer representing the connection (numbered consecutively from 1 when the server starts), “-” for a message without a connection, and “wN” for a message from the status servlet.

  • 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 the file should be deleted (e.g., when the checker already created the submission file(s) in a different place).

    Alternatively, the module can bind checker to a list of three procedures: a pre-checker, a checker, and a post-checker. All three are applied in exactly the same way as the checker (same arguments, and always within the submission directory), except that:
    • If there was an error during the pre-checker, and the submission directory does not have a "SUCCESS-*" directory, then the whole submission directory is removed. This is useful for checking that the user/s are valid; if you allow a submission only when users is '("foo" "bar"), and “foo” tries to submit alone, then the submission directory for “foo” should be removed to allow a proper submission later. Note that the timeout clock is reset only once, before the pre-checker is used.

    • The post-checker is used at the end of the process, after the "ATTEMPT" directory was renamed to "SUCCESS-0". At this stage, the submission is considered successful, so this function should avoid throwing an exception (it can, but the submission will still be in place). This is useful for things like notifying the user of the successful submission (see message), or sending a “receipt” email.

    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.

Remember that if you’re not using the (default) 3m variant of Racket, you don’t get memory accounting.

The server currently provides no mechanism for a graceful shutdown, but terminating the server is no worse than a network outage. (In particular, no data should be lost.) The server reloads the configuration file, checker modules etc, so there should not be any need to restart it for reconfigurations.

The client and server are designed to be robust against network problems and timeouts. The client-side tool always provides a cancel button for any network transaction. For handins, cancel is guaranteed to work up to the point that the client sends a “commit” command; this command is sent only after the server is ready to record the submission (having run it through the checker, if any), but before renaming "ATTEMPT". Also, the server responds to a commit with ok only after it has written the file. Thus, when the client-side tool reports that the handin was successful, the report is reliable. Meanwhile, the tool can also report successful cancels most of the time. In the (normally brief) time between a commit and an ok response, the tool gives the student a suitable warning that the cancel is unreliable.

To minimize human error, the number of active assignments should be limited to one whenever possible. When multiple assignments are active, design a checker to help ensure that the student has selected the correct assignment in the handin dialog.

A student can download his/her own submissions through the handin dialog. This can also be done through a web server that runs concurrently with the handin server (on the same port) if you set the use-https option in the configuration file to #t (the default). The starting URL is


to obtain a list of all assignments, or


to start with a specific assignment (named ASSIGNMENT).