\chapter{FTP server}\label{cha:ftpd}

\begin{description}
\item[Used files:] ftpd.scm
\item[Name of the package:] ftpd
\end{description}

\section{What users want to know}

\section{Entry points}

\defun  {ftpd} {anonymous-home \ovar{port \ovar{logfile}}} {\noreturn}
\begin{defundescx}{ftp-inetd} {anonymous-home} {\noreturn} 
  \ex{ftpd} starts the server, using \semvar{anonymous-home} as the
  root directory of the server. Usage of relative paths is not
  encouraged.  \semvar{port} specifies the port the server is
  listening for connections. It defaults to 21. \ex{ftpd} makes a log
  entry for each file sent or retrieved. These logs are written to
  \semvar{logfile}, if given.

  The log format of \ex{ftpd} is the same as the one of
  \ex{wuftpd}. The fields are seperated by spaces and contain
  following informations:
\codex{Fri Apr 19 17:08:14 2002 4 134.2.2.171 56881 /files.lst b \_ i a nop@ssword ftp 0 *}
  \begin{enumerate} 
\item Current date and time. This field contains
  spaces and is 24 characters long.
\item Transfer time in seconds.
\item Remote host IP (wuftpd puts the name here).
\item File size in bytes
\item Name of file (spaces are converted to underscores)
\item Transfer type: \underline{a}scii or \underline{b}inary (image type).
\item Special action flags. As \ex{ftpd} does not support any special
action, we are always `\ex{\_}' here.
\item File was sent to user (\underline{o}utgoing) or received from user
(\underline{i}ncoming) 
\item \underline{A}nonymous access
\item Anonymous ftp password. We do not use anyone.
\item Service name - always \ex{ftp}.
\item Authentication mode (always none = `\ex{0}').
\item Authenticated user ID (always not available = `\ex{*}')
\end{enumerate}

  As the procedure does not return, you have to do a \ex{fork} in
  order to have a ``real'' daemon: \codex{(fork (lambda () (ftpd
  "/data/ftp" 8080)))} \ex{ftpd-inetd} is the version to be used with
  a daemon like \ex{inetd}. If the server is started this way, it
  handles the connection through the current standard output and input
  ports.
\end{defundescx}

\subsubsection*{Examples}

To start the server with the current home directory as root directory
and listening on port 8080, use
\codex{(ftpd (cwd) 8080)}

This is how the ftp server at the computing faculty of the university
of Tuebingen\footnote{\texttt{archive.informatik.uni-tuebingen.de}} is
started:
\begin{alltt}
#!/bin/sh /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 "/data/archive/"))))
(dump-scsh-program archive-ftpd "archive-ftpd.image")
;; (dump-scsh "archive-ftpd.image")
EOF
\end{alltt}

Perhaps you have noticed the \ex{with-syslog-destination} command.
\ex{ftpd} generates syslog-messages that can be controlled via this
command. The following section gives you an overview of what is logged
at which level. See \ex{man 3 syslog} or the
\ex{with-syslog-destination} command in the scsh-manual for further
details.

\subsubsection*{Syslog messages}

\ex{ftpd} outputs a lot of syslog-messages. A syslog-message may look like
this:
\codex{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):

\begin{enumerate}
\item The date and time the log was made (here: Jul 24 18:34:52)
\item The machine the log was made on (here: axl)
\item The program, that output the log (ftpd)
\item 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 entry in
  the log file 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).
\item The log message (here: notification about an anonymous user login)
\item The reply code returned by ftpd, if any (here: 230)
\end{enumerate}

\subsubsection*{The Syslog-levels used\footnote{For further details
  on syslog levels see \ex{man 3 syslog}}}

Following events are logged as
\begin{description}

\item[\ex{NOTICE} level:]
\begin{itemize}
\item Messages concerning \emph{connections} (establishing connection,
  connection refused, closing connection due to timeout, etc.)
\item The execution of the \ex{STOR} command. Its success (\ie
  somebody is putting something on your server via ftp, also known as
  \ex{PUT}) is also logged at notice-level. In fact, the log is made
  before the storing is started actually.
\item Internal errors
\item Unix errors
\item Reaching of actually unreachable case branches
\end{itemize}

\item[\ex{INFO} level:] Messages concerning all \emph{other commands},
  including the \ex{RETR} command.
  
\item[\ex{DEBUG} level:] All other messages, including debug messages.
  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.
\end{description}

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).
\subsubsection*{Supported commands}

For those of you who are intrested, the table \ref{ftpd-commands}
shows the list of supported commands by \ex{ftpd} according to
RFC~959:

\FIXME{Can there be a pagebreak in a table?}


\begin{table}
\label{ftpd-commands}
\begin{center}
\begin{tabular}{|lp{10cm}|}
\hline
\ex{ABOR} & abort connection \\
\ex{CDUP} & move to parent directory \\
\ex{CWD} & move to specified directory (relative paths may be used) \\
\ex{DELE} & delete file \\
\ex{LIST} & list files in current directory (long format) \\
\ex{MDTM} & deliver modification time of a regular file \\
\ex{MKD}  & make directory \\
\ex{MODE} & change mode (only stream mode (S) is supported) \\
\ex{NLST} & list files in current directory (short format) \\
\ex{NOOP} & do nothing \\
\ex{PASS} & read in passphrase (\ex{ftpd} currently does not support
non-anonymous logins) \\
\ex{PASV} & change to passive mode \\
\ex{PORT} & change connection port \\
\ex{PWD}  & return name of working directory (print working directory) \\
\ex{QUIT} & quit session \\
\ex{RETR} & return file (GET) \\
\ex{RMD} & remove directory \\
\ex{RNFR} & read in the name of a file to be renamed (use \ex{RNTO} next) \\
\ex{RNTO} & rename file mentioned before in a \ex{RNFR} command \\
\ex{SIZE} & return size of a regular file \\
\ex{STOR} & store file (PUT) \\
\ex{STRU}& change structure to transfer files 
           (only the file structure is supported) \\
\ex{SYST} & return system type \\
\ex{TYPE} & change type (supported types: A is ascii mode, 
            I or L8 are 8-bit binary mode) \\
\ex{USER} & login user (only anonymous logins allowed, 
            use ``anonymous'' or ``ftp'' as user name) \\
\hline
\end{tabular}
\caption{Supported RFC~959 commands by the server.}
\end{center}
\end{table}


%\subsection{What programmers want to know}

%Let me know what you want to know. As long as you are waiting for my
%answer, have a look in the source file (I'm sorry).

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: man.tex
%%% End: