D. J. Bernstein
Internet publication
FTP: File Transfer Protocol

Requests, verbs, parameters, responses, and codes

An FTP conversation consists of requests sent by the client and responses sent by the server.

After the client connects, the server sends a response to the client, either accepting or rejecting the connection. This initial response is called the greeting.

If the server accepts the connection, the client sends zero or more requests to the server. Each request is handled as follows:

  1. The client sends the request to the server.
  2. The server sends one or more responses to the client. The last response either accepts or rejects the request. Previous responses are marks.

TELNET strings

RFC 959 allows the client to send certain TELNET strings at any moment, even in the middle of a request: These strings are not part of the requests, except in the case \377\377, where the request contains one \377. For example,
     \377\366RE\377\374TTR abc\377\377def\015\377\376\012\012
is a request RETR abc\377def\015\012 with several TELNET strings inserted. The client is obliged to send \377\377 whenever the request contains \377.

Similarly, the server is permitted to send the above strings at any moment, and the client must interpret them the same way. The server is obliged to use \377\377 whenever the response contains \377.

RFC 1123 prohibits clients from sending TELNET strings other than \377\377, \377\364, and \377\362. I recommend that clients and servers never send TELNET strings except as obliged above.

Request format

A request is a string of bytes. It contains
  1. a verb consisting of alphabetic ASCII characters;
  2. optionally, a space followed by a parameter; and
  3. \015\012.
Some clients fail to include the \015, so I recommend that servers look only for \012. The parameter cannot contain \012.

For example, the following request (shown without the \015\012) contains verb RETR with parameter report.ps:

     RETR report.ps
A request with verb RETR is called a ``RETR request''; similar comments apply to ``PASV request'' and so on.

Some clients send a space in certain requests even when no parameter is intended (or permitted), so I recommend that servers treat empty-parameter the same way as no-parameter.

RFC 959 states in the text that multiple spaces are allowed before the parameter, but it states in the formal syntax that only one space is allowed before the parameter. Implementors generally agree that the formal syntax is correct. I am not aware of any clients that send two spaces. I recommend that servers skip only one space before the parameter, to allow parameters that begin with spaces.

RFC 959 requires that all servers support certain requests. RFC 1123 requires that all clients and servers support certain requests, with an extremely unclear exception for ``cases where the underlying file system or operating system does not allow or support a particular command.'' These requirements cannot be taken seriously. It is often a violation of security policy, for example, for an anonymous server to support STOR, and it would be silly for a dedicated indexing client to support STOR.

Request semantics

The meaning of a request depends on (1) the verb and (2) the parameter. The format of the parameter depends on the verb.

RFC 959 specified that all verbs are interpreted without regard to case; so RETR and retr and Retr and rEtR have the same meaning. However, some FTP servers do not follow this rule. For example, Microsoft FTP Service 4.0 does not treat abor the same way as ABOR. Today's FTP clients send verbs in uppercase; I strongly recommend that new FTP clients do the same thing.

Response format

The server's response consists of one or more lines. Each line is terminated by \012.

The client can identify the last line of the response as follows: it begins with three ASCII digits and a space; previous lines do not. The three digits form a code. Codes between 100 and 199 indicate marks; codes between 200 and 399 indicate acceptance; codes between 400 and 599 indicate rejection.

For example, the following six lines have two responses:

     150-This is the first line of a mark
     123-This line does not end the mark; note the hyphen
     150 This line ends the mark
     226-This is the first line of the second response
      226 This line does not end the response; note the leading space
     226 This is the last line of the response, using code 226

Servers are required to follow several more rules, though I do not recommend that clients rely on these rules. Each line of the response is required to contain \015 immediately before the terminating \012. If the answer has more than one line, its first line is required to begin the same way as the last line, but with a hyphen in place of the space.

RFC 959 prohibited all codes other than 110, 120, 125, 150, 200, 202, 211, 212, 213, 214, 215, 220, 221, 225, 226, 227, 230, 250, 257, 331, 332, 350, 421, 425, 426, 450, 451, 452, 500, 501, 502, 503, 504, 530, 532, 550, 551, 552, and 553. (Typically the second digit is 0 for a syntax error, 1 for a human-oriented help message, 2 for a hello/goodbye message, 3 for an accounting message, or 5 for a filesystem-related message.) However, clients cannot take this list seriously; the IETF adds new codes at its whim. I recommend that clients avoid looking past the first digit of the code, either 1, 2, 3, 4, or 5. The other two digits, and all other portions of the response, are primarily for human consumption. (Exceptions: Greetings, responses with code 227, and responses with code 257 have a special format.)

Servers must not send marks except where they are explicitly allowed. Many clients cannot handle unusual marks. Typical requests do not permit any marks.

Some clients are unable to handle responses longer than one line to various requests, even though RFC 959 permits multiple-line responses under most circumstances. I recommend that servers use one-line responses whenever possible. On the other hand, many servers use multiple-line responses, so clients that cannot handle multiple-line responses need to be fixed. Some clients display multiple-line responses (often excluding the last line) for human consumption.

The server can reject any request with code

Typically 500 means that the request violated some internal parsing rule in the server, 501 means that the server does not like the format of the parameter, 502 means that the server recognized the verb but does not support it, and 504 means that the server supports the verb but does not support the parameter.

RFC 959 states that codes 400 through 499 are for temporary errors, and codes 500 through 599 are for permanent errors. Unfortunately, many servers use codes 500 through 599 for various temporary errors, often because RFC 959 failed to recognize the possibility of a temporary error. I recommend that client implementors treat all errors as temporary.