|
<SP>, followed by one line of text (where some maximum line length
has been specified), and terminated by the Telnet end-of-line
code. There will be cases however, where the text is longer than
a single line. In these cases the complete text must be bracketed
so the User-process knows when it may stop reading the reply (i.e.
stop processing input on the control connection) and go do other
things. This requires a special format on the first line to
indicate that more than one line is coming, and another on the
last line to designate it as the last. At least one of these must
contain the appropriate reply code to indicate the state of the
transaction. To satisfy all factions, it was decided that both
the first and last line codes should be the same.
Thus the format for multi-line replies is that the first line
will begin with the exact required reply code, followed
immediately by a Hyphen, "-" (also known as Minus), followed by
text. The last line will begin with the same code, followed
immediately by Space <SP>, optionally some text, and the Telnet
end-of-line code.
For example:
123-First line
Second line
234 A line beginning with numbers
123 The last line
The user-process then simply
needs to search for the second
occurrence of the same reply code, followed by <SP> (Space), at
the beginning of a line, and ignore all intermediary lines. If
an intermediary line begins with a 3-digit number, the Server
must pad the front to avoid confusion.
This scheme allows
standard system routines to be used for
reply information (such as for the STAT reply), with
"artificial" first and last lines tacked on. In rare cases
where these routines are able to generate three digits and a
Space at the beginning of any line, the beginning of each
text line should be offset by some neutral text, like Space.
This scheme assumes that
multi-line replies may not be nested.
The three digits of the reply
each have a special significance.
This is intended to allow a range of very simple to very
sophisticated responses by the user-process. The first digit
denotes whether the response is good, bad or incomplete.
(Referring to the state diagram), an unsophisticated user-process
will be able to determine its next action (proceed as planned, redo,
retrench, etc.) by simply examining this first digit. Auser-process that
wants to know approximately what kind of error occurred (e.g. file system
error, command syntax error) may examine the second digit, reserving the
third digit for the finest
gradation of information (e.g., RNTO command without a preceding
RNFR).
There are five values for
the first digit of the reply code:
1yz Positive Preliminary reply
The requested action
is being initiated; expect another
reply before proceeding with a new command. (The
user-process sending another command before the
completion reply would be in violation of protocol; but
server-FTP processes should queue any commands that
arrive while a preceding command is in progress.) This
type of reply can be used to indicate that the command
was accepted and the user-process may now pay attention
to the data connections, for implementations where
simultaneous monitoring is difficult. The server-FTP
process may send at most, one 1yz reply per command.
2yz Positive Completion reply
The requested action has been successfully completed. A
new request may be initiated.
3yz Positive Intermediate reply
The command has been accepted, but the requested action
is being held in abeyance, pending receipt of further
information. The user should send another command
specifying this information. This reply is used in
command sequence groups.
4yz Transient Negative Completion reply
The command was not accepted and the requested action did
not take place, but the error condition is temporary and
the action may be requested again. The user should
return to the beginning of the command sequence, if any.
It is difficult to assign a meaning to "transient",
particularly when two distinct sites (Server- and
User-processes) have to agree on the interpretation.
Each reply in the 4yz category might have a slightly
different time value, but the intent is that the
user-process is encouraged to try again. A rule of thumb in determining
if a reply fits into the 4yz or the 5yz (Permanent Negative) category is
that replies are 4yz if the commands can be repeated without any change in
command form or in properties of the User or Server(e.g., the command is
spelled the same with the same arguments used; the user does not change
his file access or user name; the server does not put up a new
implementation.)
5yz Permanent Negative Completion reply
The command was not accepted and the requested action did
not take place. The User-process is discouraged from repeating the exact
request (in the same sequence). Even some "permanent" error conditions
can be corrected, so the human user may want to direct his User-process to
reinitiate the command sequence by direct action at some point in the
future (e.g., after the spelling has been
changed, or the user has altered his directory status.)
The following function groupings are encoded in the second digit:
x0z Syntax - These replies refer
to syntax errors,
syntactically correct commands that don't fit any
functional category, unimplemented or superfluous
commands.
x1z Information - These are replies to requests for
information, such as status or help.
x2z Connections - Replies referring to the control and
data connections.
x3z Authentication and accounting - Replies for the login
process and accounting procedures.
x4z Unspecified as yet.
x5z File system - These replies indicate the status of the
Server file system vis-a-vis the requested transfer or
other file system action.
The third digit gives a finer gradation of meaning in each of
the function categories, specified by the second digit. The
list of replies below will illustrate this. Note that the text
associated with each reply is recommended, rather than
mandatory, and may even change according to the command with
which it is associated. The reply codes, on the other hand,
must strictly follow the specifications in the last section;
that is, Server implementations should not invent new codes for
situations that are only slightly different from the ones
described here, but rather should adapt codes already defined.
A command such as TYPE or ALLO whose successful execution
does not offer the user-process any new information will
cause a 200 reply to be returned. If the command is not
implemented by a particular Server-FTP process because it
has no relevance to that computer system, for example ALLO
at a TOPS20 site, a Positive Completion reply is still
desired so that the simple User-process knows it can proceed
with its course of action. A 202 reply is used in this case
with, for example, the reply text: "No storage allocation
necessary." If, on the other hand, the command requests a
non-site-specific action and is unimplemented, the response
is 502. A refinement of that is the 504 reply for a command
that is implemented, but that requests an unimplemented
parameter.
4.2.1 Reply Codes by Function Groups
200 Command okay.
500 Syntax error, command unrecognized.
This may include errors such as command line too long.
501 Syntax error in parameters or arguments.
202 Command not implemented, superfluous at this site.
502 Command not implemented.
503 Bad sequence of commands.
504 Command not implemented for that parameter.
110 Restart marker reply.
In this case, the text is exact and not left to the
particular implementation; it must read:
MARK yyyy = mmmm
Where yyyy is User-process data stream marker, and mmmm
server's equivalent marker (note the spaces between markers
and "=").
211 System status, or system help reply.
212 Directory status.
213 File status.
214 Help message.
On how to use the server or the meaning of a particular
non-standard command. This reply is useful only to the
human user.
215 NAME system type.
Where NAME is an official system name from the list in the
Assigned Numbers document.
120 Service ready in nnn minutes.
220 Service ready for new user.
221 Service closing control connection.
Logged out if appropriate.
421 Service not available, closing control connection.
This may be a reply to any command if the service knows it
must shut down.
125 Data connection already open; transfer starting.
225 Data connection open; no transfer in progress.
425 Can't open data connection.
226 Closing data connection.
Requested file action successful (for example, file
transfer or file abort).
426 Connection closed; transfer aborted.
227 Entering Passive Mode (h1,h2,h3,h4,p1,p2).
230 User logged in, proceed.
530 Not logged in.
331 User name okay, need password.
332 Need account for login.
532 Need account for storing files.
150 File status okay; about to open data connection.
250 Requested file action okay, completed.
257 "PATHNAME" created.
350 Requested file action pending further information.
450 Requested file action not taken.
File unavailable (e.g., file busy).
550 Requested action not taken.
File unavailable (e.g., file not found, no access).
451 Requested action aborted. Local error in processing.
551 Requested action aborted. Page type unknown.
452 Requested action not taken.
Insufficient storage space in system.
552 Requested file action aborted.
Exceeded storage allocation (for current directory or
dataset).
553 Requested action not taken.
File name not allowed.
4.2.2 Numeric Order List of Reply Codes
110 Restart marker reply.
In this case, the text is exact and not left to the
particular implementation; it must read:
MARK yyyy = mmmm
Where yyyy is User-process data stream marker, and mmmm
server's equivalent marker (note the spaces between markers
and "=").
120 Service ready in nnn minutes.
125 Data connection already open; transfer starting.
150 File status okay; about to open data connection.
200 Command okay.
202 Command not implemented, superfluous at this site.
211 System status, or system help reply.
212 Directory status.
213 File status.
214 Help message.
On how to use the server or the meaning of a particular
non-standard command. This reply is useful only to the
human user.
215 NAME system type.
Where NAME is an official system name from the list in the
Assigned Numbers document.
220 Service ready for new user.
221 Service closing control connection.
Logged out if appropriate.
225 Data connection open; no transfer in progress.
226 Closing data connection.
Requested file action successful (for example, file
transfer or file abort).
227 Entering Passive Mode (h1,h2,h3,h4,p1,p2).
230 User logged in, proceed.
250 Requested file action okay, completed.
257 "PATHNAME" created.
|
331 User name okay, need password.
332 Need account for login.
350 Requested file action pending further information.
421 Service not available, closing control connection.
This may be a reply to any command if the service knows it
must shut down.
425 Can't open data connection.
426 Connection closed; transfer aborted.
450 Requested file action not taken.
File unavailable (e.g., file busy).
451 Requested action aborted: local error in processing.
452 Requested action not taken.
Insufficient storage space in system.
500 Syntax error, command unrecognized.
This may include errors such as command line too long.
501 Syntax error in parameters or arguments.
502 Command not implemented.
503 Bad sequence of commands.
504 Command not implemented for that parameter.
530 Not logged in.
532 Need account for storing files.
550 Requested action not taken.
File unavailable (e.g., file not found, no access).
551 Requested action aborted: page type unknown.
552 Requested file action aborted.
Exceeded storage allocation (for current directory or
dataset).
553 Requested action not taken.
File name not allowed.
5. DECLARATIVE SPECIFICATIONS
5.1. MINIMUM IMPLEMENTATION
In order to make FTP workable without needless error messages, the
following minimum implementation is required for all servers:
TYPE - ASCII Non-print
MODE - Stream
STRUCTURE - File, Record
COMMANDS - USER, QUIT, PORT,
TYPE, MODE, STRU,
for the default values
RETR, STOR,
NOOP.
The default values for transfer parameters are:
TYPE - ASCII Non-print
MODE - Stream
STRU - File
All hosts must accept the above as the standard defaults.
5.2. CONNECTIONS
The server protocol interpreter shall "listen" on Port L. The
user or user protocol interpreter shall initiate the full-duplex
control connection. Server- and user- processes should follow the
conventions of the Telnet protocol as specified in the
ARPA-Internet Protocol Handbook [1]. Servers are under no
obligation to provide for editing of command lines and may require
that it be done in the user host. The control connection shall be
closed by the server at the user's request after all transfers and
replies are completed.
The user-DTP must "listen" on the specified data port; this may be
the default user port (U) or a port specified in the PORT command.
The server shall initiate the data connection from his own default
data port (L-1) using the specified user data port. The direction
of the transfer and the port used will be determined by the FTP
service command.
Note that all FTP implementation must support data transfer using
the default port, and that only the USER-PI may initiate the use
of non-default ports.
When data is to be transferred between two servers, A and B (refer
to Figure 2), the user-PI, C, sets up control connections with
both server-PI's. One of the servers, say A, is then sent a PASV
command telling him to "listen" on his data port rather than
initiate a connection when he receives a transfer service command.
When the user-PI receives an acknowledgment to the PASV command,
which includes the identity of the host and port being listened
on, the user-PI then sends A's port, a, to B in a PORT command; a
reply is returned. The user-PI may then send the corresponding
service commands to A and B. Server B initiates the connection
and the transfer proceeds. The command-reply sequence is listed
below where the messages are vertically synchronous but
horizontally asynchronous:
User-PI - Server A User-PI - Server B
------------------ ------------------
C->A : Connect C->B : Connect
C->A : PASV
A->C : 227 Entering Passive Mode. A1,A2,A3,A4,a1,a2
C->B : PORT A1,A2,A3,A4,a1,a2
B->C : 200 Okay
C->A : STOR C->B : RETR
B->A : Connect to HOST-A, PORT-a
The data connection shall be closed by the server under the
conditions described in the Section on Establishing Data
Connections. If the data connection is to be closed following a
data transfer where closing the connection is not required to
indicate the end-of-file, the server must do so immediately.
Waiting until after a new transfer command is not permitted
because the user-process will have already tested the data
connection to see if it needs to do a "listen"; (remember that the
user must "listen" on a closed data port BEFORE sending the
transfer request). To prevent a race condition here, the server
sends a reply (226) after closing the data connection (or if the
connection is left open, a "file transfer completed" reply (250)
and the user-PI should wait for one of these replies before
issuing a new transfer command).
Any time either the user or server see that the connection is
being closed by the other side, it should promptly read any
remaining data queued on the connection and issue the close on its
own side.
5.3. COMMANDS
The commands are Telnet character strings transmitted over the
control connections as described in the Section on FTP Commands.
The command functions and semantics are described in the Section
on Access Control Commands, Transfer Parameter Commands, FTP
Service Commands, and Miscellaneous Commands. The command syntax
is specified here.
The commands begin with a command code followed by an argument
field. The command codes are four or fewer alphabetic characters.
Upper and lower case alphabetic characters are to be treated
identically. Thus, any of the following may represent the
retrieve command:
RETR Retr retr ReTr rETr
This also applies to any symbols representing parameter values,
such as A or a for ASCII TYPE. The command codes and the argument
fields are separated by one or more spaces.
The argument field consists of a variable length character string
ending with the character sequence <CRLF> (Carriage Return, Line
Feed) for NVT-ASCII representation; for other negotiated languages
a different end of line character might be used. It should be
noted that the server is to take no action until the end of line
code is received.
The syntax is specified below in NVT-ASCII. All characters in the
argument field are ASCII characters including any ASCII
represented decimal integers. Square brackets denote an optional
argument field. If the option is not taken, the appropriate
default is implied.
5.3.1. FTP COMMANDS
The following are the FTP commands:
USER <SP> <username> <CRLF>
PASS <SP> <password> <CRLF>
ACCT <SP> <account-information> <CRLF>
CWD <SP> <pathname> <CRLF>
CDUP <CRLF>
SMNT <SP> <pathname> <CRLF>
QUIT <CRLF>
REIN <CRLF>
PORT <SP> <host-port> <CRLF>
PASV <CRLF>
TYPE <SP> <type-code> <CRLF>
STRU <SP> <structure-code> <CRLF>
MODE <SP> <mode-code> <CRLF>
RETR <SP> <pathname> <CRLF>
STOR <SP> <pathname> <CRLF>
STOU <CRLF>
APPE <SP> <pathname> <CRLF>
ALLO <SP> <decimal-integer>
[<SP> R <SP> <decimal-integer>] <CRLF>
REST <SP> <marker> <CRLF>
RNFR <SP> <pathname> <CRLF>
RNTO <SP> <pathname> <CRLF>
ABOR <CRLF>
DELE <SP> <pathname> <CRLF>
RMD <SP> <pathname> <CRLF>
MKD <SP> <pathname> <CRLF>
PWD <CRLF>
LIST [<SP> <pathname>] <CRLF>
NLST [<SP> <pathname>] <CRLF>
SITE <SP> <string> <CRLF>
SYST <CRLF>
STAT [<SP> <pathname>] <CRLF>
HELP [<SP> <string>] <CRLF>
NOOP <CRLF>
5.3.2. FTP COMMAND ARGUMENTS
The syntax of the above argument fields (using BNF notation
where applicable) is:
<username> ::= <string>
<password> ::= <string>
<account-information> ::= <string>
<string> ::= <char> | <char><string>
<char> ::= any of the 128 ASCII characters except <CR> and
<LF>
<marker> ::= <pr-string>
<pr-string> ::= <pr-char> | <pr-char><pr-string>
<pr-char> ::= printable characters, any
ASCII code 33 through 126
<byte-size> ::= <number>
<host-port> ::= <host-number>,<port-number>
<host-number> ::= <number>,<number>,<number>,<number>
<port-number> ::= <number>,<number>
<number> ::= any decimal integer 1 through 255
<form-code> ::= N | T | C
<type-code> ::= A [<sp> <form-code>]
| E [<sp> <form-code>]
| I
| L <sp> <byte-size>
<structure-code> ::= F | R | P
<mode-code> ::= S | B | C
<pathname> ::= <string>
<decimal-integer> ::= any decimal integer
5.4. SEQUENCING OF COMMANDS AND REPLIES
The communication between the user and server is intended to be an
alternating dialogue. As such, the user issues an FTP command and
the server responds with a prompt primary reply. The user should
wait for this initial primary success or failure response before
sending further commands.
Certain commands require a second reply for which the user should
also wait. These replies may, for example, report on the progress
or completion of file transfer or the closing of the data
connection. They are secondary replies to file transfer commands.
One important group of informational replies is the connection
greetings. Under normal circumstances, a server will send a 220
reply, "awaiting input", when the connection is completed. The
user should wait for this greeting message before sending any
commands. If the server is unable to accept input right away, a
120 "expected delay" reply should be sent immediately and a 220
reply when ready. The user will then know not to hang up if there
is a delay.
|
