Reasonable complete and up-to-date docs.
This commit is contained in:
sperber
parent
b239184a38
commit
a75990e8c2
|
|
@ -1,202 +1,103 @@
|
|||
\chapter{FTP server}\label{cha:ftpd}
|
||||
|
||||
\begin{description}
|
||||
\item[Used files:] ftpd.scm
|
||||
\item[Name of the package:] ftpd
|
||||
\end{description}
|
||||
The \ex{ftpd} structure contains a complete anonymous ftp server.
|
||||
|
||||
\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}
|
||||
\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. 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.
|
||||
\defun{with-anonymous-home}{string [options]}{options}
|
||||
\begin{desc}
|
||||
This specifies the home directory for anonymous logins. Defaults to
|
||||
\verb|"~ftp"|.
|
||||
\end{desc}
|
||||
|
||||
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}
|
||||
\defun{with-banner}{list [options]}{options}
|
||||
\begin{desc}
|
||||
This specifies an alternative greeting banner for those members of
|
||||
the Untergrund who prefer to remain covert. The banner is
|
||||
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
|
||||
spaces and is 24 characters long.
|
||||
\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 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.
|
||||
action, it always has \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{*}')
|
||||
\item Anonymous ftp password.
|
||||
\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
|
||||
The server also writes log information to the syslog facility.
|
||||
The following syslog levels occur in the output:
|
||||
\begin{description}
|
||||
|
||||
\item[\ex{NOTICE} level:]
|
||||
\item[\ex{notice}]
|
||||
\begin{itemize}
|
||||
\item Messages concerning \emph{connections} (establishing connection,
|
||||
\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
|
||||
\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
|
||||
\ex{PUT}) is also logged at \ex{notice}.
|
||||
\item internal errors
|
||||
\item Unix errors
|
||||
\item Reaching of actually unreachable case branches
|
||||
\item reaching of actually unreachable case branches
|
||||
\end{itemize}
|
||||
|
||||
\item[\ex{INFO} level:] Messages concerning all \emph{other commands},
|
||||
\item[\ex{info}] Messages concerning all 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.
|
||||
\item[\ex{debug}] all other messages, including debug messages
|
||||
\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:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "man"
|
||||
|
|
|
|||
Loading…
Reference in New Issue