From 8a4aeb32ee6e5f294be509c97175762a1b4ec2c4 Mon Sep 17 00:00:00 2001 From: Eli Barzilay Date: Thu, 1 Oct 2009 07:43:23 +0000 Subject: [PATCH] lots of improvements svn: r16196 --- .../scribblings/server-setup.scrbl | 189 +++++++++--------- 1 file changed, 94 insertions(+), 95 deletions(-) diff --git a/collects/handin-server/scribblings/server-setup.scrbl b/collects/handin-server/scribblings/server-setup.scrbl index fa56083314..db4baa314a 100644 --- a/collects/handin-server/scribblings/server-setup.scrbl +++ b/collects/handin-server/scribblings/server-setup.scrbl @@ -5,14 +5,14 @@ @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. +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: +@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}} @@ -22,7 +22,7 @@ This directory contains the following files and sub-directories: @filepath{private-key.pem} is kept private.} @item{@filepath{config.ss}: configuration options. The file format is - @schemeblock[(( ) ...)] + @verbatim[#:indent 2]{(( ) ...)} The following keys can be used: @@ -30,7 +30,7 @@ This directory contains the following files and sub-directories: @item{@indexed-scheme[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 - @scheme[inactive-dirs] below) should be unique, and is used to + @schemeid[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.} @@ -75,9 +75,9 @@ This directory contains the following files and sub-directories: 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--- @scheme[#rx"^[a-z][a-z0-9]+$"]; a @scheme["+"] is always - disallowed in a username, since it is used in a submission - username to specify joint work.} + strict--- @scheme[#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-scheme[user-desc] --- a plain-words description of the acceptable username format (according to user-regexp above); @@ -110,7 +110,7 @@ This directory contains the following files and sub-directories: @item{@indexed-scheme[log-file] --- a path (relative to handin server directory or absolute) that specifies a filename for the - handin server log (possibly combined with the @scheme[log-output] + handin server log (possibly combined with the @schemeid[log-output] option), or @scheme[#f] for no log file; defaults to @filepath{log}.} @@ -124,30 +124,31 @@ This directory contains the following files and sub-directories: this list is a list of three values: the name of the field, the regexp (or @scheme[#f], or a list of permitted string values), and a string describing acceptable strings. The default is - @schemeblock[ - '(("Full Name" #f #f) - ("ID#" #f #f) - ("Email" #rx"^[^@<>\"`',]+@[a-zA-Z0-9_.-]+[.][a-zA-Z]+$" - "a valid email address"))] + @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: - @schemeblock[ - '(("Full Name" - #rx"^[A-Z][a-zA-Z]+(?: [A-Z][a-zA-Z]+)+$" - "full name, no punctuations, 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"))] + @verbatim[#:indent 2]|{ + (("Full Name" + #rx"^[A-Z][a-zA-Z]+(?: [A-Z][a-zA-Z]+)+$" + "full name, no punctuations, 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.ss} file (see below). @; JBC: a hyperlink here for users.ss? The second item in a field description can also be the symbol - @scheme['-], which marks this field as one that is hidden from the + @schemeid[-], 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 @@ -170,20 +171,19 @@ This directory contains the following files and sub-directories: The @scheme[operation] argument indicates the operation that is now taking place. It can be one of the following: - @indexed-scheme['server-start], - @indexed-scheme['server-connect], @indexed-scheme['user-create], - @indexed-scheme['user-change], @indexed-scheme['login], - @indexed-scheme['submission-received], + @indexed-scheme['server-start], @indexed-scheme['server-connect], + @indexed-scheme['user-create], @indexed-scheme['user-change], + @indexed-scheme['login], @indexed-scheme['submission-received], @indexed-scheme['submission-committed], @indexed-scheme['submission-retrieved], @indexed-scheme['status-login], or @indexed-scheme['status-file-get]. - The @scheme[connection-context] argument is a datum that - specifies the connection context (a number for handin - connections, a @scheme['wN] symbol for servlet connections, and - @scheme[#f] for other server operations). - + The @scheme[connection-context] argument is a datum that specifies + the connection context (a number for handin connections, a + @schemeid[wN] symbol for servlet connections, and @scheme[#f] for + other server operations). + The @scheme[relevant-info] contains an alist of information relevant to this operation. Currently, the hook is used in several places after an operation has completed. @@ -207,96 +207,95 @@ This directory contains the following files and sub-directories: alist))))]}}] Changes to @filepath{config.ss} are detected, the file will be - re-read, and options are 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 things like - @scheme[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 not - save until the new contents is ready.) This is most useful for + re-read, and options are 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 things like @schemeid[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 + not save until the new contents is ready.) This is most useful for closing & opening submissions directories.} @item{@filepath{users.ss} (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 - @schemeblock[ + specified by the @schemeid[extra-fields] configuration entry (in the + same order). The file format is + @verbatim[#:indent 2]{ (( ( ...)) - ...)] + ...)} - For example, the default @scheme['extra-field] setting will make this: - @schemeblock[ + For example, the default @schemeid[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 - @scheme['user-regexp] and @scheme['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. + Usernames that begin with ``solution'' are special. They are used by + the HTTPS status server. Independent of the @schemeid[user-regexp] + and @schemeid[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 @scheme['allow-new-users] configuration allows new users, the - @filepath{users.ss} file can be updated by the server with new - users. It can always be updated by the server to change passwords. + If the @schemeid[allow-new-users] configuration allows new users, the + @filepath{users.ss} 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.ss} 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. + their normal passwords. To achieve this, use a list with + @schemeid[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.ss}, but make sure you have information - that matches your 'extra-fields specification. For example, given - this system file: - @verbatim[#:indent 2]{ + that matches your @schemeid[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} + bar:$1$dKlU0OkJ$t63TzKz:1205:1205:Bar Z. Lie:/home/bar:/bin/bash}| you can create this @filepath{users.ss} file: - @schemeblock[ + @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 @scheme['extra-fields] - in your @filepath{config.ss}: - @schemeblock[ + (bar ((unix "$1$dKlU0OkJ$t63TzKz") "Bar Z. Lie" "?")))}| + which can be combined with this setting for @schemeid[extra-fields] in + your @filepath{config.ss}: + @verbatim[#:indent 2]{ ... (extra-fields (("Full Name" #f #f) - ("TA" '("Alice" "Bob") "Your TA"))) - ...] + ("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 - @scheme['plaintext] symbol, which will be used without encryption. + @schemeid[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 @scheme['log-file] +@item{@filepath{log} (or any other name that the @schemeid[log-file] configuration option specifies (if any), created if not present, - appended otherwise): records connections and actions, where each - entry is of the form + appended otherwise): records connections and actions, where each entry + is of the form @verbatim{[|