From a741498c5983b77e2fc33bac35388118e519cb5c Mon Sep 17 00:00:00 2001
From: interp <interp>
Date: Thu, 9 Aug 2001 10:55:08 +0000
Subject: [PATCH] ftpd.scm: corrected typo; ftpd.scm.doc: doc for ftpd.scm

---
 doc/ftpd.scm.doc | 178 +++++++++++++++++++++++++++++++++++++++++++++++
 ftpd.scm         |  11 ++-
 2 files changed, 182 insertions(+), 7 deletions(-)
 create mode 100644 doc/ftpd.scm.doc

diff --git a/doc/ftpd.scm.doc b/doc/ftpd.scm.doc
new file mode 100644
index 0000000..6c67165
--- /dev/null
+++ b/doc/ftpd.scm.doc
@@ -0,0 +1,178 @@
+This file documents how to use the ftp-daemon ftpd
+
+USAGE
+-----
+
+Usage as a stand-alone daemon:
+
+Start the daemon in a scsh (or with a script, see below) using
+
+,config ,load modules.scm
+,open ftpd
+(ftpd <anonymous-home> [<port>])
+
+(confirm open's question for opening the ftpd-structure)
+where <anonymous-home> is the root-directory of the ftp-server and
+<port> the port the server is listening to. Usage of relative paths in
+<anonymous-home> is not encouraged. <port> defaults to 21.
+
+For example
+
+(ftpd (cwd) 8080)
+
+starts the server with the current directory as anonymous home and
+listening to port 8080.
+
+
+Usage with the collaboration of a daemon like inetd:
+
+Instead of FTPD, inetd uses FTPD-INETD, for example:
+
+(ftpd-inetd (cwd))
+
+starts the server with the current directory as anonymous home and
+handling the connection (given from inetd) through the current input-
+and output-ports.
+
+
+Example
+
+This is how archive.informatik.uni-tuebingen.de is called at the
+university of Tuebingen:
+
+#!/bin/sh
+/afs/informatik.uni-tuebingen.de/rs_aix43/scsh-0.6-alpha/bin/scsh <<EOF
+,batch on
+,config ,load modules.scm
+,open ftpd
+,open threads
+(define (archive-ftpd args)
+  (with-syslog-destination
+   #f
+   #f
+   (syslog-facility local0)
+   #f
+   (lambda ()
+     (ftpd "/afs/informatik.uni-tuebingen.de/data/archive/"))))
+(dump-scsh-program archive-ftpd "archive-ftpd.image")
+;; (dump-scsh "archive-ftpd.image")
+EOF
+
+Note, that the options for the syslog are set via With
+WITH-SYSLOG-DESTINATION, a scsh-command. Here, the syslog-facility is
+set to local0. See man syslog for further details on syslog.
+
+
+SUPPORTED COMMANDS
+------------------
+
+
+ftpd supports following commands according to RFC 959:
+
+ABOR - abort connection
+CDUP - move to parent directory
+CWD  - move to specified directory (relative paths may be used)
+DELE - delete file
+LIST - list files in current directory (long format)
+MDTM - deliver modification time of a regular file
+MKD  - make directory
+MODE - change mode (only stream mode (S) is supported)
+NLST - list files in current directory (short format)
+NOOP - do nothing
+PASS - read in passphrase
+PASV - change to passive mode
+PORT - change connection port
+PWD  - return name of working directory (print working directory)
+QUIT - quit session
+RETR - return file (GET)
+RMD  - remove directory
+RNFR - read in the name of a file to be renamed (use RNTO next)
+RNTO - rename file mentioned before in a RNFR command
+SIZE - return size of a regular file
+STOR - store file (PUT)
+STRU - change structure to transfer files
+       (only the file structure is supported)
+SYST - return system type
+TYPE - change type (supported types: A = ascii mode, I, L8 = 8-bit
+       binary  mode)
+USER - login user (only anonymous logins allowed, use "anonymous" or
+       "ftp" as user name)
+
+
+SYSLOG-MESSAGES
+---------------
+
+ftpd outputs a lot of syslog-messages. A syslog-message looks like
+this:
+
+Jul 24 18:34:52 axl ftpd: (thread 21) anonymous user login (230)
+
+The log gives you following informations (including those delivered by
+the syslog-daemon):
+
+* the date and time the log was made (here: Jul 24 18:34:52)
+* the machine the log was made on (here: axl)
+* the program, that output the log (ftpd)
+* the thread the message concerns (here thread 21)
+  Each connection is linked with a thread, that handles the commands
+  of this connection. When the thread is created, there is a log
+  containing the remote address and the thread number, so in future 
+  logs the thread number labels the connection. As at any given time 
+  the thread number is unique, this is a bijection. (Note that the 
+  thread numbers are not unique over a period of time).
+* the log message (here: notification about an anonymous user login)
+* the reply code returned by ftpd, if any (here: 230)
+
+
+The Syslog-levels used:
+-----------------------
+
+
+Overview:
+
+
+As NOTICE are logged:
+
+* messages concerning CONNECTIONS
+* the execution of the STOR command
+* internal errors
+* unix errors
+* reaching of actually unreachable case branches
+
+
+As INFO are logged:
+
+* messages concerning all OTHER COMMANDS, including the RETR command
+
+
+As DEBUG are logged:
+
+* all other messages, including debug messages
+
+
+Details:
+
+Messages concerning connections (establishing connection, connection
+refused, closing connection due to timeout, etc.) are logged at
+notice-level. 
+
+The success of the STOR-command (PUT, i.e. somebody is putting
+something on your server via ftp) is also logged at notice-level. In
+fact, the log is made before the storing is started actually.
+
+Internal errors, unix errors and the reaching of unreachable
+case-branches are also logged at notice-level.
+
+Messages concerning all other commands including the RETR-command
+(GET) are logged at info-level.
+
+All other messages including debugging-informations are logged at
+debug-level. If you want to debug ftpd, put all the messages in one
+single file, since the debug-messages may refer to messages of other
+levels.
+
+Success (as long as interesting) and failure of commands are logged at
+info-level, except the success of the STOR-command, that is logged at
+notice-level (as mentioned above).
+
+
diff --git a/ftpd.scm b/ftpd.scm
index d9928da..0b32e7e 100644
--- a/ftpd.scm
+++ b/ftpd.scm
@@ -16,11 +16,8 @@
 ; - GET-command: ftpd reports "Can't open FILENAME for reading" if
 ;   file actually doesn't exist. This is confusing. Reporting
 ;   "FILENAME does not exist" is much better.
-; - logging: 
-;   * improve syslog-levels (too much debug-messages?)  
-;   * improve perfomance (values are often calculated twice: first
-;     time for logging, second time for reporting
-; BRNR: STOPPED at 836
+
+
 
 (define-record session
   control-input-port
@@ -658,7 +655,7 @@
     (register-reply! 500
 		     "No arguments.  Not to worry---I'd ignore them anyway."))
    ((string-ci=? "F" arg)
-    (log (syslog-level info) "(still) using file structure to tranfser files (200)")
+    (log (syslog-level info) "(still) using file structure to transfer files (200)")
     (register-reply! 200 "Using file structure to transfer files."))
    (else
     (log (syslog-level info) "file structure ~S is not supported (504)" arg)
@@ -1147,7 +1144,7 @@
 
 ; Version
 
-(define *ftpd-version* "$Revision: 1.24 $")
+(define *ftpd-version* "$Revision: 1.25 $")
 
 (define (copy-port->port-binary input-port output-port)
   (let ((buffer (make-string *window-size*)))