#lang scribble/doc @(require "common.rkt") @title[#:tag "server-setup"]{Server Setup} @declare-exporting[#:use-sources (handin-server/scribblings/hook-dummy)] 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 @envvar{PLT_HANDINSERVER_DIR} environment variable. This directory contains the following files and sub-directories: @itemize[ @item{@filepath{server-cert.pem}: the server's certificate. To create a certificate and key with openssl: @commandline{openssl req -new -nodes -x509 -days 365 -out server-cert.pem -keyout private-key.pem}} @item{@filepath{private-key.pem}: the private key to go with @filepath{server-cert.pem}. Whereas @filepath{server-cert.pem} gets distributed to students with the handin client, @filepath{private-key.pem} is kept private.} @item{@filepath{config.rktd}: configuration options. The file format is @verbatim[#:indent 2]{(( ) ...)} The following keys can be used: @itemize[ @item{@indexed-racket[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 @racketid[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.} @item{@indexed-racket[inactive-dirs] --- a list of inactive submission directories (see above for details).} @item{@indexed-racket[port-number] --- the port for the main handin server; the default is 7979.} @item{@indexed-racket[use-https] --- determines whether to start an embedded web server for handin status reports; the default is @racket[#t].} @item{@indexed-racket[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.} @item{@indexed-racket[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.} @item{@indexed-racket[allow-web-upload] --- either @racket[#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 @racket[#f]. The suffix strings should include a @litchar{.}, as in @racket[".rkt"].} @item{@indexed-racket[default-file-name] --- the default filename that will be saved with the submission contents. The default is @filepath{handin.rkt}.} @item{@indexed-racket[max-upload] --- maximum size in bytes of an acceptable submission; the default is 500000.} @item{@indexed-racket[max-upload-keep] --- maximum index of submissions to keep; the most recent submission is @filepath{handin.rkt} (by default), the next oldest is in @filepath{BACKUP-0/handin.rkt}, next oldest is @filepath{BACKUP-1/handin.rkt}, etc. The default is 9.} @item{@indexed-racket[user-regexp] --- a regular expression that is used to validate usernames; alternatively, this can be @racket[#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--- @racket[#rx"^[a-z][a-z0-9]+$"]; a @litchar{+} is always disallowed in a username, since it is used in a submission username to specify joint work.} @item{@indexed-racket[user-desc] --- a plain-words description of the acceptable username format (according to user-regexp above); @racket[#f] stands for no description; the default is @racket["alphanumeric string"] which matches the default user-regexp.} @item{@indexed-racket[username-case-sensitive] --- a boolean; when @racket[#f], usernames are case-folded for all purposes; defaults to @racket[#f] (note that you should not set this to @racket[#t] on Windows or when using other case-insensitive filesystems, since usernames are used as directory names).} @item{@indexed-racket[allow-new-users] --- a boolean indicating whether to allow new-user requests from a client tool; the default is @racket[#f].} @item{@indexed-racket[allow-change-info] --- a boolean indicating whether to allow changing user information from a client tool (changing passwords is always possible); the default is @racket[#f].} @item{@indexed-racket[master-password] --- a string for an MD5 hash for a password that allows login as any user; the default is @racket[#f], which disables the password.} @item{@indexed-racket[log-output] --- a boolean that controls whether the handin server log is written on the standard output; defaults to @racket[#t].} @item{@indexed-racket[log-file] --- a path (relative to handin server directory or absolute) that specifies a filename for the handin server log (possibly combined with the @racketid[log-output] option), or @racket[#f] for no log file; defaults to @filepath{log}.} @item{@indexed-racket[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 @racket[#f] (the default) to disable this log.} @item{@indexed-racket[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 @racket[#f], or a list of permitted string values), and a string describing acceptable strings. The default is @verbatim[#:indent 2]|{ (("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: @verbatim[#:indent 2]|{ (("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 @filepath{users.rktd} file (see below). @; JBC: a hyperlink here for users.rktd? The second item in a field description can also be the symbol @racketid[-], 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 @filepath{users.rktd} file and fill in such information. (The third element for such descriptors is ignored.)} @item{@indexed-racket[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 @racket[hook] function, which should be receiving three arguments: @defproc[(hook [operation symbol?] [connection-context (or/c number? symbol? false?)] [relevant-info (listof (list/c symbol? any))]) void?]{ The @racket[operation] argument indicates the operation that is now taking place. It can be one of the following: @indexed-racket['server-start], @indexed-racket['server-connect], @indexed-racket['user-create], @indexed-racket['user-change], @indexed-racket['login], @indexed-racket['submission-received], @indexed-racket['submission-committed], @indexed-racket['submission-retrieved], @indexed-racket['status-login], or @indexed-racket['status-file-get]. The @racket[connection-context] argument is a datum that specifies the connection context (a number for handin connections, a @racketid[wN] symbol for servlet connections, and @racket[#f] for other server operations). The @racket[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: @racketmod[ 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))))]}}] In addition, you can add your own keys --- see @racket[get-conf] for details. Changes to @filepath{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 @racketid[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.} @item{@filepath{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 @racketid[extra-fields] configuration entry (in the same order). The file format is @verbatim[#:indent 2]{ (( ( ...)) ...)} For example, the default @racketid[extra-field] setting will make this: @verbatim[#:indent 2]{ (( ( )) ...)} Usernames that begin with ``solution'' are special. They are used by the HTTPS status server. Independent of the @racketid[user-regexp] and @racketid[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 @racketid[allow-new-users] configuration allows new users, the @filepath{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 @filepath{/etc/passwd} or @filepath{/etc/shadow}), then you can construct a @filepath{users.rktd} file that will allow users to use their normal passwords. To achieve this, use a list with @racketid[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 @filepath{users.rktd}, but make sure you have information that matches your @racketid[extra-fields] specification. For example, given this system file: @verbatim[#:indent 2]|{ 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 @filepath{users.rktd} file: @verbatim[#:indent 2]|{ ((foo ((unix "wRzN1u5q2SqRD") "L.E. Foo" "?")) (bar ((unix "$1$dKlU0OkJ$t63TzKz") "Bar Z. Lie" "?")))}| which can be combined with this setting for @racketid[extra-fields] in your @filepath{config.rktd}: @verbatim[#:indent 2]{ ... (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 @onscreen{Manage ...} dialog to properly set their TA name. Finally, a password value can be a list that begins with a @racketid[plaintext] symbol, which will be used without encryption. This may be useful for manually resetting a forgotten passwords.} @item{@filepath{log} (or any other name that the @racketid[log-file] configuration option specifies (if any), created if not present, appended otherwise): records connections and actions, where each entry is of the form @verbatim{[|