scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reasonable complete and up-to-date docs.

This commit is contained in:
sperber 2003-01-23 09:38:44 +00:00
parent b239184a38
commit a75990e8c2
1 changed files with 73 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

245
doc/latex/ftpd.tex
View File

@ -1,202 +1,103 @@
\chapter{FTP server}\label{cha:ftpd} \chapter{FTP server}\label{cha:ftpd}
\begin{description} The \ex{ftpd} structure contains a complete anonymous ftp server.
\item[Used files:] ftpd.scm
\item[Name of the package:] ftpd
\end{description}
\section{What users want to know} \defun{ftpd}{options}{\noreturn}
\defunx{ftp-inetd}{options}{\noreturn}
\begin{desc}
\ex{Ftpd} starts the server, using \var{anonymous-home} as the
root directory of the server.
\ex{ftpd-inetd} is the version to be used from \ex{inetd}.
\ex{Ftpd-inetd} handles the connection through the current standard
output and input ports.
\end{desc}
%
The \var{options} argument can be constructed through a number of
procedures with names of the form \texttt{with-\ldots}. Each of these
procedures either creates a fresh options value or adds a
configuration parameter to an old options argument. The configuration
parameter value is always the first argument, the (old) options value
the optional second one. Here they are:
\section{Entry points} \defun{with-port}{port [options]}{options}
\begin{desc}
This specifies the port on which the server listens. Defaults to 21.
\end{desc}
\defun {ftpd} {options} {\noreturn} \defun{with-anonymous-home}{string [options]}{options}
\begin{defundescx}{ftp-inetd} {anonymous-home} {\noreturn} \begin{desc}
\ex{ftpd} starts the server, using \semvar{anonymous-home} as the This specifies the home directory for anonymous logins. Defaults to
root directory of the server. Usage of relative paths is not \verb|"~ftp"|.
encouraged. \semvar{port} specifies the port the server is \end{desc}
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. If \semvar{dns-lookup?} is \sharpt, the
logfile will contain the host names instead of their IP
addresses. If \semvar{dns-lookup?} is not specified or \sharpf, the
IP addresses are stored.
The log format of \ex{ftpd} is the same as the one of \defun{with-banner}{list [options]}{options}
\ex{wuftpd}. The fields are seperated by spaces and contain \begin{desc}
following informations: This specifies an alternative greeting banner for those members of
\codex{Fri Apr 19 17:08:14 2002 4 134.2.2.171 56881 /files.lst b \_ i a nop@ssword ftp 0 *} the Untergrund who prefer to remain covert. The banner is
\begin{enumerate} represented as a list of strings, one for each line of output.
\end{desc}
\defun{with-logfile}{file-name [options]}{options}
\begin{desc}
If this is non-\sharpf, ex{ftpd} makes a log entry for each file
sent or retrieved in \var{file-name}. Defaults to \sharpf.
\end{desc}
\defun{with-dns-lookup?}{boolean [options]}{options}
\begin{desc}
If \var{dns-lookup?} is \sharpt, the log file will contain the host
names instead of their IP addresses. If \var{dns-lookup?} is \sharpf,
the log will only contain IP addresses. Defaults to \sharpf.
\end{desc}
The log format of \ex{ftpd} is the same as the one of
\ex{wuftpd}. The entries look like this:
%
\begin{verbatim}
Fri Apr 19 17:08:14 2002 4 134.2.2.171 56881 /files.lst b _ i a nop@ssword ftp 0 *
\end{verbatim}
%
These are the fields:
\begin{enumerate}
\item Current date and time. This field contains \item Current date and time. This field contains
spaces and is 24 characters long. spaces and is 24 characters long.
\item Transfer time in seconds. \item Transfer time in seconds.
\item Remote host IP (wuftpd puts the name here). \item Remote host IP (wu-ftpd puts the name here).
\item File size in bytes \item File size in bytes
\item Name of file (spaces are converted to underscores) \item Name of file (spaces are converted to underscores)
\item Transfer type: \underline{a}scii or \underline{b}inary (image type). \item Transfer type: \underline{a}scii or \underline{b}inary (image type).
\item Special action flags. As \ex{ftpd} does not support any special \item Special action flags. As \ex{ftpd} does not support any special
action, we are always `\ex{\_}' here. action, it always has \ex{\_} here.
\item File was sent to user (\underline{o}utgoing) or received from user \item File was sent to user (\underline{o}utgoing) or received from user
(\underline{i}ncoming) (\underline{i}ncoming)
\item \underline{A}nonymous access \item \underline{A}nonymous access
\item Anonymous ftp password. We do not use anyone. \item Anonymous ftp password.
\item Service name - always \ex{ftp}. \item Service name---always \ex{ftp}.
\item Authentication mode (always none = `\ex{0}'). \item Authentication mode (always ``none'' = `\ex{0}').
\item Authenticated user ID (always not available = `\ex{*}') \item Authenticated user ID (always ``not available'' = `\ex{*}')
\end{enumerate} \end{enumerate}
As the procedure does not return, you have to do a \ex{fork} in The server also writes log information to the syslog facility.
order to have a ``real'' daemon: \codex{(fork (lambda () (ftpd The following syslog levels occur in the output:
"/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} \begin{description}
\item[\ex{notice}]
\item[\ex{NOTICE} level:]
\begin{itemize} \begin{itemize}
\item Messages concerning \emph{connections} (establishing connection, \item messages concerning \emph{connections} (establishing connection,
connection refused, closing connection due to timeout, etc.) connection refused, closing connection due to timeout, etc.)
\item The execution of the \ex{STOR} command. Its success (\ie \item the execution of the \ex{STOR} command\\
Its success (\ie
somebody is putting something on your server via ftp, also known as 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 \ex{PUT}) is also logged at \ex{notice}.
before the storing is started actually. \item internal errors
\item Internal errors
\item Unix errors \item Unix errors
\item Reaching of actually unreachable case branches \item reaching of actually unreachable case branches
\end{itemize} \end{itemize}
\item[\ex{info}] Messages concerning all other commands,
\item[\ex{INFO} level:] Messages concerning all \emph{other commands},
including the \ex{RETR} command. including the \ex{RETR} command.
\item[\ex{debug}] all other messages, including debug messages
\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} \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:
%{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: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: "man" %%% TeX-master: "man"