aboutsummaryrefslogtreecommitdiffstats
path: root/lib/inets/doc
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/inets/doc
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/inets/doc')
-rw-r--r--lib/inets/doc/archive/includes.txt168
-rw-r--r--lib/inets/doc/archive/pieces_of_code.txt83
-rw-r--r--lib/inets/doc/archive/rfc1123.txt5782
-rw-r--r--lib/inets/doc/archive/rfc1945.html3035
-rw-r--r--lib/inets/doc/archive/rfc2068.txt9075
-rw-r--r--lib/inets/doc/archive/rfc2145.txt395
-rw-r--r--lib/inets/doc/archive/rfc2428.txt451
-rw-r--r--lib/inets/doc/archive/rfc2577.txt451
-rw-r--r--lib/inets/doc/archive/rfc2616.pdfbin0 -> 550558 bytes
-rw-r--r--lib/inets/doc/archive/rfc2616.txt9859
-rw-r--r--lib/inets/doc/archive/rfc959.txt3933
-rw-r--r--lib/inets/doc/html/.gitignore0
-rw-r--r--lib/inets/doc/man3/.gitignore0
-rw-r--r--lib/inets/doc/man6/.gitignore0
-rw-r--r--lib/inets/doc/pdf/.gitignore0
-rw-r--r--lib/inets/doc/src/Makefile272
-rw-r--r--lib/inets/doc/src/book.gifbin0 -> 1081 bytes
-rw-r--r--lib/inets/doc/src/book.xml50
-rw-r--r--lib/inets/doc/src/fascicules.xml19
-rw-r--r--lib/inets/doc/src/ftp.xml939
-rw-r--r--lib/inets/doc/src/ftp_client.xml91
-rw-r--r--lib/inets/doc/src/http.xml491
-rw-r--r--lib/inets/doc/src/http_client.xml140
-rw-r--r--lib/inets/doc/src/http_server.xml1004
-rw-r--r--lib/inets/doc/src/httpd.xml1089
-rw-r--r--lib/inets/doc/src/httpd_conf.xml144
-rw-r--r--lib/inets/doc/src/httpd_socket.xml95
-rw-r--r--lib/inets/doc/src/httpd_util.xml459
-rw-r--r--lib/inets/doc/src/inets.gifbin0 -> 9763 bytes
-rw-r--r--lib/inets/doc/src/inets.xml179
-rw-r--r--lib/inets/doc/src/inets_services.xml78
-rw-r--r--lib/inets/doc/src/make.dep27
-rw-r--r--lib/inets/doc/src/marting_tankar.sdwbin0 -> 19968 bytes
-rw-r--r--lib/inets/doc/src/min_head.gifbin0 -> 2652 bytes
-rw-r--r--lib/inets/doc/src/mod_alias.xml132
-rw-r--r--lib/inets/doc/src/mod_auth.xml287
-rw-r--r--lib/inets/doc/src/mod_esi.xml123
-rw-r--r--lib/inets/doc/src/mod_security.xml158
-rw-r--r--lib/inets/doc/src/note.gifbin0 -> 1539 bytes
-rw-r--r--lib/inets/doc/src/notes.gifbin0 -> 2005 bytes
-rw-r--r--lib/inets/doc/src/notes.xml929
-rw-r--r--lib/inets/doc/src/notes_history.xml1826
-rw-r--r--lib/inets/doc/src/part.xml42
-rw-r--r--lib/inets/doc/src/part_notes.xml39
-rw-r--r--lib/inets/doc/src/part_notes_history.xml34
-rw-r--r--lib/inets/doc/src/ref_man.gifbin0 -> 1530 bytes
-rw-r--r--lib/inets/doc/src/ref_man.xml53
-rw-r--r--lib/inets/doc/src/summary.html.src1
-rw-r--r--lib/inets/doc/src/tftp.xml637
-rw-r--r--lib/inets/doc/src/user_guide.gifbin0 -> 1581 bytes
-rw-r--r--lib/inets/doc/src/warning.gifbin0 -> 1498 bytes
51 files changed, 42570 insertions, 0 deletions
diff --git a/lib/inets/doc/archive/includes.txt b/lib/inets/doc/archive/includes.txt
new file mode 100644
index 0000000000..5222790be1
--- /dev/null
+++ b/lib/inets/doc/archive/includes.txt
@@ -0,0 +1,168 @@
+ Server Side Includes (SSI)
+
+NCSA HTTPd allows users to create documents which provide simple information
+to clients on the fly. Such information can include the current date, the
+file's last modification date, and the size or last modification of other
+files. In its more advanced usage, it can provide a powerful interface to
+CGI and /bin/sh programs.
+
+ * SSI Issues
+ * SSI Setup
+ * Converting INC SRV to SSI
+ * The SSI Format
+ * SSI Environment Variables
+
+------------------------------------------------------------------------
+
+SSI Issues
+
+Having the server parse documents is a double edged sword. It can be costly
+for heavily loaded servers to perform parsing of files while sending them.
+Further, it can be considered a security risk to have average users
+executing commands as the server's User. If you disable the exec option,
+this danger is mitigated, but the performance issue remains. You should
+consider these items carefully before activating server-side includes on
+your server.
+
+------------------------------------------------------------------------
+
+SSI Setup
+
+First, you should decide which directories you want to allow Includes in.
+Most likely this will not include users' home directories or directories you
+do not trust. You should then decide, of the directories you are allowing
+includes in, which directories are safe enough to use exec in.
+
+For the directories in which you want to fully enable includes, you need to
+use the Options directive to turn on the option Includes. Similarly for the
+directories you want crippled (no exec) includes, you should use the option
+IncludesNOEXEC. In any directory you want to disable includes, use the
+Options directive without either option.
+
+Next, you need to tell the server what filename extension you are using for
+the parsed files. These files, while very similar to HTML, are not HTML and
+are thus not treated the same. Internally, the server uses the magic MIME
+type text/x-server-parsed-html to identify parsed documents. It will then
+perform a format conversion to change these files into HTML for the client.
+To tell the server which extension you want to use for parsed files, use the
+AddType directive. For instance:
+
+AddType text/x-server-parsed-html .shtml
+
+This makes any file ending with .shtml a parsed file. Alternatively, if you
+don't care about the performance hit of having all .html files parsed, you
+could use:
+
+AddType text/x-server-parsed-html .html
+
+This would make the server parse all .html files.
+
+------------------------------------------------------------------------
+
+Converting your old INC SRV documents to the SSI Format
+
+You should use the program inc2shtml in the support subdirectory of the
+HTTPd distribution to translate your documents from HTTPd 1.1 and earlier to
+the new format. Usage is simple: inc2shtml file.html > file.shtml.
+
+------------------------------------------------------------------------
+
+The SSI Format
+
+All directives to the server are formatted as SGML comments within the
+document. This is in case the document should ever find itself in the
+client's hands unparsed. Each directive has the following format:
+
+<!--#command tag1="value1" tag2="value2" -->
+
+Each command takes different arguments, most only accept one tag at a time.
+Here is a breakdown of the commands and their associated tags:
+
+ * config
+
+ The config directive controls various aspects of the file parsing.
+ There are two valid tags:
+
+ o errmsg controls what message is sent back to the client if an
+ error includes while parsing the document. When an error occurs,
+ it is logged in the server's error log.
+
+ o timefmt gives the server a new format to use when providing dates.
+ This is a string compatible with the strftime library call under
+ most versions of UNIX.
+
+ o sizefmt determines the formatting to be used when displaying the
+ size of a file. Valid choices are bytes, for a formatted byte
+ count (formatted as 1,234,567), or abbrev for an abbreviated
+ version displaying the number of kilobytes or megabytes the file
+ occupies.
+
+ * include
+
+ include will insert the text of a document into the parsed document.
+ Any included file is subject to the usual access control. This command
+ accepts two tags:
+
+ o virtual gives a virtual path to a document on the server. You must
+ access a normal file this way, you cannot access a CGI script in
+ this fashion. You can, however, access another parsed document.
+
+ o file gives a pathname relative to the current directory. ../
+ cannot be used in this pathname, nor can absolute paths be used.
+ As above, you can send other parsed documents, but you cannot send
+ CGI scripts.
+
+ * echo prints the value of one of the include variables (defined below).
+ Any dates are printed subject to the currently configured timefmt. The
+ only valid tag to this command is var, whose value is the name of the
+ variable you wish to echo.
+
+ * fsize prints the size of the specified file. Valid tags are the same as
+ with the include command. The resulting format of this command is
+ subject to the sizefmt parameter to the config command.
+
+ * flastmod prints the last modification date of the specified file,
+ subject to the formatting preference given by the timefmt parameter to
+ config. Valid tags are the same as with the include command.
+
+ * exec executes a given shell command or CGI script. It must be activated
+ to be used. Valid tags are:
+
+ o cmd will execute the given string using /bin/sh. All of the
+ variables defined below are defined, and can be used in the
+ command.
+
+ o cgi will execute the given virtual path to a CGI script and
+ include its output. The server does not perform error checking to
+ make sure your script didn't output horrible things like a GIF, so
+ be careful. It will, however, interpret any URL Location: header
+ and translate it into an HTML anchor.
+
+------------------------------------------------------------------------
+
+SSI Environment Variables
+
+A number of variables are made available to parsed documents. In addition to
+the CGI variable set, the following variables are made available:
+
+ * DOCUMENT_NAME: The current filename.
+
+ * DOCUMENT_URI: The virtual path to this document (such as
+ /docs/tutorials/foo.shtml).
+
+ * QUERY_STRING_UNESCAPED: The unescaped version of any search query the
+ client sent, with all shell-special characters escaped with \.
+
+ * DATE_LOCAL: The current date, local time zone. Subject to the timefmt
+ parameter to the config command.
+
+ * DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.
+
+ * LAST_MODIFIED: The last modification date of the current document.
+ Subject to timefmt like the others.
+
+------------------------------------------------------------------------
+ [Back] Return to tutorial index
+
+------------------------------------------------------------------------
+NCSA HTTPd Development Team / [email protected] / 9-28-95
diff --git a/lib/inets/doc/archive/pieces_of_code.txt b/lib/inets/doc/archive/pieces_of_code.txt
new file mode 100644
index 0000000000..f18fd2a20c
--- /dev/null
+++ b/lib/inets/doc/archive/pieces_of_code.txt
@@ -0,0 +1,83 @@
+
+%script_name([],_) ->
+% not_an_executable;
+%script_name([""|Rest],SoFar) ->
+% script_name(Rest,SoFar);
+%script_name([First|Rest],SoFar) ->
+% NewSoFar=SoFar++"/"++First,
+% case file:read_file_info(NewSoFar) of
+% %% Do the script exists and is it executable? To be done!
+% {ok,FileInfo} when FileInfo#file_info.type == regular ->
+% {yes,NewSoFar,[$/|Rest]};
+% {ok,FileInfo} ->
+% script_name(Rest,NewSoFar);
+% {error,Reason} ->
+% script_name(Rest,NewSoFar)
+% end.
+
+
+
+ case httpd_util:key1search(Info#mod.data,real_name) of
+ undefined ->
+ DocumentRoot=
+ httpd_util:lookup(Info#mod.config_db,document_root,""),
+ DocumentRoot++"/"++httpd_util:decode_hex(Info#mod.request_uri);
+ RealName ->
+ RealName
+ end,
+
+
+test() ->
+ disk_log:open({name,"/var/tmp/server_root/logs/access_disk_log"},
+ {file,"/var/tmp/server_root/logs/access_disk_log"},
+ {linkto,Pid},
+ {format,external},
+ {type,Type}
+ {size,{MaxBytes,MaxFiles}},
+ {head,{M,F,A}},
+
+%% order
+parse_directory(Stream,ConfigDB,Directory,[$o,$r,$d,$e,$r|Order]) ->
+ case regexp:split(Order,",") of
+ {ok,[First,Second]} ->
+ CleanSecond=clean(Second),
+ case clean(First) of
+ "allow" when CleanSecond == "deny" ->
+ ets:insert(ConfigDB,{{directory,Directory},{"order",allow_deny}}),
+ parse_directory(Stream,ConfigDB,Directory);
+ "deny" when CleanSecond == "allow" ->
+ ets:insert(ConfigDB,{{directory,Directory},{"order",deny_allow}}),
+ parse_directory(Stream,ConfigDB,Directory);
+ _ ->
+ {error,atom_to_list(?MODULE)++": "++clean(Order)++
+ " is an invalid order!"}
+ end;
+ {ok,_} ->
+ {error,atom_to_list(?MODULE)++": "++clean(Order)++
+ " is an invalid order!"}
+ end;
+
+%% Redirect
+parse(Stream,ConfigDB,[$R,$e,$d,$i,$r,$e,$c,$t|Redirect]) ->
+ case regexp:split(Redirect," ") of
+ {ok,[FakeName,URL]} ->
+ ets:insert(ConfigDB,{"Redirect",{FakeName,URL}}),
+ parse(Stream,ConfigDB);
+ {ok,_} ->
+ {error,atom_to_list(?MODULE)++": "++clean(Redirect)++
+ " is an invalid Redirect!"}
+ end;
+
+%% deny
+parse_directory(Stream,ConfigDB,Directory,[$d,$e,$n,$y|Deny]) ->
+ case regexp:split(Deny," ") of
+ {ok,["from","all"]} ->
+ ets:insert(ConfigDB,{{directory,Directory},{"deny",all}}),
+ parse_directory(Stream,ConfigDB,Directory);
+ {ok,["from"|Hosts]} ->
+ ets:insert(ConfigDB,{{directory,Directory},{"deny",Hosts}}),
+ parse_directory(Stream,ConfigDB,Directory);
+ {ok,_} ->
+ {error,atom_to_list(?MODULE)++": "++clean(Deny)++
+ " is an invalid deny!"}
+ end;
diff --git a/lib/inets/doc/archive/rfc1123.txt b/lib/inets/doc/archive/rfc1123.txt
new file mode 100644
index 0000000000..4918137c88
--- /dev/null
+++ b/lib/inets/doc/archive/rfc1123.txt
@@ -0,0 +1,5782 @@
+
+
+
+
+
+
+Network Working Group Internet Engineering Task Force
+Request for Comments: 1123 R. Braden, Editor
+ October 1989
+
+
+ Requirements for Internet Hosts -- Application and Support
+
+Status of This Memo
+
+ This RFC is an official specification for the Internet community. It
+ incorporates by reference, amends, corrects, and supplements the
+ primary protocol standards documents relating to hosts. Distribution
+ of this document is unlimited.
+
+Summary
+
+ This RFC is one of a pair that defines and discusses the requirements
+ for Internet host software. This RFC covers the application and
+ support protocols; its companion RFC-1122 covers the communication
+ protocol layers: link layer, IP layer, and transport layer.
+
+
+
+ Table of Contents
+
+
+
+
+ 1. INTRODUCTION ............................................... 5
+ 1.1 The Internet Architecture .............................. 6
+ 1.2 General Considerations ................................. 6
+ 1.2.1 Continuing Internet Evolution ..................... 6
+ 1.2.2 Robustness Principle .............................. 7
+ 1.2.3 Error Logging ..................................... 8
+ 1.2.4 Configuration ..................................... 8
+ 1.3 Reading this Document .................................. 10
+ 1.3.1 Organization ...................................... 10
+ 1.3.2 Requirements ...................................... 10
+ 1.3.3 Terminology ....................................... 11
+ 1.4 Acknowledgments ........................................ 12
+
+ 2. GENERAL ISSUES ............................................. 13
+ 2.1 Host Names and Numbers ................................. 13
+ 2.2 Using Domain Name Service .............................. 13
+ 2.3 Applications on Multihomed hosts ....................... 14
+ 2.4 Type-of-Service ........................................ 14
+ 2.5 GENERAL APPLICATION REQUIREMENTS SUMMARY ............... 15
+
+
+
+
+Internet Engineering Task Force [Page 1]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ 3. REMOTE LOGIN -- TELNET PROTOCOL ............................ 16
+ 3.1 INTRODUCTION ........................................... 16
+ 3.2 PROTOCOL WALK-THROUGH .................................. 16
+ 3.2.1 Option Negotiation ................................ 16
+ 3.2.2 Telnet Go-Ahead Function .......................... 16
+ 3.2.3 Control Functions ................................. 17
+ 3.2.4 Telnet "Synch" Signal ............................. 18
+ 3.2.5 NVT Printer and Keyboard .......................... 19
+ 3.2.6 Telnet Command Structure .......................... 20
+ 3.2.7 Telnet Binary Option .............................. 20
+ 3.2.8 Telnet Terminal-Type Option ....................... 20
+ 3.3 SPECIFIC ISSUES ........................................ 21
+ 3.3.1 Telnet End-of-Line Convention ..................... 21
+ 3.3.2 Data Entry Terminals .............................. 23
+ 3.3.3 Option Requirements ............................... 24
+ 3.3.4 Option Initiation ................................. 24
+ 3.3.5 Telnet Linemode Option ............................ 25
+ 3.4 TELNET/USER INTERFACE .................................. 25
+ 3.4.1 Character Set Transparency ........................ 25
+ 3.4.2 Telnet Commands ................................... 26
+ 3.4.3 TCP Connection Errors ............................. 26
+ 3.4.4 Non-Default Telnet Contact Port ................... 26
+ 3.4.5 Flushing Output ................................... 26
+ 3.5. TELNET REQUIREMENTS SUMMARY ........................... 27
+
+ 4. FILE TRANSFER .............................................. 29
+ 4.1 FILE TRANSFER PROTOCOL -- FTP .......................... 29
+ 4.1.1 INTRODUCTION ...................................... 29
+ 4.1.2. PROTOCOL WALK-THROUGH ............................ 29
+ 4.1.2.1 LOCAL Type ................................... 29
+ 4.1.2.2 Telnet Format Control ........................ 30
+ 4.1.2.3 Page Structure ............................... 30
+ 4.1.2.4 Data Structure Transformations ............... 30
+ 4.1.2.5 Data Connection Management ................... 31
+ 4.1.2.6 PASV Command ................................. 31
+ 4.1.2.7 LIST and NLST Commands ....................... 31
+ 4.1.2.8 SITE Command ................................. 32
+ 4.1.2.9 STOU Command ................................. 32
+ 4.1.2.10 Telnet End-of-line Code ..................... 32
+ 4.1.2.11 FTP Replies ................................. 33
+ 4.1.2.12 Connections ................................. 34
+ 4.1.2.13 Minimum Implementation; RFC-959 Section ..... 34
+ 4.1.3 SPECIFIC ISSUES ................................... 35
+ 4.1.3.1 Non-standard Command Verbs ................... 35
+ 4.1.3.2 Idle Timeout ................................. 36
+ 4.1.3.3 Concurrency of Data and Control .............. 36
+ 4.1.3.4 FTP Restart Mechanism ........................ 36
+ 4.1.4 FTP/USER INTERFACE ................................ 39
+
+
+
+Internet Engineering Task Force [Page 2]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ 4.1.4.1 Pathname Specification ....................... 39
+ 4.1.4.2 "QUOTE" Command .............................. 40
+ 4.1.4.3 Displaying Replies to User ................... 40
+ 4.1.4.4 Maintaining Synchronization .................. 40
+ 4.1.5 FTP REQUIREMENTS SUMMARY ......................... 41
+ 4.2 TRIVIAL FILE TRANSFER PROTOCOL -- TFTP ................. 44
+ 4.2.1 INTRODUCTION ...................................... 44
+ 4.2.2 PROTOCOL WALK-THROUGH ............................. 44
+ 4.2.2.1 Transfer Modes ............................... 44
+ 4.2.2.2 UDP Header ................................... 44
+ 4.2.3 SPECIFIC ISSUES ................................... 44
+ 4.2.3.1 Sorcerer's Apprentice Syndrome ............... 44
+ 4.2.3.2 Timeout Algorithms ........................... 46
+ 4.2.3.3 Extensions ................................... 46
+ 4.2.3.4 Access Control ............................... 46
+ 4.2.3.5 Broadcast Request ............................ 46
+ 4.2.4 TFTP REQUIREMENTS SUMMARY ......................... 47
+
+ 5. ELECTRONIC MAIL -- SMTP and RFC-822 ........................ 48
+ 5.1 INTRODUCTION ........................................... 48
+ 5.2 PROTOCOL WALK-THROUGH .................................. 48
+ 5.2.1 The SMTP Model .................................... 48
+ 5.2.2 Canonicalization .................................. 49
+ 5.2.3 VRFY and EXPN Commands ............................ 50
+ 5.2.4 SEND, SOML, and SAML Commands ..................... 50
+ 5.2.5 HELO Command ...................................... 50
+ 5.2.6 Mail Relay ........................................ 51
+ 5.2.7 RCPT Command ...................................... 52
+ 5.2.8 DATA Command ...................................... 53
+ 5.2.9 Command Syntax .................................... 54
+ 5.2.10 SMTP Replies ..................................... 54
+ 5.2.11 Transparency ..................................... 55
+ 5.2.12 WKS Use in MX Processing ......................... 55
+ 5.2.13 RFC-822 Message Specification .................... 55
+ 5.2.14 RFC-822 Date and Time Specification .............. 55
+ 5.2.15 RFC-822 Syntax Change ............................ 56
+ 5.2.16 RFC-822 Local-part .............................. 56
+ 5.2.17 Domain Literals .................................. 57
+ 5.2.18 Common Address Formatting Errors ................. 58
+ 5.2.19 Explicit Source Routes ........................... 58
+ 5.3 SPECIFIC ISSUES ........................................ 59
+ 5.3.1 SMTP Queueing Strategies .......................... 59
+ 5.3.1.1 Sending Strategy .............................. 59
+ 5.3.1.2 Receiving strategy ........................... 61
+ 5.3.2 Timeouts in SMTP .................................. 61
+ 5.3.3 Reliable Mail Receipt ............................. 63
+ 5.3.4 Reliable Mail Transmission ........................ 63
+ 5.3.5 Domain Name Support ............................... 65
+
+
+
+Internet Engineering Task Force [Page 3]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ 5.3.6 Mailing Lists and Aliases ......................... 65
+ 5.3.7 Mail Gatewaying ................................... 66
+ 5.3.8 Maximum Message Size .............................. 68
+ 5.4 SMTP REQUIREMENTS SUMMARY .............................. 69
+
+ 6. SUPPORT SERVICES ............................................ 72
+ 6.1 DOMAIN NAME TRANSLATION ................................. 72
+ 6.1.1 INTRODUCTION ....................................... 72
+ 6.1.2 PROTOCOL WALK-THROUGH ............................. 72
+ 6.1.2.1 Resource Records with Zero TTL ............... 73
+ 6.1.2.2 QCLASS Values ................................ 73
+ 6.1.2.3 Unused Fields ................................ 73
+ 6.1.2.4 Compression .................................. 73
+ 6.1.2.5 Misusing Configuration Info .................. 73
+ 6.1.3 SPECIFIC ISSUES ................................... 74
+ 6.1.3.1 Resolver Implementation ...................... 74
+ 6.1.3.2 Transport Protocols .......................... 75
+ 6.1.3.3 Efficient Resource Usage ..................... 77
+ 6.1.3.4 Multihomed Hosts ............................. 78
+ 6.1.3.5 Extensibility ................................ 79
+ 6.1.3.6 Status of RR Types ........................... 79
+ 6.1.3.7 Robustness ................................... 80
+ 6.1.3.8 Local Host Table ............................. 80
+ 6.1.4 DNS USER INTERFACE ................................ 81
+ 6.1.4.1 DNS Administration ........................... 81
+ 6.1.4.2 DNS User Interface ........................... 81
+ 6.1.4.3 Interface Abbreviation Facilities ............. 82
+ 6.1.5 DOMAIN NAME SYSTEM REQUIREMENTS SUMMARY ........... 84
+ 6.2 HOST INITIALIZATION .................................... 87
+ 6.2.1 INTRODUCTION ...................................... 87
+ 6.2.2 REQUIREMENTS ...................................... 87
+ 6.2.2.1 Dynamic Configuration ........................ 87
+ 6.2.2.2 Loading Phase ................................ 89
+ 6.3 REMOTE MANAGEMENT ...................................... 90
+ 6.3.1 INTRODUCTION ...................................... 90
+ 6.3.2 PROTOCOL WALK-THROUGH ............................. 90
+ 6.3.3 MANAGEMENT REQUIREMENTS SUMMARY ................... 92
+
+ 7. REFERENCES ................................................. 93
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 4]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+1. INTRODUCTION
+
+ This document is one of a pair that defines and discusses the
+ requirements for host system implementations of the Internet protocol
+ suite. This RFC covers the applications layer and support protocols.
+ Its companion RFC, "Requirements for Internet Hosts -- Communications
+ Layers" [INTRO:1] covers the lower layer protocols: transport layer,
+ IP layer, and link layer.
+
+ These documents are intended to provide guidance for vendors,
+ implementors, and users of Internet communication software. They
+ represent the consensus of a large body of technical experience and
+ wisdom, contributed by members of the Internet research and vendor
+ communities.
+
+ This RFC enumerates standard protocols that a host connected to the
+ Internet must use, and it incorporates by reference the RFCs and
+ other documents describing the current specifications for these
+ protocols. It corrects errors in the referenced documents and adds
+ additional discussion and guidance for an implementor.
+
+ For each protocol, this document also contains an explicit set of
+ requirements, recommendations, and options. The reader must
+ understand that the list of requirements in this document is
+ incomplete by itself; the complete set of requirements for an
+ Internet host is primarily defined in the standard protocol
+ specification documents, with the corrections, amendments, and
+ supplements contained in this RFC.
+
+ A good-faith implementation of the protocols that was produced after
+ careful reading of the RFC's and with some interaction with the
+ Internet technical community, and that followed good communications
+ software engineering practices, should differ from the requirements
+ of this document in only minor ways. Thus, in many cases, the
+ "requirements" in this RFC are already stated or implied in the
+ standard protocol documents, so that their inclusion here is, in a
+ sense, redundant. However, they were included because some past
+ implementation has made the wrong choice, causing problems of
+ interoperability, performance, and/or robustness.
+
+ This document includes discussion and explanation of many of the
+ requirements and recommendations. A simple list of requirements
+ would be dangerous, because:
+
+ o Some required features are more important than others, and some
+ features are optional.
+
+ o There may be valid reasons why particular vendor products that
+
+
+
+Internet Engineering Task Force [Page 5]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ are designed for restricted contexts might choose to use
+ different specifications.
+
+ However, the specifications of this document must be followed to meet
+ the general goal of arbitrary host interoperation across the
+ diversity and complexity of the Internet system. Although most
+ current implementations fail to meet these requirements in various
+ ways, some minor and some major, this specification is the ideal
+ towards which we need to move.
+
+ These requirements are based on the current level of Internet
+ architecture. This document will be updated as required to provide
+ additional clarifications or to include additional information in
+ those areas in which specifications are still evolving.
+
+ This introductory section begins with general advice to host software
+ vendors, and then gives some guidance on reading the rest of the
+ document. Section 2 contains general requirements that may be
+ applicable to all application and support protocols. Sections 3, 4,
+ and 5 contain the requirements on protocols for the three major
+ applications: Telnet, file transfer, and electronic mail,
+ respectively. Section 6 covers the support applications: the domain
+ name system, system initialization, and management. Finally, all
+ references will be found in Section 7.
+
+ 1.1 The Internet Architecture
+
+ For a brief introduction to the Internet architecture from a host
+ viewpoint, see Section 1.1 of [INTRO:1]. That section also
+ contains recommended references for general background on the
+ Internet architecture.
+
+ 1.2 General Considerations
+
+ There are two important lessons that vendors of Internet host
+ software have learned and which a new vendor should consider
+ seriously.
+
+ 1.2.1 Continuing Internet Evolution
+
+ The enormous growth of the Internet has revealed problems of
+ management and scaling in a large datagram-based packet
+ communication system. These problems are being addressed, and
+ as a result there will be continuing evolution of the
+ specifications described in this document. These changes will
+ be carefully planned and controlled, since there is extensive
+ participation in this planning by the vendors and by the
+ organizations responsible for operations of the networks.
+
+
+
+Internet Engineering Task Force [Page 6]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ Development, evolution, and revision are characteristic of
+ computer network protocols today, and this situation will
+ persist for some years. A vendor who develops computer
+ communication software for the Internet protocol suite (or any
+ other protocol suite!) and then fails to maintain and update
+ that software for changing specifications is going to leave a
+ trail of unhappy customers. The Internet is a large
+ communication network, and the users are in constant contact
+ through it. Experience has shown that knowledge of
+ deficiencies in vendor software propagates quickly through the
+ Internet technical community.
+
+ 1.2.2 Robustness Principle
+
+ At every layer of the protocols, there is a general rule whose
+ application can lead to enormous benefits in robustness and
+ interoperability:
+
+ "Be liberal in what you accept, and
+ conservative in what you send"
+
+ Software should be written to deal with every conceivable
+ error, no matter how unlikely; sooner or later a packet will
+ come in with that particular combination of errors and
+ attributes, and unless the software is prepared, chaos can
+ ensue. In general, it is best to assume that the network is
+ filled with malevolent entities that will send in packets
+ designed to have the worst possible effect. This assumption
+ will lead to suitable protective design, although the most
+ serious problems in the Internet have been caused by
+ unenvisaged mechanisms triggered by low-probability events;
+ mere human malice would never have taken so devious a course!
+
+ Adaptability to change must be designed into all levels of
+ Internet host software. As a simple example, consider a
+ protocol specification that contains an enumeration of values
+ for a particular header field -- e.g., a type field, a port
+ number, or an error code; this enumeration must be assumed to
+ be incomplete. Thus, if a protocol specification defines four
+ possible error codes, the software must not break when a fifth
+ code shows up. An undefined code might be logged (see below),
+ but it must not cause a failure.
+
+ The second part of the principle is almost as important:
+ software on other hosts may contain deficiencies that make it
+ unwise to exploit legal but obscure protocol features. It is
+ unwise to stray far from the obvious and simple, lest untoward
+ effects result elsewhere. A corollary of this is "watch out
+
+
+
+Internet Engineering Task Force [Page 7]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ for misbehaving hosts"; host software should be prepared, not
+ just to survive other misbehaving hosts, but also to cooperate
+ to limit the amount of disruption such hosts can cause to the
+ shared communication facility.
+
+ 1.2.3 Error Logging
+
+ The Internet includes a great variety of host and gateway
+ systems, each implementing many protocols and protocol layers,
+ and some of these contain bugs and mis-features in their
+ Internet protocol software. As a result of complexity,
+ diversity, and distribution of function, the diagnosis of user
+ problems is often very difficult.
+
+ Problem diagnosis will be aided if host implementations include
+ a carefully designed facility for logging erroneous or
+ "strange" protocol events. It is important to include as much
+ diagnostic information as possible when an error is logged. In
+ particular, it is often useful to record the header(s) of a
+ packet that caused an error. However, care must be taken to
+ ensure that error logging does not consume prohibitive amounts
+ of resources or otherwise interfere with the operation of the
+ host.
+
+ There is a tendency for abnormal but harmless protocol events
+ to overflow error logging files; this can be avoided by using a
+ "circular" log, or by enabling logging only while diagnosing a
+ known failure. It may be useful to filter and count duplicate
+ successive messages. One strategy that seems to work well is:
+ (1) always count abnormalities and make such counts accessible
+ through the management protocol (see Section 6.3); and (2)
+ allow the logging of a great variety of events to be
+ selectively enabled. For example, it might useful to be able
+ to "log everything" or to "log everything for host X".
+
+ Note that different managements may have differing policies
+ about the amount of error logging that they want normally
+ enabled in a host. Some will say, "if it doesn't hurt me, I
+ don't want to know about it", while others will want to take a
+ more watchful and aggressive attitude about detecting and
+ removing protocol abnormalities.
+
+ 1.2.4 Configuration
+
+ It would be ideal if a host implementation of the Internet
+ protocol suite could be entirely self-configuring. This would
+ allow the whole suite to be implemented in ROM or cast into
+ silicon, it would simplify diskless workstations, and it would
+
+
+
+Internet Engineering Task Force [Page 8]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ be an immense boon to harried LAN administrators as well as
+ system vendors. We have not reached this ideal; in fact, we
+ are not even close.
+
+ At many points in this document, you will find a requirement
+ that a parameter be a configurable option. There are several
+ different reasons behind such requirements. In a few cases,
+ there is current uncertainty or disagreement about the best
+ value, and it may be necessary to update the recommended value
+ in the future. In other cases, the value really depends on
+ external factors -- e.g., the size of the host and the
+ distribution of its communication load, or the speeds and
+ topology of nearby networks -- and self-tuning algorithms are
+ unavailable and may be insufficient. In some cases,
+ configurability is needed because of administrative
+ requirements.
+
+ Finally, some configuration options are required to communicate
+ with obsolete or incorrect implementations of the protocols,
+ distributed without sources, that unfortunately persist in many
+ parts of the Internet. To make correct systems coexist with
+ these faulty systems, administrators often have to "mis-
+ configure" the correct systems. This problem will correct
+ itself gradually as the faulty systems are retired, but it
+ cannot be ignored by vendors.
+
+ When we say that a parameter must be configurable, we do not
+ intend to require that its value be explicitly read from a
+ configuration file at every boot time. We recommend that
+ implementors set up a default for each parameter, so a
+ configuration file is only necessary to override those defaults
+ that are inappropriate in a particular installation. Thus, the
+ configurability requirement is an assurance that it will be
+ POSSIBLE to override the default when necessary, even in a
+ binary-only or ROM-based product.
+
+ This document requires a particular value for such defaults in
+ some cases. The choice of default is a sensitive issue when
+ the configuration item controls the accommodation to existing
+ faulty systems. If the Internet is to converge successfully to
+ complete interoperability, the default values built into
+ implementations must implement the official protocol, not
+ "mis-configurations" to accommodate faulty implementations.
+ Although marketing considerations have led some vendors to
+ choose mis-configuration defaults, we urge vendors to choose
+ defaults that will conform to the standard.
+
+ Finally, we note that a vendor needs to provide adequate
+
+
+
+Internet Engineering Task Force [Page 9]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ documentation on all configuration parameters, their limits and
+ effects.
+
+
+ 1.3 Reading this Document
+
+ 1.3.1 Organization
+
+ In general, each major section is organized into the following
+ subsections:
+
+ (1) Introduction
+
+ (2) Protocol Walk-Through -- considers the protocol
+ specification documents section-by-section, correcting
+ errors, stating requirements that may be ambiguous or
+ ill-defined, and providing further clarification or
+ explanation.
+
+ (3) Specific Issues -- discusses protocol design and
+ implementation issues that were not included in the walk-
+ through.
+
+ (4) Interfaces -- discusses the service interface to the next
+ higher layer.
+
+ (5) Summary -- contains a summary of the requirements of the
+ section.
+
+ Under many of the individual topics in this document, there is
+ parenthetical material labeled "DISCUSSION" or
+ "IMPLEMENTATION". This material is intended to give
+ clarification and explanation of the preceding requirements
+ text. It also includes some suggestions on possible future
+ directions or developments. The implementation material
+ contains suggested approaches that an implementor may want to
+ consider.
+
+ The summary sections are intended to be guides and indexes to
+ the text, but are necessarily cryptic and incomplete. The
+ summaries should never be used or referenced separately from
+ the complete RFC.
+
+ 1.3.2 Requirements
+
+ In this document, the words that are used to define the
+ significance of each particular requirement are capitalized.
+ These words are:
+
+
+
+Internet Engineering Task Force [Page 10]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ * "MUST"
+
+ This word or the adjective "REQUIRED" means that the item
+ is an absolute requirement of the specification.
+
+ * "SHOULD"
+
+ This word or the adjective "RECOMMENDED" means that there
+ may exist valid reasons in particular circumstances to
+ ignore this item, but the full implications should be
+ understood and the case carefully weighed before choosing
+ a different course.
+
+ * "MAY"
+
+ This word or the adjective "OPTIONAL" means that this item
+ is truly optional. One vendor may choose to include the
+ item because a particular marketplace requires it or
+ because it enhances the product, for example; another
+ vendor may omit the same item.
+
+
+ An implementation is not compliant if it fails to satisfy one
+ or more of the MUST requirements for the protocols it
+ implements. An implementation that satisfies all the MUST and
+ all the SHOULD requirements for its protocols is said to be
+ "unconditionally compliant"; one that satisfies all the MUST
+ requirements but not all the SHOULD requirements for its
+ protocols is said to be "conditionally compliant".
+
+ 1.3.3 Terminology
+
+ This document uses the following technical terms:
+
+ Segment
+ A segment is the unit of end-to-end transmission in the
+ TCP protocol. A segment consists of a TCP header followed
+ by application data. A segment is transmitted by
+ encapsulation in an IP datagram.
+
+ Message
+ This term is used by some application layer protocols
+ (particularly SMTP) for an application data unit.
+
+ Datagram
+ A [UDP] datagram is the unit of end-to-end transmission in
+ the UDP protocol.
+
+
+
+
+Internet Engineering Task Force [Page 11]
+
+
+
+
+RFC1123 INTRODUCTION October 1989
+
+
+ Multihomed
+ A host is said to be multihomed if it has multiple IP
+ addresses to connected networks.
+
+
+
+ 1.4 Acknowledgments
+
+ This document incorporates contributions and comments from a large
+ group of Internet protocol experts, including representatives of
+ university and research labs, vendors, and government agencies.
+ It was assembled primarily by the Host Requirements Working Group
+ of the Internet Engineering Task Force (IETF).
+
+ The Editor would especially like to acknowledge the tireless
+ dedication of the following people, who attended many long
+ meetings and generated 3 million bytes of electronic mail over the
+ past 18 months in pursuit of this document: Philip Almquist, Dave
+ Borman (Cray Research), Noel Chiappa, Dave Crocker (DEC), Steve
+ Deering (Stanford), Mike Karels (Berkeley), Phil Karn (Bellcore),
+ John Lekashman (NASA), Charles Lynn (BBN), Keith McCloghrie (TWG),
+ Paul Mockapetris (ISI), Thomas Narten (Purdue), Craig Partridge
+ (BBN), Drew Perkins (CMU), and James Van Bokkelen (FTP Software).
+
+ In addition, the following people made major contributions to the
+ effort: Bill Barns (Mitre), Steve Bellovin (AT&T), Mike Brescia
+ (BBN), Ed Cain (DCA), Annette DeSchon (ISI), Martin Gross (DCA),
+ Phill Gross (NRI), Charles Hedrick (Rutgers), Van Jacobson (LBL),
+ John Klensin (MIT), Mark Lottor (SRI), Milo Medin (NASA), Bill
+ Melohn (Sun Microsystems), Greg Minshall (Kinetics), Jeff Mogul
+ (DEC), John Mullen (CMC), Jon Postel (ISI), John Romkey (Epilogue
+ Technology), and Mike StJohns (DCA). The following also made
+ significant contributions to particular areas: Eric Allman
+ (Berkeley), Rob Austein (MIT), Art Berggreen (ACC), Keith Bostic
+ (Berkeley), Vint Cerf (NRI), Wayne Hathaway (NASA), Matt Korn
+ (IBM), Erik Naggum (Naggum Software, Norway), Robert Ullmann
+ (Prime Computer), David Waitzman (BBN), Frank Wancho (USA), Arun
+ Welch (Ohio State), Bill Westfield (Cisco), and Rayan Zachariassen
+ (Toronto).
+
+ We are grateful to all, including any contributors who may have
+ been inadvertently omitted from this list.
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 12]
+
+
+
+
+RFC1123 APPLICATIONS LAYER -- GENERAL October 1989
+
+
+2. GENERAL ISSUES
+
+ This section contains general requirements that may be applicable to
+ all application-layer protocols.
+
+ 2.1 Host Names and Numbers
+
+ The syntax of a legal Internet host name was specified in RFC-952
+ [DNS:4]. One aspect of host name syntax is hereby changed: the
+ restriction on the first character is relaxed to allow either a
+ letter or a digit. Host software MUST support this more liberal
+ syntax.
+
+ Host software MUST handle host names of up to 63 characters and
+ SHOULD handle host names of up to 255 characters.
+
+ Whenever a user inputs the identity of an Internet host, it SHOULD
+ be possible to enter either (1) a host domain name or (2) an IP
+ address in dotted-decimal ("#.#.#.#") form. The host SHOULD check
+ the string syntactically for a dotted-decimal number before
+ looking it up in the Domain Name System.
+
+ DISCUSSION:
+ This last requirement is not intended to specify the complete
+ syntactic form for entering a dotted-decimal host number;
+ that is considered to be a user-interface issue. For
+ example, a dotted-decimal number must be enclosed within
+ "[ ]" brackets for SMTP mail (see Section 5.2.17). This
+ notation could be made universal within a host system,
+ simplifying the syntactic checking for a dotted-decimal
+ number.
+
+ If a dotted-decimal number can be entered without such
+ identifying delimiters, then a full syntactic check must be
+ made, because a segment of a host domain name is now allowed
+ to begin with a digit and could legally be entirely numeric
+ (see Section 6.1.2.4). However, a valid host name can never
+ have the dotted-decimal form #.#.#.#, since at least the
+ highest-level component label will be alphabetic.
+
+ 2.2 Using Domain Name Service
+
+ Host domain names MUST be translated to IP addresses as described
+ in Section 6.1.
+
+ Applications using domain name services MUST be able to cope with
+ soft error conditions. Applications MUST wait a reasonable
+ interval between successive retries due to a soft error, and MUST
+
+
+
+Internet Engineering Task Force [Page 13]
+
+
+
+
+RFC1123 APPLICATIONS LAYER -- GENERAL October 1989
+
+
+ allow for the possibility that network problems may deny service
+ for hours or even days.
+
+ An application SHOULD NOT rely on the ability to locate a WKS
+ record containing an accurate listing of all services at a
+ particular host address, since the WKS RR type is not often used
+ by Internet sites. To confirm that a service is present, simply
+ attempt to use it.
+
+ 2.3 Applications on Multihomed hosts
+
+ When the remote host is multihomed, the name-to-address
+ translation will return a list of alternative IP addresses. As
+ specified in Section 6.1.3.4, this list should be in order of
+ decreasing preference. Application protocol implementations
+ SHOULD be prepared to try multiple addresses from the list until
+ success is obtained. More specific requirements for SMTP are
+ given in Section 5.3.4.
+
+ When the local host is multihomed, a UDP-based request/response
+ application SHOULD send the response with an IP source address
+ that is the same as the specific destination address of the UDP
+ request datagram. The "specific destination address" is defined
+ in the "IP Addressing" section of the companion RFC [INTRO:1].
+
+ Similarly, a server application that opens multiple TCP
+ connections to the same client SHOULD use the same local IP
+ address for all.
+
+ 2.4 Type-of-Service
+
+ Applications MUST select appropriate TOS values when they invoke
+ transport layer services, and these values MUST be configurable.
+ Note that a TOS value contains 5 bits, of which only the most-
+ significant 3 bits are currently defined; the other two bits MUST
+ be zero.
+
+ DISCUSSION:
+ As gateway algorithms are developed to implement Type-of-
+ Service, the recommended values for various application
+ protocols may change. In addition, it is likely that
+ particular combinations of users and Internet paths will want
+ non-standard TOS values. For these reasons, the TOS values
+ must be configurable.
+
+ See the latest version of the "Assigned Numbers" RFC
+ [INTRO:5] for the recommended TOS values for the major
+ application protocols.
+
+
+
+Internet Engineering Task Force [Page 14]
+
+
+
+
+RFC1123 APPLICATIONS LAYER -- GENERAL October 1989
+
+
+ 2.5 GENERAL APPLICATION REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-----------------------------------------------|----------|-|-|-|-|-|--
+ | | | | | | |
+User interfaces: | | | | | | |
+ Allow host name to begin with digit |2.1 |x| | | | |
+ Host names of up to 635 characters |2.1 |x| | | | |
+ Host names of up to 255 characters |2.1 | |x| | | |
+ Support dotted-decimal host numbers |2.1 | |x| | | |
+ Check syntactically for dotted-dec first |2.1 | |x| | | |
+ | | | | | | |
+Map domain names per Section 6.1 |2.2 |x| | | | |
+Cope with soft DNS errors |2.2 |x| | | | |
+ Reasonable interval between retries |2.2 |x| | | | |
+ Allow for long outages |2.2 |x| | | | |
+Expect WKS records to be available |2.2 | | | |x| |
+ | | | | | | |
+Try multiple addr's for remote multihomed host |2.3 | |x| | | |
+UDP reply src addr is specific dest of request |2.3 | |x| | | |
+Use same IP addr for related TCP connections |2.3 | |x| | | |
+Specify appropriate TOS values |2.4 |x| | | | |
+ TOS values configurable |2.4 |x| | | | |
+ Unused TOS bits zero |2.4 |x| | | | |
+ | | | | | | |
+ | | | | | | |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 15]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+3. REMOTE LOGIN -- TELNET PROTOCOL
+
+ 3.1 INTRODUCTION
+
+ Telnet is the standard Internet application protocol for remote
+ login. It provides the encoding rules to link a user's
+ keyboard/display on a client ("user") system with a command
+ interpreter on a remote server system. A subset of the Telnet
+ protocol is also incorporated within other application protocols,
+ e.g., FTP and SMTP.
+
+ Telnet uses a single TCP connection, and its normal data stream
+ ("Network Virtual Terminal" or "NVT" mode) is 7-bit ASCII with
+ escape sequences to embed control functions. Telnet also allows
+ the negotiation of many optional modes and functions.
+
+ The primary Telnet specification is to be found in RFC-854
+ [TELNET:1], while the options are defined in many other RFCs; see
+ Section 7 for references.
+
+ 3.2 PROTOCOL WALK-THROUGH
+
+ 3.2.1 Option Negotiation: RFC-854, pp. 2-3
+
+ Every Telnet implementation MUST include option negotiation and
+ subnegotiation machinery [TELNET:2].
+
+ A host MUST carefully follow the rules of RFC-854 to avoid
+ option-negotiation loops. A host MUST refuse (i.e, reply
+ WONT/DONT to a DO/WILL) an unsupported option. Option
+ negotiation SHOULD continue to function (even if all requests
+ are refused) throughout the lifetime of a Telnet connection.
+
+ If all option negotiations fail, a Telnet implementation MUST
+ default to, and support, an NVT.
+
+ DISCUSSION:
+ Even though more sophisticated "terminals" and supporting
+ option negotiations are becoming the norm, all
+ implementations must be prepared to support an NVT for any
+ user-server communication.
+
+ 3.2.2 Telnet Go-Ahead Function: RFC-854, p. 5, and RFC-858
+
+ On a host that never sends the Telnet command Go Ahead (GA),
+ the Telnet Server MUST attempt to negotiate the Suppress Go
+ Ahead option (i.e., send "WILL Suppress Go Ahead"). A User or
+ Server Telnet MUST always accept negotiation of the Suppress Go
+
+
+
+Internet Engineering Task Force [Page 16]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ Ahead option.
+
+ When it is driving a full-duplex terminal for which GA has no
+ meaning, a User Telnet implementation MAY ignore GA commands.
+
+ DISCUSSION:
+ Half-duplex ("locked-keyboard") line-at-a-time terminals
+ for which the Go-Ahead mechanism was designed have largely
+ disappeared from the scene. It turned out to be difficult
+ to implement sending the Go-Ahead signal in many operating
+ systems, even some systems that support native half-duplex
+ terminals. The difficulty is typically that the Telnet
+ server code does not have access to information about
+ whether the user process is blocked awaiting input from
+ the Telnet connection, i.e., it cannot reliably determine
+ when to send a GA command. Therefore, most Telnet Server
+ hosts do not send GA commands.
+
+ The effect of the rules in this section is to allow either
+ end of a Telnet connection to veto the use of GA commands.
+
+ There is a class of half-duplex terminals that is still
+ commercially important: "data entry terminals," which
+ interact in a full-screen manner. However, supporting
+ data entry terminals using the Telnet protocol does not
+ require the Go Ahead signal; see Section 3.3.2.
+
+ 3.2.3 Control Functions: RFC-854, pp. 7-8
+
+ The list of Telnet commands has been extended to include EOR
+ (End-of-Record), with code 239 [TELNET:9].
+
+ Both User and Server Telnets MAY support the control functions
+ EOR, EC, EL, and Break, and MUST support AO, AYT, DM, IP, NOP,
+ SB, and SE.
+
+ A host MUST be able to receive and ignore any Telnet control
+ functions that it does not support.
+
+ DISCUSSION:
+ Note that a Server Telnet is required to support the
+ Telnet IP (Interrupt Process) function, even if the server
+ host has an equivalent in-stream function (e.g., Control-C
+ in many systems). The Telnet IP function may be stronger
+ than an in-stream interrupt command, because of the out-
+ of-band effect of TCP urgent data.
+
+ The EOR control function may be used to delimit the
+
+
+
+Internet Engineering Task Force [Page 17]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ stream. An important application is data entry terminal
+ support (see Section 3.3.2). There was concern that since
+ EOR had not been defined in RFC-854, a host that was not
+ prepared to correctly ignore unknown Telnet commands might
+ crash if it received an EOR. To protect such hosts, the
+ End-of-Record option [TELNET:9] was introduced; however, a
+ properly implemented Telnet program will not require this
+ protection.
+
+ 3.2.4 Telnet "Synch" Signal: RFC-854, pp. 8-10
+
+ When it receives "urgent" TCP data, a User or Server Telnet
+ MUST discard all data except Telnet commands until the DM (and
+ end of urgent) is reached.
+
+ When it sends Telnet IP (Interrupt Process), a User Telnet
+ SHOULD follow it by the Telnet "Synch" sequence, i.e., send as
+ TCP urgent data the sequence "IAC IP IAC DM". The TCP urgent
+ pointer points to the DM octet.
+
+ When it receives a Telnet IP command, a Server Telnet MAY send
+ a Telnet "Synch" sequence back to the user, to flush the output
+ stream. The choice ought to be consistent with the way the
+ server operating system behaves when a local user interrupts a
+ process.
+
+ When it receives a Telnet AO command, a Server Telnet MUST send
+ a Telnet "Synch" sequence back to the user, to flush the output
+ stream.
+
+ A User Telnet SHOULD have the capability of flushing output
+ when it sends a Telnet IP; see also Section 3.4.5.
+
+ DISCUSSION:
+ There are three possible ways for a User Telnet to flush
+ the stream of server output data:
+
+ (1) Send AO after IP.
+
+ This will cause the server host to send a "flush-
+ buffered-output" signal to its operating system.
+ However, the AO may not take effect locally, i.e.,
+ stop terminal output at the User Telnet end, until
+ the Server Telnet has received and processed the AO
+ and has sent back a "Synch".
+
+ (2) Send DO TIMING-MARK [TELNET:7] after IP, and discard
+ all output locally until a WILL/WONT TIMING-MARK is
+
+
+
+Internet Engineering Task Force [Page 18]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ received from the Server Telnet.
+
+ Since the DO TIMING-MARK will be processed after the
+ IP at the server, the reply to it should be in the
+ right place in the output data stream. However, the
+ TIMING-MARK will not send a "flush buffered output"
+ signal to the server operating system. Whether or
+ not this is needed is dependent upon the server
+ system.
+
+ (3) Do both.
+
+ The best method is not entirely clear, since it must
+ accommodate a number of existing server hosts that do not
+ follow the Telnet standards in various ways. The safest
+ approach is probably to provide a user-controllable option
+ to select (1), (2), or (3).
+
+ 3.2.5 NVT Printer and Keyboard: RFC-854, p. 11
+
+ In NVT mode, a Telnet SHOULD NOT send characters with the
+ high-order bit 1, and MUST NOT send it as a parity bit.
+ Implementations that pass the high-order bit to applications
+ SHOULD negotiate binary mode (see Section 3.2.6).
+
+
+ DISCUSSION:
+ Implementors should be aware that a strict reading of
+ RFC-854 allows a client or server expecting NVT ASCII to
+ ignore characters with the high-order bit set. In
+ general, binary mode is expected to be used for
+ transmission of an extended (beyond 7-bit) character set
+ with Telnet.
+
+ However, there exist applications that really need an 8-
+ bit NVT mode, which is currently not defined, and these
+ existing applications do set the high-order bit during
+ part or all of the life of a Telnet connection. Note that
+ binary mode is not the same as 8-bit NVT mode, since
+ binary mode turns off end-of-line processing. For this
+ reason, the requirements on the high-order bit are stated
+ as SHOULD, not MUST.
+
+ RFC-854 defines a minimal set of properties of a "network
+ virtual terminal" or NVT; this is not meant to preclude
+ additional features in a real terminal. A Telnet
+ connection is fully transparent to all 7-bit ASCII
+ characters, including arbitrary ASCII control characters.
+
+
+
+Internet Engineering Task Force [Page 19]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ For example, a terminal might support full-screen commands
+ coded as ASCII escape sequences; a Telnet implementation
+ would pass these sequences as uninterpreted data. Thus,
+ an NVT should not be conceived as a terminal type of a
+ highly-restricted device.
+
+ 3.2.6 Telnet Command Structure: RFC-854, p. 13
+
+ Since options may appear at any point in the data stream, a
+ Telnet escape character (known as IAC, with the value 255) to
+ be sent as data MUST be doubled.
+
+ 3.2.7 Telnet Binary Option: RFC-856
+
+ When the Binary option has been successfully negotiated,
+ arbitrary 8-bit characters are allowed. However, the data
+ stream MUST still be scanned for IAC characters, any embedded
+ Telnet commands MUST be obeyed, and data bytes equal to IAC
+ MUST be doubled. Other character processing (e.g., replacing
+ CR by CR NUL or by CR LF) MUST NOT be done. In particular,
+ there is no end-of-line convention (see Section 3.3.1) in
+ binary mode.
+
+ DISCUSSION:
+ The Binary option is normally negotiated in both
+ directions, to change the Telnet connection from NVT mode
+ to "binary mode".
+
+ The sequence IAC EOR can be used to delimit blocks of data
+ within a binary-mode Telnet stream.
+
+ 3.2.8 Telnet Terminal-Type Option: RFC-1091
+
+ The Terminal-Type option MUST use the terminal type names
+ officially defined in the Assigned Numbers RFC [INTRO:5], when
+ they are available for the particular terminal. However, the
+ receiver of a Terminal-Type option MUST accept any name.
+
+ DISCUSSION:
+ RFC-1091 [TELNET:10] updates an earlier version of the
+ Terminal-Type option defined in RFC-930. The earlier
+ version allowed a server host capable of supporting
+ multiple terminal types to learn the type of a particular
+ client's terminal, assuming that each physical terminal
+ had an intrinsic type. However, today a "terminal" is
+ often really a terminal emulator program running in a PC,
+ perhaps capable of emulating a range of terminal types.
+ Therefore, RFC-1091 extends the specification to allow a
+
+
+
+Internet Engineering Task Force [Page 20]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ more general terminal-type negotiation between User and
+ Server Telnets.
+
+ 3.3 SPECIFIC ISSUES
+
+ 3.3.1 Telnet End-of-Line Convention
+
+ The Telnet protocol defines the sequence CR LF to mean "end-
+ of-line". For terminal input, this corresponds to a command-
+ completion or "end-of-line" key being pressed on a user
+ terminal; on an ASCII terminal, this is the CR key, but it may
+ also be labelled "Return" or "Enter".
+
+ When a Server Telnet receives the Telnet end-of-line sequence
+ CR LF as input from a remote terminal, the effect MUST be the
+ same as if the user had pressed the "end-of-line" key on a
+ local terminal. On server hosts that use ASCII, in particular,
+ receipt of the Telnet sequence CR LF must cause the same effect
+ as a local user pressing the CR key on a local terminal. Thus,
+ CR LF and CR NUL MUST have the same effect on an ASCII server
+ host when received as input over a Telnet connection.
+
+ A User Telnet MUST be able to send any of the forms: CR LF, CR
+ NUL, and LF. A User Telnet on an ASCII host SHOULD have a
+ user-controllable mode to send either CR LF or CR NUL when the
+ user presses the "end-of-line" key, and CR LF SHOULD be the
+ default.
+
+ The Telnet end-of-line sequence CR LF MUST be used to send
+ Telnet data that is not terminal-to-computer (e.g., for Server
+ Telnet sending output, or the Telnet protocol incorporated
+ another application protocol).
+
+ DISCUSSION:
+ To allow interoperability between arbitrary Telnet clients
+ and servers, the Telnet protocol defined a standard
+ representation for a line terminator. Since the ASCII
+ character set includes no explicit end-of-line character,
+ systems have chosen various representations, e.g., CR, LF,
+ and the sequence CR LF. The Telnet protocol chose the CR
+ LF sequence as the standard for network transmission.
+
+ Unfortunately, the Telnet protocol specification in RFC-
+ 854 [TELNET:1] has turned out to be somewhat ambiguous on
+ what character(s) should be sent from client to server for
+ the "end-of-line" key. The result has been a massive and
+ continuing interoperability headache, made worse by
+ various faulty implementations of both User and Server
+
+
+
+Internet Engineering Task Force [Page 21]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ Telnets.
+
+ Although the Telnet protocol is based on a perfectly
+ symmetric model, in a remote login session the role of the
+ user at a terminal differs from the role of the server
+ host. For example, RFC-854 defines the meaning of CR, LF,
+ and CR LF as output from the server, but does not specify
+ what the User Telnet should send when the user presses the
+ "end-of-line" key on the terminal; this turns out to be
+ the point at issue.
+
+ When a user presses the "end-of-line" key, some User
+ Telnet implementations send CR LF, while others send CR
+ NUL (based on a different interpretation of the same
+ sentence in RFC-854). These will be equivalent for a
+ correctly-implemented ASCII server host, as discussed
+ above. For other servers, a mode in the User Telnet is
+ needed.
+
+ The existence of User Telnets that send only CR NUL when
+ CR is pressed creates a dilemma for non-ASCII hosts: they
+ can either treat CR NUL as equivalent to CR LF in input,
+ thus precluding the possibility of entering a "bare" CR,
+ or else lose complete interworking.
+
+ Suppose a user on host A uses Telnet to log into a server
+ host B, and then execute B's User Telnet program to log
+ into server host C. It is desirable for the Server/User
+ Telnet combination on B to be as transparent as possible,
+ i.e., to appear as if A were connected directly to C. In
+ particular, correct implementation will make B transparent
+ to Telnet end-of-line sequences, except that CR LF may be
+ translated to CR NUL or vice versa.
+
+ IMPLEMENTATION:
+ To understand Telnet end-of-line issues, one must have at
+ least a general model of the relationship of Telnet to the
+ local operating system. The Server Telnet process is
+ typically coupled into the terminal driver software of the
+ operating system as a pseudo-terminal. A Telnet end-of-
+ line sequence received by the Server Telnet must have the
+ same effect as pressing the end-of-line key on a real
+ locally-connected terminal.
+
+ Operating systems that support interactive character-at-
+ a-time applications (e.g., editors) typically have two
+ internal modes for their terminal I/O: a formatted mode,
+ in which local conventions for end-of-line and other
+
+
+
+Internet Engineering Task Force [Page 22]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ formatting rules have been applied to the data stream, and
+ a "raw" mode, in which the application has direct access
+ to every character as it was entered. A Server Telnet
+ must be implemented in such a way that these modes have
+ the same effect for remote as for local terminals. For
+ example, suppose a CR LF or CR NUL is received by the
+ Server Telnet on an ASCII host. In raw mode, a CR
+ character is passed to the application; in formatted mode,
+ the local system's end-of-line convention is used.
+
+ 3.3.2 Data Entry Terminals
+
+ DISCUSSION:
+ In addition to the line-oriented and character-oriented
+ ASCII terminals for which Telnet was designed, there are
+ several families of video display terminals that are
+ sometimes known as "data entry terminals" or DETs. The
+ IBM 3270 family is a well-known example.
+
+ Two Internet protocols have been designed to support
+ generic DETs: SUPDUP [TELNET:16, TELNET:17], and the DET
+ option [TELNET:18, TELNET:19]. The DET option drives a
+ data entry terminal over a Telnet connection using (sub-)
+ negotiation. SUPDUP is a completely separate terminal
+ protocol, which can be entered from Telnet by negotiation.
+ Although both SUPDUP and the DET option have been used
+ successfully in particular environments, neither has
+ gained general acceptance or wide implementation.
+
+ A different approach to DET interaction has been developed
+ for supporting the IBM 3270 family through Telnet,
+ although the same approach would be applicable to any DET.
+ The idea is to enter a "native DET" mode, in which the
+ native DET input/output stream is sent as binary data.
+ The Telnet EOR command is used to delimit logical records
+ (e.g., "screens") within this binary stream.
+
+ IMPLEMENTATION:
+ The rules for entering and leaving native DET mode are as
+ follows:
+
+ o The Server uses the Terminal-Type option [TELNET:10]
+ to learn that the client is a DET.
+
+ o It is conventional, but not required, that both ends
+ negotiate the EOR option [TELNET:9].
+
+ o Both ends negotiate the Binary option [TELNET:3] to
+
+
+
+Internet Engineering Task Force [Page 23]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ enter native DET mode.
+
+ o When either end negotiates out of binary mode, the
+ other end does too, and the mode then reverts to
+ normal NVT.
+
+
+ 3.3.3 Option Requirements
+
+ Every Telnet implementation MUST support the Binary option
+ [TELNET:3] and the Suppress Go Ahead option [TELNET:5], and
+ SHOULD support the Echo [TELNET:4], Status [TELNET:6], End-of-
+ Record [TELNET:9], and Extended Options List [TELNET:8]
+ options.
+
+ A User or Server Telnet SHOULD support the Window Size Option
+ [TELNET:12] if the local operating system provides the
+ corresponding capability.
+
+ DISCUSSION:
+ Note that the End-of-Record option only signifies that a
+ Telnet can receive a Telnet EOR without crashing;
+ therefore, every Telnet ought to be willing to accept
+ negotiation of the End-of-Record option. See also the
+ discussion in Section 3.2.3.
+
+ 3.3.4 Option Initiation
+
+ When the Telnet protocol is used in a client/server situation,
+ the server SHOULD initiate negotiation of the terminal
+ interaction mode it expects.
+
+ DISCUSSION:
+ The Telnet protocol was defined to be perfectly
+ symmetrical, but its application is generally asymmetric.
+ Remote login has been known to fail because NEITHER side
+ initiated negotiation of the required non-default terminal
+ modes. It is generally the server that determines the
+ preferred mode, so the server needs to initiate the
+ negotiation; since the negotiation is symmetric, the user
+ can also initiate it.
+
+ A client (User Telnet) SHOULD provide a means for users to
+ enable and disable the initiation of option negotiation.
+
+ DISCUSSION:
+ A user sometimes needs to connect to an application
+ service (e.g., FTP or SMTP) that uses Telnet for its
+
+
+
+Internet Engineering Task Force [Page 24]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ control stream but does not support Telnet options. User
+ Telnet may be used for this purpose if initiation of
+ option negotiation is disabled.
+
+ 3.3.5 Telnet Linemode Option
+
+ DISCUSSION:
+ An important new Telnet option, LINEMODE [TELNET:12], has
+ been proposed. The LINEMODE option provides a standard
+ way for a User Telnet and a Server Telnet to agree that
+ the client rather than the server will perform terminal
+ character processing. When the client has prepared a
+ complete line of text, it will send it to the server in
+ (usually) one TCP packet. This option will greatly
+ decrease the packet cost of Telnet sessions and will also
+ give much better user response over congested or long-
+ delay networks.
+
+ The LINEMODE option allows dynamic switching between local
+ and remote character processing. For example, the Telnet
+ connection will automatically negotiate into single-
+ character mode while a full screen editor is running, and
+ then return to linemode when the editor is finished.
+
+ We expect that when this RFC is released, hosts should
+ implement the client side of this option, and may
+ implement the server side of this option. To properly
+ implement the server side, the server needs to be able to
+ tell the local system not to do any input character
+ processing, but to remember its current terminal state and
+ notify the Server Telnet process whenever the state
+ changes. This will allow password echoing and full screen
+ editors to be handled properly, for example.
+
+ 3.4 TELNET/USER INTERFACE
+
+ 3.4.1 Character Set Transparency
+
+ User Telnet implementations SHOULD be able to send or receive
+ any 7-bit ASCII character. Where possible, any special
+ character interpretations by the user host's operating system
+ SHOULD be bypassed so that these characters can conveniently be
+ sent and received on the connection.
+
+ Some character value MUST be reserved as "escape to command
+ mode"; conventionally, doubling this character allows it to be
+ entered as data. The specific character used SHOULD be user
+ selectable.
+
+
+
+Internet Engineering Task Force [Page 25]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ On binary-mode connections, a User Telnet program MAY provide
+ an escape mechanism for entering arbitrary 8-bit values, if the
+ host operating system doesn't allow them to be entered directly
+ from the keyboard.
+
+ IMPLEMENTATION:
+ The transparency issues are less pressing on servers, but
+ implementors should take care in dealing with issues like:
+ masking off parity bits (sent by an older, non-conforming
+ client) before they reach programs that expect only NVT
+ ASCII, and properly handling programs that request 8-bit
+ data streams.
+
+ 3.4.2 Telnet Commands
+
+ A User Telnet program MUST provide a user the capability of
+ entering any of the Telnet control functions IP, AO, or AYT,
+ and SHOULD provide the capability of entering EC, EL, and
+ Break.
+
+ 3.4.3 TCP Connection Errors
+
+ A User Telnet program SHOULD report to the user any TCP errors
+ that are reported by the transport layer (see "TCP/Application
+ Layer Interface" section in [INTRO:1]).
+
+ 3.4.4 Non-Default Telnet Contact Port
+
+ A User Telnet program SHOULD allow the user to optionally
+ specify a non-standard contact port number at the Server Telnet
+ host.
+
+ 3.4.5 Flushing Output
+
+ A User Telnet program SHOULD provide the user the ability to
+ specify whether or not output should be flushed when an IP is
+ sent; see Section 3.2.4.
+
+ For any output flushing scheme that causes the User Telnet to
+ flush output locally until a Telnet signal is received from the
+ Server, there SHOULD be a way for the user to manually restore
+ normal output, in case the Server fails to send the expected
+ signal.
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 26]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ 3.5. TELNET REQUIREMENTS SUMMARY
+
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-------------------------------------------------|--------|-|-|-|-|-|--
+ | | | | | | |
+Option Negotiation |3.2.1 |x| | | | |
+ Avoid negotiation loops |3.2.1 |x| | | | |
+ Refuse unsupported options |3.2.1 |x| | | | |
+ Negotiation OK anytime on connection |3.2.1 | |x| | | |
+ Default to NVT |3.2.1 |x| | | | |
+ Send official name in Term-Type option |3.2.8 |x| | | | |
+ Accept any name in Term-Type option |3.2.8 |x| | | | |
+ Implement Binary, Suppress-GA options |3.3.3 |x| | | | |
+ Echo, Status, EOL, Ext-Opt-List options |3.3.3 | |x| | | |
+ Implement Window-Size option if appropriate |3.3.3 | |x| | | |
+ Server initiate mode negotiations |3.3.4 | |x| | | |
+ User can enable/disable init negotiations |3.3.4 | |x| | | |
+ | | | | | | |
+Go-Aheads | | | | | | |
+ Non-GA server negotiate SUPPRESS-GA option |3.2.2 |x| | | | |
+ User or Server accept SUPPRESS-GA option |3.2.2 |x| | | | |
+ User Telnet ignore GA's |3.2.2 | | |x| | |
+ | | | | | | |
+Control Functions | | | | | | |
+ Support SE NOP DM IP AO AYT SB |3.2.3 |x| | | | |
+ Support EOR EC EL Break |3.2.3 | | |x| | |
+ Ignore unsupported control functions |3.2.3 |x| | | | |
+ User, Server discard urgent data up to DM |3.2.4 |x| | | | |
+ User Telnet send "Synch" after IP, AO, AYT |3.2.4 | |x| | | |
+ Server Telnet reply Synch to IP |3.2.4 | | |x| | |
+ Server Telnet reply Synch to AO |3.2.4 |x| | | | |
+ User Telnet can flush output when send IP |3.2.4 | |x| | | |
+ | | | | | | |
+Encoding | | | | | | |
+ Send high-order bit in NVT mode |3.2.5 | | | |x| |
+ Send high-order bit as parity bit |3.2.5 | | | | |x|
+ Negot. BINARY if pass high-ord. bit to applic |3.2.5 | |x| | | |
+ Always double IAC data byte |3.2.6 |x| | | | |
+
+
+
+Internet Engineering Task Force [Page 27]
+
+
+
+
+RFC1123 REMOTE LOGIN -- TELNET October 1989
+
+
+ Double IAC data byte in binary mode |3.2.7 |x| | | | |
+ Obey Telnet cmds in binary mode |3.2.7 |x| | | | |
+ End-of-line, CR NUL in binary mode |3.2.7 | | | | |x|
+ | | | | | | |
+End-of-Line | | | | | | |
+ EOL at Server same as local end-of-line |3.3.1 |x| | | | |
+ ASCII Server accept CR LF or CR NUL for EOL |3.3.1 |x| | | | |
+ User Telnet able to send CR LF, CR NUL, or LF |3.3.1 |x| | | | |
+ ASCII user able to select CR LF/CR NUL |3.3.1 | |x| | | |
+ User Telnet default mode is CR LF |3.3.1 | |x| | | |
+ Non-interactive uses CR LF for EOL |3.3.1 |x| | | | |
+ | | | | | | |
+User Telnet interface | | | | | | |
+ Input & output all 7-bit characters |3.4.1 | |x| | | |
+ Bypass local op sys interpretation |3.4.1 | |x| | | |
+ Escape character |3.4.1 |x| | | | |
+ User-settable escape character |3.4.1 | |x| | | |
+ Escape to enter 8-bit values |3.4.1 | | |x| | |
+ Can input IP, AO, AYT |3.4.2 |x| | | | |
+ Can input EC, EL, Break |3.4.2 | |x| | | |
+ Report TCP connection errors to user |3.4.3 | |x| | | |
+ Optional non-default contact port |3.4.4 | |x| | | |
+ Can spec: output flushed when IP sent |3.4.5 | |x| | | |
+ Can manually restore output mode |3.4.5 | |x| | | |
+ | | | | | | |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 28]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+4. FILE TRANSFER
+
+ 4.1 FILE TRANSFER PROTOCOL -- FTP
+
+ 4.1.1 INTRODUCTION
+
+ The File Transfer Protocol FTP is the primary Internet standard
+ for file transfer. The current specification is contained in
+ RFC-959 [FTP:1].
+
+ FTP uses separate simultaneous TCP connections for control and
+ for data transfer. The FTP protocol includes many features,
+ some of which are not commonly implemented. However, for every
+ feature in FTP, there exists at least one implementation. The
+ minimum implementation defined in RFC-959 was too small, so a
+ somewhat larger minimum implementation is defined here.
+
+ Internet users have been unnecessarily burdened for years by
+ deficient FTP implementations. Protocol implementors have
+ suffered from the erroneous opinion that implementing FTP ought
+ to be a small and trivial task. This is wrong, because FTP has
+ a user interface, because it has to deal (correctly) with the
+ whole variety of communication and operating system errors that
+ may occur, and because it has to handle the great diversity of
+ real file systems in the world.
+
+ 4.1.2. PROTOCOL WALK-THROUGH
+
+ 4.1.2.1 LOCAL Type: RFC-959 Section 3.1.1.4
+
+ An FTP program MUST support TYPE I ("IMAGE" or binary type)
+ as well as TYPE L 8 ("LOCAL" type with logical byte size 8).
+ A machine whose memory is organized into m-bit words, where
+ m is not a multiple of 8, MAY also support TYPE L m.
+
+ DISCUSSION:
+ The command "TYPE L 8" is often required to transfer
+ binary data between a machine whose memory is organized
+ into (e.g.) 36-bit words and a machine with an 8-bit
+ byte organization. For an 8-bit byte machine, TYPE L 8
+ is equivalent to IMAGE.
+
+ "TYPE L m" is sometimes specified to the FTP programs
+ on two m-bit word machines to ensure the correct
+ transfer of a native-mode binary file from one machine
+ to the other. However, this command should have the
+ same effect on these machines as "TYPE I".
+
+
+
+
+Internet Engineering Task Force [Page 29]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ 4.1.2.2 Telnet Format Control: RFC-959 Section 3.1.1.5.2
+
+ A host that makes no distinction between TYPE N and TYPE T
+ SHOULD implement TYPE T to be identical to TYPE N.
+
+ DISCUSSION:
+ This provision should ease interoperation with hosts
+ that do make this distinction.
+
+ Many hosts represent text files internally as strings
+ of ASCII characters, using the embedded ASCII format
+ effector characters (LF, BS, FF, ...) to control the
+ format when a file is printed. For such hosts, there
+ is no distinction between "print" files and other
+ files. However, systems that use record structured
+ files typically need a special format for printable
+ files (e.g., ASA carriage control). For the latter
+ hosts, FTP allows a choice of TYPE N or TYPE T.
+
+ 4.1.2.3 Page Structure: RFC-959 Section 3.1.2.3 and Appendix I
+
+ Implementation of page structure is NOT RECOMMENDED in
+ general. However, if a host system does need to implement
+ FTP for "random access" or "holey" files, it MUST use the
+ defined page structure format rather than define a new
+ private FTP format.
+
+ 4.1.2.4 Data Structure Transformations: RFC-959 Section 3.1.2
+
+ An FTP transformation between record-structure and file-
+ structure SHOULD be invertible, to the extent possible while
+ making the result useful on the target host.
+
+ DISCUSSION:
+ RFC-959 required strict invertibility between record-
+ structure and file-structure, but in practice,
+ efficiency and convenience often preclude it.
+ Therefore, the requirement is being relaxed. There are
+ two different objectives for transferring a file:
+ processing it on the target host, or just storage. For
+ storage, strict invertibility is important. For
+ processing, the file created on the target host needs
+ to be in the format expected by application programs on
+ that host.
+
+ As an example of the conflict, imagine a record-
+ oriented operating system that requires some data files
+ to have exactly 80 bytes in each record. While STORing
+
+
+
+Internet Engineering Task Force [Page 30]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ a file on such a host, an FTP Server must be able to
+ pad each line or record to 80 bytes; a later retrieval
+ of such a file cannot be strictly invertible.
+
+ 4.1.2.5 Data Connection Management: RFC-959 Section 3.3
+
+ A User-FTP that uses STREAM mode SHOULD send a PORT command
+ to assign a non-default data port before each transfer
+ command is issued.
+
+ DISCUSSION:
+ This is required because of the long delay after a TCP
+ connection is closed until its socket pair can be
+ reused, to allow multiple transfers during a single FTP
+ session. Sending a port command can avoided if a
+ transfer mode other than stream is used, by leaving the
+ data transfer connection open between transfers.
+
+ 4.1.2.6 PASV Command: RFC-959 Section 4.1.2
+
+ A server-FTP MUST implement the PASV command.
+
+ If multiple third-party transfers are to be executed during
+ the same session, a new PASV command MUST be issued before
+ each transfer command, to obtain a unique port pair.
+
+ IMPLEMENTATION:
+ The format of the 227 reply to a PASV command is not
+ well standardized. In particular, an FTP client cannot
+ assume that the parentheses shown on page 40 of RFC-959
+ will be present (and in fact, Figure 3 on page 43 omits
+ them). Therefore, a User-FTP program that interprets
+ the PASV reply must scan the reply for the first digit
+ of the host and port numbers.
+
+ Note that the host number h1,h2,h3,h4 is the IP address
+ of the server host that is sending the reply, and that
+ p1,p2 is a non-default data transfer port that PASV has
+ assigned.
+
+ 4.1.2.7 LIST and NLST Commands: RFC-959 Section 4.1.3
+
+ The data returned by an NLST command MUST contain only a
+ simple list of legal pathnames, such that the server can use
+ them directly as the arguments of subsequent data transfer
+ commands for the individual files.
+
+ The data returned by a LIST or NLST command SHOULD use an
+
+
+
+Internet Engineering Task Force [Page 31]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ implied TYPE AN, unless the current type is EBCDIC, in which
+ case an implied TYPE EN SHOULD be used.
+
+ DISCUSSION:
+ Many FTP clients support macro-commands that will get
+ or put files matching a wildcard specification, using
+ NLST to obtain a list of pathnames. The expansion of
+ "multiple-put" is local to the client, but "multiple-
+ get" requires cooperation by the server.
+
+ The implied type for LIST and NLST is designed to
+ provide compatibility with existing User-FTPs, and in
+ particular with multiple-get commands.
+
+ 4.1.2.8 SITE Command: RFC-959 Section 4.1.3
+
+ A Server-FTP SHOULD use the SITE command for non-standard
+ features, rather than invent new private commands or
+ unstandardized extensions to existing commands.
+
+ 4.1.2.9 STOU Command: RFC-959 Section 4.1.3
+
+ The STOU command stores into a uniquely named file. When it
+ receives an STOU command, a Server-FTP MUST return the
+ actual file name in the "125 Transfer Starting" or the "150
+ Opening Data Connection" message that precedes the transfer
+ (the 250 reply code mentioned in RFC-959 is incorrect). The
+ exact format of these messages is hereby defined to be as
+ follows:
+
+ 125 FILE: pppp
+ 150 FILE: pppp
+
+ where pppp represents the unique pathname of the file that
+ will be written.
+
+ 4.1.2.10 Telnet End-of-line Code: RFC-959, Page 34
+
+ Implementors MUST NOT assume any correspondence between READ
+ boundaries on the control connection and the Telnet EOL
+ sequences (CR LF).
+
+ DISCUSSION:
+ Thus, a server-FTP (or User-FTP) must continue reading
+ characters from the control connection until a complete
+ Telnet EOL sequence is encountered, before processing
+ the command (or response, respectively). Conversely, a
+ single READ from the control connection may include
+
+
+
+Internet Engineering Task Force [Page 32]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ more than one FTP command.
+
+ 4.1.2.11 FTP Replies: RFC-959 Section 4.2, Page 35
+
+ A Server-FTP MUST send only correctly formatted replies on
+ the control connection. Note that RFC-959 (unlike earlier
+ versions of the FTP spec) contains no provision for a
+ "spontaneous" reply message.
+
+ A Server-FTP SHOULD use the reply codes defined in RFC-959
+ whenever they apply. However, a server-FTP MAY use a
+ different reply code when needed, as long as the general
+ rules of Section 4.2 are followed. When the implementor has
+ a choice between a 4xx and 5xx reply code, a Server-FTP
+ SHOULD send a 4xx (temporary failure) code when there is any
+ reasonable possibility that a failed FTP will succeed a few
+ hours later.
+
+ A User-FTP SHOULD generally use only the highest-order digit
+ of a 3-digit reply code for making a procedural decision, to
+ prevent difficulties when a Server-FTP uses non-standard
+ reply codes.
+
+ A User-FTP MUST be able to handle multi-line replies. If
+ the implementation imposes a limit on the number of lines
+ and if this limit is exceeded, the User-FTP MUST recover,
+ e.g., by ignoring the excess lines until the end of the
+ multi-line reply is reached.
+
+ A User-FTP SHOULD NOT interpret a 421 reply code ("Service
+ not available, closing control connection") specially, but
+ SHOULD detect closing of the control connection by the
+ server.
+
+ DISCUSSION:
+ Server implementations that fail to strictly follow the
+ reply rules often cause FTP user programs to hang.
+ Note that RFC-959 resolved ambiguities in the reply
+ rules found in earlier FTP specifications and must be
+ followed.
+
+ It is important to choose FTP reply codes that properly
+ distinguish between temporary and permanent failures,
+ to allow the successful use of file transfer client
+ daemons. These programs depend on the reply codes to
+ decide whether or not to retry a failed transfer; using
+ a permanent failure code (5xx) for a temporary error
+ will cause these programs to give up unnecessarily.
+
+
+
+Internet Engineering Task Force [Page 33]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ When the meaning of a reply matches exactly the text
+ shown in RFC-959, uniformity will be enhanced by using
+ the RFC-959 text verbatim. However, a Server-FTP
+ implementor is encouraged to choose reply text that
+ conveys specific system-dependent information, when
+ appropriate.
+
+ 4.1.2.12 Connections: RFC-959 Section 5.2
+
+ The words "and the port used" in the second paragraph of
+ this section of RFC-959 are erroneous (historical), and they
+ should be ignored.
+
+ On a multihomed server host, the default data transfer port
+ (L-1) MUST be associated with the same local IP address as
+ the corresponding control connection to port L.
+
+ A user-FTP MUST NOT send any Telnet controls other than
+ SYNCH and IP on an FTP control connection. In particular, it
+ MUST NOT attempt to negotiate Telnet options on the control
+ connection. However, a server-FTP MUST be capable of
+ accepting and refusing Telnet negotiations (i.e., sending
+ DONT/WONT).
+
+ DISCUSSION:
+ Although the RFC says: "Server- and User- processes
+ should follow the conventions for the Telnet
+ protocol...[on the control connection]", it is not the
+ intent that Telnet option negotiation is to be
+ employed.
+
+ 4.1.2.13 Minimum Implementation; RFC-959 Section 5.1
+
+ The following commands and options MUST be supported by
+ every server-FTP and user-FTP, except in cases where the
+ underlying file system or operating system does not allow or
+ support a particular command.
+
+ Type: ASCII Non-print, IMAGE, LOCAL 8
+ Mode: Stream
+ Structure: File, Record*
+ Commands:
+ USER, PASS, ACCT,
+ PORT, PASV,
+ TYPE, MODE, STRU,
+ RETR, STOR, APPE,
+ RNFR, RNTO, DELE,
+ CWD, CDUP, RMD, MKD, PWD,
+
+
+
+Internet Engineering Task Force [Page 34]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ LIST, NLST,
+ SYST, STAT,
+ HELP, NOOP, QUIT.
+
+ *Record structure is REQUIRED only for hosts whose file
+ systems support record structure.
+
+ DISCUSSION:
+ Vendors are encouraged to implement a larger subset of
+ the protocol. For example, there are important
+ robustness features in the protocol (e.g., Restart,
+ ABOR, block mode) that would be an aid to some Internet
+ users but are not widely implemented.
+
+ A host that does not have record structures in its file
+ system may still accept files with STRU R, recording
+ the byte stream literally.
+
+ 4.1.3 SPECIFIC ISSUES
+
+ 4.1.3.1 Non-standard Command Verbs
+
+ FTP allows "experimental" commands, whose names begin with
+ "X". If these commands are subsequently adopted as
+ standards, there may still be existing implementations using
+ the "X" form. At present, this is true for the directory
+ commands:
+
+ RFC-959 "Experimental"
+
+ MKD XMKD
+ RMD XRMD
+ PWD XPWD
+ CDUP XCUP
+ CWD XCWD
+
+ All FTP implementations SHOULD recognize both forms of these
+ commands, by simply equating them with extra entries in the
+ command lookup table.
+
+ IMPLEMENTATION:
+ A User-FTP can access a server that supports only the
+ "X" forms by implementing a mode switch, or
+ automatically using the following procedure: if the
+ RFC-959 form of one of the above commands is rejected
+ with a 500 or 502 response code, then try the
+ experimental form; any other response would be passed
+ to the user.
+
+
+
+Internet Engineering Task Force [Page 35]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ 4.1.3.2 Idle Timeout
+
+ A Server-FTP process SHOULD have an idle timeout, which will
+ terminate the process and close the control connection if
+ the server is inactive (i.e., no command or data transfer in
+ progress) for a long period of time. The idle timeout time
+ SHOULD be configurable, and the default should be at least 5
+ minutes.
+
+ A client FTP process ("User-PI" in RFC-959) will need
+ timeouts on responses only if it is invoked from a program.
+
+ DISCUSSION:
+ Without a timeout, a Server-FTP process may be left
+ pending indefinitely if the corresponding client
+ crashes without closing the control connection.
+
+ 4.1.3.3 Concurrency of Data and Control
+
+ DISCUSSION:
+ The intent of the designers of FTP was that a user
+ should be able to send a STAT command at any time while
+ data transfer was in progress and that the server-FTP
+ would reply immediately with status -- e.g., the number
+ of bytes transferred so far. Similarly, an ABOR
+ command should be possible at any time during a data
+ transfer.
+
+ Unfortunately, some small-machine operating systems
+ make such concurrent programming difficult, and some
+ other implementers seek minimal solutions, so some FTP
+ implementations do not allow concurrent use of the data
+ and control connections. Even such a minimal server
+ must be prepared to accept and defer a STAT or ABOR
+ command that arrives during data transfer.
+
+ 4.1.3.4 FTP Restart Mechanism
+
+ The description of the 110 reply on pp. 40-41 of RFC-959 is
+ incorrect; the correct description is as follows. A restart
+ reply message, sent over the control connection from the
+ receiving FTP to the User-FTP, has the format:
+
+ 110 MARK ssss = rrrr
+
+ Here:
+
+ * ssss is a text string that appeared in a Restart Marker
+
+
+
+Internet Engineering Task Force [Page 36]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ in the data stream and encodes a position in the
+ sender's file system;
+
+ * rrrr encodes the corresponding position in the
+ receiver's file system.
+
+ The encoding, which is specific to a particular file system
+ and network implementation, is always generated and
+ interpreted by the same system, either sender or receiver.
+
+ When an FTP that implements restart receives a Restart
+ Marker in the data stream, it SHOULD force the data to that
+ point to be written to stable storage before encoding the
+ corresponding position rrrr. An FTP sending Restart Markers
+ MUST NOT assume that 110 replies will be returned
+ synchronously with the data, i.e., it must not await a 110
+ reply before sending more data.
+
+ Two new reply codes are hereby defined for errors
+ encountered in restarting a transfer:
+
+ 554 Requested action not taken: invalid REST parameter.
+
+ A 554 reply may result from a FTP service command that
+ follows a REST command. The reply indicates that the
+ existing file at the Server-FTP cannot be repositioned
+ as specified in the REST.
+
+ 555 Requested action not taken: type or stru mismatch.
+
+ A 555 reply may result from an APPE command or from any
+ FTP service command following a REST command. The
+ reply indicates that there is some mismatch between the
+ current transfer parameters (type and stru) and the
+ attributes of the existing file.
+
+ DISCUSSION:
+ Note that the FTP Restart mechanism requires that Block
+ or Compressed mode be used for data transfer, to allow
+ the Restart Markers to be included within the data
+ stream. The frequency of Restart Markers can be low.
+
+ Restart Markers mark a place in the data stream, but
+ the receiver may be performing some transformation on
+ the data as it is stored into stable storage. In
+ general, the receiver's encoding must include any state
+ information necessary to restart this transformation at
+ any point of the FTP data stream. For example, in TYPE
+
+
+
+Internet Engineering Task Force [Page 37]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ A transfers, some receiver hosts transform CR LF
+ sequences into a single LF character on disk. If a
+ Restart Marker happens to fall between CR and LF, the
+ receiver must encode in rrrr that the transfer must be
+ restarted in a "CR has been seen and discarded" state.
+
+ Note that the Restart Marker is required to be encoded
+ as a string of printable ASCII characters, regardless
+ of the type of the data.
+
+ RFC-959 says that restart information is to be returned
+ "to the user". This should not be taken literally. In
+ general, the User-FTP should save the restart
+ information (ssss,rrrr) in stable storage, e.g., append
+ it to a restart control file. An empty restart control
+ file should be created when the transfer first starts
+ and deleted automatically when the transfer completes
+ successfully. It is suggested that this file have a
+ name derived in an easily-identifiable manner from the
+ name of the file being transferred and the remote host
+ name; this is analogous to the means used by many text
+ editors for naming "backup" files.
+
+ There are three cases for FTP restart.
+
+ (1) User-to-Server Transfer
+
+ The User-FTP puts Restart Markers <ssss> at
+ convenient places in the data stream. When the
+ Server-FTP receives a Marker, it writes all prior
+ data to disk, encodes its file system position and
+ transformation state as rrrr, and returns a "110
+ MARK ssss = rrrr" reply over the control
+ connection. The User-FTP appends the pair
+ (ssss,rrrr) to its restart control file.
+
+ To restart the transfer, the User-FTP fetches the
+ last (ssss,rrrr) pair from the restart control
+ file, repositions its local file system and
+ transformation state using ssss, and sends the
+ command "REST rrrr" to the Server-FTP.
+
+ (2) Server-to-User Transfer
+
+ The Server-FTP puts Restart Markers <ssss> at
+ convenient places in the data stream. When the
+ User-FTP receives a Marker, it writes all prior
+ data to disk, encodes its file system position and
+
+
+
+Internet Engineering Task Force [Page 38]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ transformation state as rrrr, and appends the pair
+ (rrrr,ssss) to its restart control file.
+
+ To restart the transfer, the User-FTP fetches the
+ last (rrrr,ssss) pair from the restart control
+ file, repositions its local file system and
+ transformation state using rrrr, and sends the
+ command "REST ssss" to the Server-FTP.
+
+ (3) Server-to-Server ("Third-Party") Transfer
+
+ The sending Server-FTP puts Restart Markers <ssss>
+ at convenient places in the data stream. When it
+ receives a Marker, the receiving Server-FTP writes
+ all prior data to disk, encodes its file system
+ position and transformation state as rrrr, and
+ sends a "110 MARK ssss = rrrr" reply over the
+ control connection to the User. The User-FTP
+ appends the pair (ssss,rrrr) to its restart
+ control file.
+
+ To restart the transfer, the User-FTP fetches the
+ last (ssss,rrrr) pair from the restart control
+ file, sends "REST ssss" to the sending Server-FTP,
+ and sends "REST rrrr" to the receiving Server-FTP.
+
+
+ 4.1.4 FTP/USER INTERFACE
+
+ This section discusses the user interface for a User-FTP
+ program.
+
+ 4.1.4.1 Pathname Specification
+
+ Since FTP is intended for use in a heterogeneous
+ environment, User-FTP implementations MUST support remote
+ pathnames as arbitrary character strings, so that their form
+ and content are not limited by the conventions of the local
+ operating system.
+
+ DISCUSSION:
+ In particular, remote pathnames can be of arbitrary
+ length, and all the printing ASCII characters as well
+ as space (0x20) must be allowed. RFC-959 allows a
+ pathname to contain any 7-bit ASCII character except CR
+ or LF.
+
+
+
+
+
+Internet Engineering Task Force [Page 39]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ 4.1.4.2 "QUOTE" Command
+
+ A User-FTP program MUST implement a "QUOTE" command that
+ will pass an arbitrary character string to the server and
+ display all resulting response messages to the user.
+
+ To make the "QUOTE" command useful, a User-FTP SHOULD send
+ transfer control commands to the server as the user enters
+ them, rather than saving all the commands and sending them
+ to the server only when a data transfer is started.
+
+ DISCUSSION:
+ The "QUOTE" command is essential to allow the user to
+ access servers that require system-specific commands
+ (e.g., SITE or ALLO), or to invoke new or optional
+ features that are not implemented by the User-FTP. For
+ example, "QUOTE" may be used to specify "TYPE A T" to
+ send a print file to hosts that require the
+ distinction, even if the User-FTP does not recognize
+ that TYPE.
+
+ 4.1.4.3 Displaying Replies to User
+
+ A User-FTP SHOULD display to the user the full text of all
+ error reply messages it receives. It SHOULD have a
+ "verbose" mode in which all commands it sends and the full
+ text and reply codes it receives are displayed, for
+ diagnosis of problems.
+
+ 4.1.4.4 Maintaining Synchronization
+
+ The state machine in a User-FTP SHOULD be forgiving of
+ missing and unexpected reply messages, in order to maintain
+ command synchronization with the server.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 40]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ 4.1.5 FTP REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-------------------------------------------|---------------|-|-|-|-|-|--
+Implement TYPE T if same as TYPE N |4.1.2.2 | |x| | | |
+File/Record transform invertible if poss. |4.1.2.4 | |x| | | |
+User-FTP send PORT cmd for stream mode |4.1.2.5 | |x| | | |
+Server-FTP implement PASV |4.1.2.6 |x| | | | |
+ PASV is per-transfer |4.1.2.6 |x| | | | |
+NLST reply usable in RETR cmds |4.1.2.7 |x| | | | |
+Implied type for LIST and NLST |4.1.2.7 | |x| | | |
+SITE cmd for non-standard features |4.1.2.8 | |x| | | |
+STOU cmd return pathname as specified |4.1.2.9 |x| | | | |
+Use TCP READ boundaries on control conn. |4.1.2.10 | | | | |x|
+ | | | | | | |
+Server-FTP send only correct reply format |4.1.2.11 |x| | | | |
+Server-FTP use defined reply code if poss. |4.1.2.11 | |x| | | |
+ New reply code following Section 4.2 |4.1.2.11 | | |x| | |
+User-FTP use only high digit of reply |4.1.2.11 | |x| | | |
+User-FTP handle multi-line reply lines |4.1.2.11 |x| | | | |
+User-FTP handle 421 reply specially |4.1.2.11 | | | |x| |
+ | | | | | | |
+Default data port same IP addr as ctl conn |4.1.2.12 |x| | | | |
+User-FTP send Telnet cmds exc. SYNCH, IP |4.1.2.12 | | | | |x|
+User-FTP negotiate Telnet options |4.1.2.12 | | | | |x|
+Server-FTP handle Telnet options |4.1.2.12 |x| | | | |
+Handle "Experimental" directory cmds |4.1.3.1 | |x| | | |
+Idle timeout in server-FTP |4.1.3.2 | |x| | | |
+ Configurable idle timeout |4.1.3.2 | |x| | | |
+Receiver checkpoint data at Restart Marker |4.1.3.4 | |x| | | |
+Sender assume 110 replies are synchronous |4.1.3.4 | | | | |x|
+ | | | | | | |
+Support TYPE: | | | | | | |
+ ASCII - Non-Print (AN) |4.1.2.13 |x| | | | |
+ ASCII - Telnet (AT) -- if same as AN |4.1.2.2 | |x| | | |
+ ASCII - Carriage Control (AC) |959 3.1.1.5.2 | | |x| | |
+ EBCDIC - (any form) |959 3.1.1.2 | | |x| | |
+ IMAGE |4.1.2.1 |x| | | | |
+ LOCAL 8 |4.1.2.1 |x| | | | |
+
+
+
+Internet Engineering Task Force [Page 41]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+ LOCAL m |4.1.2.1 | | |x| | |2
+ | | | | | | |
+Support MODE: | | | | | | |
+ Stream |4.1.2.13 |x| | | | |
+ Block |959 3.4.2 | | |x| | |
+ | | | | | | |
+Support STRUCTURE: | | | | | | |
+ File |4.1.2.13 |x| | | | |
+ Record |4.1.2.13 |x| | | | |3
+ Page |4.1.2.3 | | | |x| |
+ | | | | | | |
+Support commands: | | | | | | |
+ USER |4.1.2.13 |x| | | | |
+ PASS |4.1.2.13 |x| | | | |
+ ACCT |4.1.2.13 |x| | | | |
+ CWD |4.1.2.13 |x| | | | |
+ CDUP |4.1.2.13 |x| | | | |
+ SMNT |959 5.3.1 | | |x| | |
+ REIN |959 5.3.1 | | |x| | |
+ QUIT |4.1.2.13 |x| | | | |
+ | | | | | | |
+ PORT |4.1.2.13 |x| | | | |
+ PASV |4.1.2.6 |x| | | | |
+ TYPE |4.1.2.13 |x| | | | |1
+ STRU |4.1.2.13 |x| | | | |1
+ MODE |4.1.2.13 |x| | | | |1
+ | | | | | | |
+ RETR |4.1.2.13 |x| | | | |
+ STOR |4.1.2.13 |x| | | | |
+ STOU |959 5.3.1 | | |x| | |
+ APPE |4.1.2.13 |x| | | | |
+ ALLO |959 5.3.1 | | |x| | |
+ REST |959 5.3.1 | | |x| | |
+ RNFR |4.1.2.13 |x| | | | |
+ RNTO |4.1.2.13 |x| | | | |
+ ABOR |959 5.3.1 | | |x| | |
+ DELE |4.1.2.13 |x| | | | |
+ RMD |4.1.2.13 |x| | | | |
+ MKD |4.1.2.13 |x| | | | |
+ PWD |4.1.2.13 |x| | | | |
+ LIST |4.1.2.13 |x| | | | |
+ NLST |4.1.2.13 |x| | | | |
+ SITE |4.1.2.8 | | |x| | |
+ STAT |4.1.2.13 |x| | | | |
+ SYST |4.1.2.13 |x| | | | |
+ HELP |4.1.2.13 |x| | | | |
+ NOOP |4.1.2.13 |x| | | | |
+ | | | | | | |
+
+
+
+Internet Engineering Task Force [Page 42]
+
+
+
+
+RFC1123 FILE TRANSFER -- FTP October 1989
+
+
+User Interface: | | | | | | |
+ Arbitrary pathnames |4.1.4.1 |x| | | | |
+ Implement "QUOTE" command |4.1.4.2 |x| | | | |
+ Transfer control commands immediately |4.1.4.2 | |x| | | |
+ Display error messages to user |4.1.4.3 | |x| | | |
+ Verbose mode |4.1.4.3 | |x| | | |
+ Maintain synchronization with server |4.1.4.4 | |x| | | |
+
+Footnotes:
+
+(1) For the values shown earlier.
+
+(2) Here m is number of bits in a memory word.
+
+(3) Required for host with record-structured file system, optional
+ otherwise.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 43]
+
+
+
+
+RFC1123 FILE TRANSFER -- TFTP October 1989
+
+
+ 4.2 TRIVIAL FILE TRANSFER PROTOCOL -- TFTP
+
+ 4.2.1 INTRODUCTION
+
+ The Trivial File Transfer Protocol TFTP is defined in RFC-783
+ [TFTP:1].
+
+ TFTP provides its own reliable delivery with UDP as its
+ transport protocol, using a simple stop-and-wait acknowledgment
+ system. Since TFTP has an effective window of only one 512
+ octet segment, it can provide good performance only over paths
+ that have a small delay*bandwidth product. The TFTP file
+ interface is very simple, providing no access control or
+ security.
+
+ TFTP's most important application is bootstrapping a host over
+ a local network, since it is simple and small enough to be
+ easily implemented in EPROM [BOOT:1, BOOT:2]. Vendors are
+ urged to support TFTP for booting.
+
+ 4.2.2 PROTOCOL WALK-THROUGH
+
+ The TFTP specification [TFTP:1] is written in an open style,
+ and does not fully specify many parts of the protocol.
+
+ 4.2.2.1 Transfer Modes: RFC-783, Page 3
+
+ The transfer mode "mail" SHOULD NOT be supported.
+
+ 4.2.2.2 UDP Header: RFC-783, Page 17
+
+ The Length field of a UDP header is incorrectly defined; it
+ includes the UDP header length (8).
+
+ 4.2.3 SPECIFIC ISSUES
+
+ 4.2.3.1 Sorcerer's Apprentice Syndrome
+
+ There is a serious bug, known as the "Sorcerer's Apprentice
+ Syndrome," in the protocol specification. While it does not
+ cause incorrect operation of the transfer (the file will
+ always be transferred correctly if the transfer completes),
+ this bug may cause excessive retransmission, which may cause
+ the transfer to time out.
+
+ Implementations MUST contain the fix for this problem: the
+ sender (i.e., the side originating the DATA packets) must
+ never resend the current DATA packet on receipt of a
+
+
+
+Internet Engineering Task Force [Page 44]
+
+
+
+
+RFC1123 FILE TRANSFER -- TFTP October 1989
+
+
+ duplicate ACK.
+
+ DISCUSSION:
+ The bug is caused by the protocol rule that either
+ side, on receiving an old duplicate datagram, may
+ resend the current datagram. If a packet is delayed in
+ the network but later successfully delivered after
+ either side has timed out and retransmitted a packet, a
+ duplicate copy of the response may be generated. If
+ the other side responds to this duplicate with a
+ duplicate of its own, then every datagram will be sent
+ in duplicate for the remainder of the transfer (unless
+ a datagram is lost, breaking the repetition). Worse
+ yet, since the delay is often caused by congestion,
+ this duplicate transmission will usually causes more
+ congestion, leading to more delayed packets, etc.
+
+ The following example may help to clarify this problem.
+
+ TFTP A TFTP B
+
+ (1) Receive ACK X-1
+ Send DATA X
+ (2) Receive DATA X
+ Send ACK X
+ (ACK X is delayed in network,
+ and A times out):
+ (3) Retransmit DATA X
+
+ (4) Receive DATA X again
+ Send ACK X again
+ (5) Receive (delayed) ACK X
+ Send DATA X+1
+ (6) Receive DATA X+1
+ Send ACK X+1
+ (7) Receive ACK X again
+ Send DATA X+1 again
+ (8) Receive DATA X+1 again
+ Send ACK X+1 again
+ (9) Receive ACK X+1
+ Send DATA X+2
+ (10) Receive DATA X+2
+ Send ACK X+3
+ (11) Receive ACK X+1 again
+ Send DATA X+2 again
+ (12) Receive DATA X+2 again
+ Send ACK X+3 again
+
+
+
+
+Internet Engineering Task Force [Page 45]
+
+
+
+
+RFC1123 FILE TRANSFER -- TFTP October 1989
+
+
+ Notice that once the delayed ACK arrives, the protocol
+ settles down to duplicate all further packets
+ (sequences 5-8 and 9-12). The problem is caused not by
+ either side timing out, but by both sides
+ retransmitting the current packet when they receive a
+ duplicate.
+
+ The fix is to break the retransmission loop, as
+ indicated above. This is analogous to the behavior of
+ TCP. It is then possible to remove the retransmission
+ timer on the receiver, since the resent ACK will never
+ cause any action; this is a useful simplification where
+ TFTP is used in a bootstrap program. It is OK to allow
+ the timer to remain, and it may be helpful if the
+ retransmitted ACK replaces one that was genuinely lost
+ in the network. The sender still requires a retransmit
+ timer, of course.
+
+ 4.2.3.2 Timeout Algorithms
+
+ A TFTP implementation MUST use an adaptive timeout.
+
+ IMPLEMENTATION:
+ TCP retransmission algorithms provide a useful base to
+ work from. At least an exponential backoff of
+ retransmission timeout is necessary.
+
+ 4.2.3.3 Extensions
+
+ A variety of non-standard extensions have been made to TFTP,
+ including additional transfer modes and a secure operation
+ mode (with passwords). None of these have been
+ standardized.
+
+ 4.2.3.4 Access Control
+
+ A server TFTP implementation SHOULD include some
+ configurable access control over what pathnames are allowed
+ in TFTP operations.
+
+ 4.2.3.5 Broadcast Request
+
+ A TFTP request directed to a broadcast address SHOULD be
+ silently ignored.
+
+ DISCUSSION:
+ Due to the weak access control capability of TFTP,
+ directed broadcasts of TFTP requests to random networks
+
+
+
+Internet Engineering Task Force [Page 46]
+
+
+
+
+RFC1123 FILE TRANSFER -- TFTP October 1989
+
+
+ could create a significant security hole.
+
+ 4.2.4 TFTP REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-------------------------------------------------|--------|-|-|-|-|-|--
+Fix Sorcerer's Apprentice Syndrome |4.2.3.1 |x| | | | |
+Transfer modes: | | | | | | |
+ netascii |RFC-783 |x| | | | |
+ octet |RFC-783 |x| | | | |
+ mail |4.2.2.1 | | | |x| |
+ extensions |4.2.3.3 | | |x| | |
+Use adaptive timeout |4.2.3.2 |x| | | | |
+Configurable access control |4.2.3.4 | |x| | | |
+Silently ignore broadcast request |4.2.3.5 | |x| | | |
+-------------------------------------------------|--------|-|-|-|-|-|--
+-------------------------------------------------|--------|-|-|-|-|-|--
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 47]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+5. ELECTRONIC MAIL -- SMTP and RFC-822
+
+ 5.1 INTRODUCTION
+
+ In the TCP/IP protocol suite, electronic mail in a format
+ specified in RFC-822 [SMTP:2] is transmitted using the Simple Mail
+ Transfer Protocol (SMTP) defined in RFC-821 [SMTP:1].
+
+ While SMTP has remained unchanged over the years, the Internet
+ community has made several changes in the way SMTP is used. In
+ particular, the conversion to the Domain Name System (DNS) has
+ caused changes in address formats and in mail routing. In this
+ section, we assume familiarity with the concepts and terminology
+ of the DNS, whose requirements are given in Section 6.1.
+
+ RFC-822 specifies the Internet standard format for electronic mail
+ messages. RFC-822 supercedes an older standard, RFC-733, that may
+ still be in use in a few places, although it is obsolete. The two
+ formats are sometimes referred to simply by number ("822" and
+ "733").
+
+ RFC-822 is used in some non-Internet mail environments with
+ different mail transfer protocols than SMTP, and SMTP has also
+ been adapted for use in some non-Internet environments. Note that
+ this document presents the rules for the use of SMTP and RFC-822
+ for the Internet environment only; other mail environments that
+ use these protocols may be expected to have their own rules.
+
+ 5.2 PROTOCOL WALK-THROUGH
+
+ This section covers both RFC-821 and RFC-822.
+
+ The SMTP specification in RFC-821 is clear and contains numerous
+ examples, so implementors should not find it difficult to
+ understand. This section simply updates or annotates portions of
+ RFC-821 to conform with current usage.
+
+ RFC-822 is a long and dense document, defining a rich syntax.
+ Unfortunately, incomplete or defective implementations of RFC-822
+ are common. In fact, nearly all of the many formats of RFC-822
+ are actually used, so an implementation generally needs to
+ recognize and correctly interpret all of the RFC-822 syntax.
+
+ 5.2.1 The SMTP Model: RFC-821 Section 2
+
+ DISCUSSION:
+ Mail is sent by a series of request/response transactions
+ between a client, the "sender-SMTP," and a server, the
+
+
+
+Internet Engineering Task Force [Page 48]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ "receiver-SMTP". These transactions pass (1) the message
+ proper, which is composed of header and body, and (2) SMTP
+ source and destination addresses, referred to as the
+ "envelope".
+
+ The SMTP programs are analogous to Message Transfer Agents
+ (MTAs) of X.400. There will be another level of protocol
+ software, closer to the end user, that is responsible for
+ composing and analyzing RFC-822 message headers; this
+ component is known as the "User Agent" in X.400, and we
+ use that term in this document. There is a clear logical
+ distinction between the User Agent and the SMTP
+ implementation, since they operate on different levels of
+ protocol. Note, however, that this distinction is may not
+ be exactly reflected the structure of typical
+ implementations of Internet mail. Often there is a
+ program known as the "mailer" that implements SMTP and
+ also some of the User Agent functions; the rest of the
+ User Agent functions are included in a user interface used
+ for entering and reading mail.
+
+ The SMTP envelope is constructed at the originating site,
+ typically by the User Agent when the message is first
+ queued for the Sender-SMTP program. The envelope
+ addresses may be derived from information in the message
+ header, supplied by the user interface (e.g., to implement
+ a bcc: request), or derived from local configuration
+ information (e.g., expansion of a mailing list). The SMTP
+ envelope cannot in general be re-derived from the header
+ at a later stage in message delivery, so the envelope is
+ transmitted separately from the message itself using the
+ MAIL and RCPT commands of SMTP.
+
+ The text of RFC-821 suggests that mail is to be delivered
+ to an individual user at a host. With the advent of the
+ domain system and of mail routing using mail-exchange (MX)
+ resource records, implementors should now think of
+ delivering mail to a user at a domain, which may or may
+ not be a particular host. This DOES NOT change the fact
+ that SMTP is a host-to-host mail exchange protocol.
+
+ 5.2.2 Canonicalization: RFC-821 Section 3.1
+
+ The domain names that a Sender-SMTP sends in MAIL and RCPT
+ commands MUST have been "canonicalized," i.e., they must be
+ fully-qualified principal names or domain literals, not
+ nicknames or domain abbreviations. A canonicalized name either
+ identifies a host directly or is an MX name; it cannot be a
+
+
+
+Internet Engineering Task Force [Page 49]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ CNAME.
+
+ 5.2.3 VRFY and EXPN Commands: RFC-821 Section 3.3
+
+ A receiver-SMTP MUST implement VRFY and SHOULD implement EXPN
+ (this requirement overrides RFC-821). However, there MAY be
+ configuration information to disable VRFY and EXPN in a
+ particular installation; this might even allow EXPN to be
+ disabled for selected lists.
+
+ A new reply code is defined for the VRFY command:
+
+ 252 Cannot VRFY user (e.g., info is not local), but will
+ take message for this user and attempt delivery.
+
+ DISCUSSION:
+ SMTP users and administrators make regular use of these
+ commands for diagnosing mail delivery problems. With the
+ increasing use of multi-level mailing list expansion
+ (sometimes more than two levels), EXPN has been
+ increasingly important for diagnosing inadvertent mail
+ loops. On the other hand, some feel that EXPN represents
+ a significant privacy, and perhaps even a security,
+ exposure.
+
+ 5.2.4 SEND, SOML, and SAML Commands: RFC-821 Section 3.4
+
+ An SMTP MAY implement the commands to send a message to a
+ user's terminal: SEND, SOML, and SAML.
+
+ DISCUSSION:
+ It has been suggested that the use of mail relaying
+ through an MX record is inconsistent with the intent of
+ SEND to deliver a message immediately and directly to a
+ user's terminal. However, an SMTP receiver that is unable
+ to write directly to the user terminal can return a "251
+ User Not Local" reply to the RCPT following a SEND, to
+ inform the originator of possibly deferred delivery.
+
+ 5.2.5 HELO Command: RFC-821 Section 3.5
+
+ The sender-SMTP MUST ensure that the <domain> parameter in a
+ HELO command is a valid principal host domain name for the
+ client host. As a result, the receiver-SMTP will not have to
+ perform MX resolution on this name in order to validate the
+ HELO parameter.
+
+ The HELO receiver MAY verify that the HELO parameter really
+
+
+
+Internet Engineering Task Force [Page 50]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ corresponds to the IP address of the sender. However, the
+ receiver MUST NOT refuse to accept a message, even if the
+ sender's HELO command fails verification.
+
+ DISCUSSION:
+ Verifying the HELO parameter requires a domain name lookup
+ and may therefore take considerable time. An alternative
+ tool for tracking bogus mail sources is suggested below
+ (see "DATA Command").
+
+ Note also that the HELO argument is still required to have
+ valid <domain> syntax, since it will appear in a Received:
+ line; otherwise, a 501 error is to be sent.
+
+ IMPLEMENTATION:
+ When HELO parameter validation fails, a suggested
+ procedure is to insert a note about the unknown
+ authenticity of the sender into the message header (e.g.,
+ in the "Received:" line).
+
+ 5.2.6 Mail Relay: RFC-821 Section 3.6
+
+ We distinguish three types of mail (store-and-) forwarding:
+
+ (1) A simple forwarder or "mail exchanger" forwards a message
+ using private knowledge about the recipient; see section
+ 3.2 of RFC-821.
+
+ (2) An SMTP mail "relay" forwards a message within an SMTP
+ mail environment as the result of an explicit source route
+ (as defined in section 3.6 of RFC-821). The SMTP relay
+ function uses the "@...:" form of source route from RFC-
+ 822 (see Section 5.2.19 below).
+
+ (3) A mail "gateway" passes a message between different
+ environments. The rules for mail gateways are discussed
+ below in Section 5.3.7.
+
+ An Internet host that is forwarding a message but is not a
+ gateway to a different mail environment (i.e., it falls under
+ (1) or (2)) SHOULD NOT alter any existing header fields,
+ although the host will add an appropriate Received: line as
+ required in Section 5.2.8.
+
+ A Sender-SMTP SHOULD NOT send a RCPT TO: command containing an
+ explicit source route using the "@...:" address form. Thus,
+ the relay function defined in section 3.6 of RFC-821 should
+ not be used.
+
+
+
+Internet Engineering Task Force [Page 51]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ DISCUSSION:
+ The intent is to discourage all source routing and to
+ abolish explicit source routing for mail delivery within
+ the Internet environment. Source-routing is unnecessary;
+ the simple target address "user@domain" should always
+ suffice. This is the result of an explicit architectural
+ decision to use universal naming rather than source
+ routing for mail. Thus, SMTP provides end-to-end
+ connectivity, and the DNS provides globally-unique,
+ location-independent names. MX records handle the major
+ case where source routing might otherwise be needed.
+
+ A receiver-SMTP MUST accept the explicit source route syntax in
+ the envelope, but it MAY implement the relay function as
+ defined in section 3.6 of RFC-821. If it does not implement
+ the relay function, it SHOULD attempt to deliver the message
+ directly to the host to the right of the right-most "@" sign.
+
+ DISCUSSION:
+ For example, suppose a host that does not implement the
+ relay function receives a message with the SMTP command:
+ "RCPT TO:<@ALPHA,@BETA:joe@GAMMA>", where ALPHA, BETA, and
+ GAMMA represent domain names. Rather than immediately
+ refusing the message with a 550 error reply as suggested
+ on page 20 of RFC-821, the host should try to forward the
+ message to GAMMA directly, using: "RCPT TO:<joe@GAMMA>".
+ Since this host does not support relaying, it is not
+ required to update the reverse path.
+
+ Some have suggested that source routing may be needed
+ occasionally for manually routing mail around failures;
+ however, the reality and importance of this need is
+ controversial. The use of explicit SMTP mail relaying for
+ this purpose is discouraged, and in fact it may not be
+ successful, as many host systems do not support it. Some
+ have used the "%-hack" (see Section 5.2.16) for this
+ purpose.
+
+ 5.2.7 RCPT Command: RFC-821 Section 4.1.1
+
+ A host that supports a receiver-SMTP MUST support the reserved
+ mailbox "Postmaster".
+
+ The receiver-SMTP MAY verify RCPT parameters as they arrive;
+ however, RCPT responses MUST NOT be delayed beyond a reasonable
+ time (see Section 5.3.2).
+
+ Therefore, a "250 OK" response to a RCPT does not necessarily
+
+
+
+Internet Engineering Task Force [Page 52]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ imply that the delivery address(es) are valid. Errors found
+ after message acceptance will be reported by mailing a
+ notification message to an appropriate address (see Section
+ 5.3.3).
+
+ DISCUSSION:
+ The set of conditions under which a RCPT parameter can be
+ validated immediately is an engineering design choice.
+ Reporting destination mailbox errors to the Sender-SMTP
+ before mail is transferred is generally desirable to save
+ time and network bandwidth, but this advantage is lost if
+ RCPT verification is lengthy.
+
+ For example, the receiver can verify immediately any
+ simple local reference, such as a single locally-
+ registered mailbox. On the other hand, the "reasonable
+ time" limitation generally implies deferring verification
+ of a mailing list until after the message has been
+ transferred and accepted, since verifying a large mailing
+ list can take a very long time. An implementation might
+ or might not choose to defer validation of addresses that
+ are non-local and therefore require a DNS lookup. If a
+ DNS lookup is performed but a soft domain system error
+ (e.g., timeout) occurs, validity must be assumed.
+
+ 5.2.8 DATA Command: RFC-821 Section 4.1.1
+
+ Every receiver-SMTP (not just one that "accepts a message for
+ relaying or for final delivery" [SMTP:1]) MUST insert a
+ "Received:" line at the beginning of a message. In this line,
+ called a "time stamp line" in RFC-821:
+
+ * The FROM field SHOULD contain both (1) the name of the
+ source host as presented in the HELO command and (2) a
+ domain literal containing the IP address of the source,
+ determined from the TCP connection.
+
+ * The ID field MAY contain an "@" as suggested in RFC-822,
+ but this is not required.
+
+ * The FOR field MAY contain a list of <path> entries when
+ multiple RCPT commands have been given.
+
+
+ An Internet mail program MUST NOT change a Received: line that
+ was previously added to the message header.
+
+
+
+
+
+Internet Engineering Task Force [Page 53]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ DISCUSSION:
+ Including both the source host and the IP source address
+ in the Received: line may provide enough information for
+ tracking illicit mail sources and eliminate a need to
+ explicitly verify the HELO parameter.
+
+ Received: lines are primarily intended for humans tracing
+ mail routes, primarily of diagnosis of faults. See also
+ the discussion under 5.3.7.
+
+ When the receiver-SMTP makes "final delivery" of a message,
+ then it MUST pass the MAIL FROM: address from the SMTP envelope
+ with the message, for use if an error notification message must
+ be sent later (see Section 5.3.3). There is an analogous
+ requirement when gatewaying from the Internet into a different
+ mail environment; see Section 5.3.7.
+
+ DISCUSSION:
+ Note that the final reply to the DATA command depends only
+ upon the successful transfer and storage of the message.
+ Any problem with the destination address(es) must either
+ (1) have been reported in an SMTP error reply to the RCPT
+ command(s), or (2) be reported in a later error message
+ mailed to the originator.
+
+ IMPLEMENTATION:
+ The MAIL FROM: information may be passed as a parameter or
+ in a Return-Path: line inserted at the beginning of the
+ message.
+
+ 5.2.9 Command Syntax: RFC-821 Section 4.1.2
+
+ The syntax shown in RFC-821 for the MAIL FROM: command omits
+ the case of an empty path: "MAIL FROM: <>" (see RFC-821 Page
+ 15). An empty reverse path MUST be supported.
+
+ 5.2.10 SMTP Replies: RFC-821 Section 4.2
+
+ A receiver-SMTP SHOULD send only the reply codes listed in
+ section 4.2.2 of RFC-821 or in this document. A receiver-SMTP
+ SHOULD use the text shown in examples in RFC-821 whenever
+ appropriate.
+
+ A sender-SMTP MUST determine its actions only by the reply
+ code, not by the text (except for 251 and 551 replies); any
+ text, including no text at all, must be acceptable. The space
+ (blank) following the reply code is considered part of the
+ text. Whenever possible, a sender-SMTP SHOULD test only the
+
+
+
+Internet Engineering Task Force [Page 54]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ first digit of the reply code, as specified in Appendix E of
+ RFC-821.
+
+ DISCUSSION:
+ Interoperability problems have arisen with SMTP systems
+ using reply codes that are not listed explicitly in RFC-
+ 821 Section 4.3 but are legal according to the theory of
+ reply codes explained in Appendix E.
+
+ 5.2.11 Transparency: RFC-821 Section 4.5.2
+
+ Implementors MUST be sure that their mail systems always add
+ and delete periods to ensure message transparency.
+
+ 5.2.12 WKS Use in MX Processing: RFC-974, p. 5
+
+ RFC-974 [SMTP:3] recommended that the domain system be queried
+ for WKS ("Well-Known Service") records, to verify that each
+ proposed mail target does support SMTP. Later experience has
+ shown that WKS is not widely supported, so the WKS step in MX
+ processing SHOULD NOT be used.
+
+ The following are notes on RFC-822, organized by section of that
+ document.
+
+ 5.2.13 RFC-822 Message Specification: RFC-822 Section 4
+
+ The syntax shown for the Return-path line omits the possibility
+ of a null return path, which is used to prevent looping of
+ error notifications (see Section 5.3.3). The complete syntax
+ is:
+
+ return = "Return-path" ":" route-addr
+ / "Return-path" ":" "<" ">"
+
+ The set of optional header fields is hereby expanded to include
+ the Content-Type field defined in RFC-1049 [SMTP:7]. This
+ field "allows mail reading systems to automatically identify
+ the type of a structured message body and to process it for
+ display accordingly". [SMTP:7] A User Agent MAY support this
+ field.
+
+ 5.2.14 RFC-822 Date and Time Specification: RFC-822 Section 5
+
+ The syntax for the date is hereby changed to:
+
+ date = 1*2DIGIT month 2*4DIGIT
+
+
+
+
+Internet Engineering Task Force [Page 55]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ All mail software SHOULD use 4-digit years in dates, to ease
+ the transition to the next century.
+
+ There is a strong trend towards the use of numeric timezone
+ indicators, and implementations SHOULD use numeric timezones
+ instead of timezone names. However, all implementations MUST
+ accept either notation. If timezone names are used, they MUST
+ be exactly as defined in RFC-822.
+
+ The military time zones are specified incorrectly in RFC-822:
+ they count the wrong way from UT (the signs are reversed). As
+ a result, military time zones in RFC-822 headers carry no
+ information.
+
+ Finally, note that there is a typo in the definition of "zone"
+ in the syntax summary of appendix D; the correct definition
+ occurs in Section 3 of RFC-822.
+
+ 5.2.15 RFC-822 Syntax Change: RFC-822 Section 6.1
+
+ The syntactic definition of "mailbox" in RFC-822 is hereby
+ changed to:
+
+ mailbox = addr-spec ; simple address
+ / [phrase] route-addr ; name & addr-spec
+
+ That is, the phrase preceding a route address is now OPTIONAL.
+ This change makes the following header field legal, for
+ example:
+
+
+ 5.2.16 RFC-822 Local-part: RFC-822 Section 6.2
+
+ The basic mailbox address specification has the form: "local-
+ part@domain". Here "local-part", sometimes called the "left-
+ hand side" of the address, is domain-dependent.
+
+ A host that is forwarding the message but is not the
+ destination host implied by the right-hand side "domain" MUST
+ NOT interpret or modify the "local-part" of the address.
+
+ When mail is to be gatewayed from the Internet mail environment
+ into a foreign mail environment (see Section 5.3.7), routing
+ information for that foreign environment MAY be embedded within
+ the "local-part" of the address. The gateway will then
+ interpret this local part appropriately for the foreign mail
+ environment.
+
+
+
+Internet Engineering Task Force [Page 56]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ DISCUSSION:
+ Although source routes are discouraged within the Internet
+ (see Section 5.2.6), there are non-Internet mail
+ environments whose delivery mechanisms do depend upon
+ source routes. Source routes for extra-Internet
+ environments can generally be buried in the "local-part"
+ of the address (see Section 5.2.16) while mail traverses
+ the Internet. When the mail reaches the appropriate
+ Internet mail gateway, the gateway will interpret the
+ local-part and build the necessary address or route for
+ the target mail environment.
+
+ For example, an Internet host might send mail to:
+ "a!b!c!user@gateway-domain". The complex local part
+ "a!b!c!user" would be uninterpreted within the Internet
+ domain, but could be parsed and understood by the
+ specified mail gateway.
+
+ An embedded source route is sometimes encoded in the
+ "local-part" using "%" as a right-binding routing
+ operator. For example, in:
+
+ user%domain%relay3%relay2@relay1
+
+ the "%" convention implies that the mail is to be routed
+ from "relay1" through "relay2", "relay3", and finally to
+ "user" at "domain". This is commonly known as the "%-
+ hack". It is suggested that "%" have lower precedence
+ than any other routing operator (e.g., "!") hidden in the
+ local-part; for example, "a!b%c" would be interpreted as
+ "(a!b)%c".
+
+ Only the target host (in this case, "relay1") is permitted
+ to analyze the local-part "user%domain%relay3%relay2".
+
+ 5.2.17 Domain Literals: RFC-822 Section 6.2.3
+
+ A mailer MUST be able to accept and parse an Internet domain
+ literal whose content ("dtext"; see RFC-822) is a dotted-
+ decimal host address. This satisfies the requirement of
+ Section 2.1 for the case of mail.
+
+ An SMTP MUST accept and recognize a domain literal for any of
+ its own IP addresses.
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 57]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ 5.2.18 Common Address Formatting Errors: RFC-822 Section 6.1
+
+ Errors in formatting or parsing 822 addresses are unfortunately
+ common. This section mentions only the most common errors. A
+ User Agent MUST accept all valid RFC-822 address formats, and
+ MUST NOT generate illegal address syntax.
+
+ o A common error is to leave out the semicolon after a group
+ identifier.
+
+ o Some systems fail to fully-qualify domain names in
+ messages they generate. The right-hand side of an "@"
+ sign in a header address field MUST be a fully-qualified
+ domain name.
+
+ For example, some systems fail to fully-qualify the From:
+ address; this prevents a "reply" command in the user
+ interface from automatically constructing a return
+ address.
+
+ DISCUSSION:
+ Although RFC-822 allows the local use of abbreviated
+ domain names within a domain, the application of
+ RFC-822 in Internet mail does not allow this. The
+ intent is that an Internet host must not send an SMTP
+ message header containing an abbreviated domain name
+ in an address field. This allows the address fields
+ of the header to be passed without alteration across
+ the Internet, as required in Section 5.2.6.
+
+ o Some systems mis-parse multiple-hop explicit source routes
+ such as:
+
+ @relay1,@relay2,@relay3:user@domain.
+
+
+ o Some systems over-qualify domain names by adding a
+ trailing dot to some or all domain names in addresses or
+ message-ids. This violates RFC-822 syntax.
+
+
+ 5.2.19 Explicit Source Routes: RFC-822 Section 6.2.7
+
+ Internet host software SHOULD NOT create an RFC-822 header
+ containing an address with an explicit source route, but MUST
+ accept such headers for compatibility with earlier systems.
+
+ DISCUSSION:
+
+
+
+Internet Engineering Task Force [Page 58]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ In an understatement, RFC-822 says "The use of explicit
+ source routing is discouraged". Many hosts implemented
+ RFC-822 source routes incorrectly, so the syntax cannot be
+ used unambiguously in practice. Many users feel the
+ syntax is ugly. Explicit source routes are not needed in
+ the mail envelope for delivery; see Section 5.2.6. For
+ all these reasons, explicit source routes using the RFC-
+ 822 notations are not to be used in Internet mail headers.
+
+ As stated in Section 5.2.16, it is necessary to allow an
+ explicit source route to be buried in the local-part of an
+ address, e.g., using the "%-hack", in order to allow mail
+ to be gatewayed into another environment in which explicit
+ source routing is necessary. The vigilant will observe
+ that there is no way for a User Agent to detect and
+ prevent the use of such implicit source routing when the
+ destination is within the Internet. We can only
+ discourage source routing of any kind within the Internet,
+ as unnecessary and undesirable.
+
+ 5.3 SPECIFIC ISSUES
+
+ 5.3.1 SMTP Queueing Strategies
+
+ The common structure of a host SMTP implementation includes
+ user mailboxes, one or more areas for queueing messages in
+ transit, and one or more daemon processes for sending and
+ receiving mail. The exact structure will vary depending on the
+ needs of the users on the host and the number and size of
+ mailing lists supported by the host. We describe several
+ optimizations that have proved helpful, particularly for
+ mailers supporting high traffic levels.
+
+ Any queueing strategy MUST include:
+
+ o Timeouts on all activities. See Section 5.3.2.
+
+ o Never sending error messages in response to error
+ messages.
+
+
+ 5.3.1.1 Sending Strategy
+
+ The general model of a sender-SMTP is one or more processes
+ that periodically attempt to transmit outgoing mail. In a
+ typical system, the program that composes a message has some
+ method for requesting immediate attention for a new piece of
+ outgoing mail, while mail that cannot be transmitted
+
+
+
+Internet Engineering Task Force [Page 59]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ immediately MUST be queued and periodically retried by the
+ sender. A mail queue entry will include not only the
+ message itself but also the envelope information.
+
+ The sender MUST delay retrying a particular destination
+ after one attempt has failed. In general, the retry
+ interval SHOULD be at least 30 minutes; however, more
+ sophisticated and variable strategies will be beneficial
+ when the sender-SMTP can determine the reason for non-
+ delivery.
+
+ Retries continue until the message is transmitted or the
+ sender gives up; the give-up time generally needs to be at
+ least 4-5 days. The parameters to the retry algorithm MUST
+ be configurable.
+
+ A sender SHOULD keep a list of hosts it cannot reach and
+ corresponding timeouts, rather than just retrying queued
+ mail items.
+
+ DISCUSSION:
+ Experience suggests that failures are typically
+ transient (the target system has crashed), favoring a
+ policy of two connection attempts in the first hour the
+ message is in the queue, and then backing off to once
+ every two or three hours.
+
+ The sender-SMTP can shorten the queueing delay by
+ cooperation with the receiver-SMTP. In particular, if
+ mail is received from a particular address, it is good
+ evidence that any mail queued for that host can now be
+ sent.
+
+ The strategy may be further modified as a result of
+ multiple addresses per host (see Section 5.3.4), to
+ optimize delivery time vs. resource usage.
+
+ A sender-SMTP may have a large queue of messages for
+ each unavailable destination host, and if it retried
+ all these messages in every retry cycle, there would be
+ excessive Internet overhead and the daemon would be
+ blocked for a long period. Note that an SMTP can
+ generally determine that a delivery attempt has failed
+ only after a timeout of a minute or more; a one minute
+ timeout per connection will result in a very large
+ delay if it is repeated for dozens or even hundreds of
+ queued messages.
+
+
+
+
+Internet Engineering Task Force [Page 60]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ When the same message is to be delivered to several users on
+ the same host, only one copy of the message SHOULD be
+ transmitted. That is, the sender-SMTP should use the
+ command sequence: RCPT, RCPT,... RCPT, DATA instead of the
+ sequence: RCPT, DATA, RCPT, DATA,... RCPT, DATA.
+ Implementation of this efficiency feature is strongly urged.
+
+ Similarly, the sender-SMTP MAY support multiple concurrent
+ outgoing mail transactions to achieve timely delivery.
+ However, some limit SHOULD be imposed to protect the host
+ from devoting all its resources to mail.
+
+ The use of the different addresses of a multihomed host is
+ discussed below.
+
+ 5.3.1.2 Receiving strategy
+
+ The receiver-SMTP SHOULD attempt to keep a pending listen on
+ the SMTP port at all times. This will require the support
+ of multiple incoming TCP connections for SMTP. Some limit
+ MAY be imposed.
+
+ IMPLEMENTATION:
+ When the receiver-SMTP receives mail from a particular
+ host address, it could notify the sender-SMTP to retry
+ any mail pending for that host address.
+
+ 5.3.2 Timeouts in SMTP
+
+ There are two approaches to timeouts in the sender-SMTP: (a)
+ limit the time for each SMTP command separately, or (b) limit
+ the time for the entire SMTP dialogue for a single mail
+ message. A sender-SMTP SHOULD use option (a), per-command
+ timeouts. Timeouts SHOULD be easily reconfigurable, preferably
+ without recompiling the SMTP code.
+
+ DISCUSSION:
+ Timeouts are an essential feature of an SMTP
+ implementation. If the timeouts are too long (or worse,
+ there are no timeouts), Internet communication failures or
+ software bugs in receiver-SMTP programs can tie up SMTP
+ processes indefinitely. If the timeouts are too short,
+ resources will be wasted with attempts that time out part
+ way through message delivery.
+
+ If option (b) is used, the timeout has to be very large,
+ e.g., an hour, to allow time to expand very large mailing
+ lists. The timeout may also need to increase linearly
+
+
+
+Internet Engineering Task Force [Page 61]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ with the size of the message, to account for the time to
+ transmit a very large message. A large fixed timeout
+ leads to two problems: a failure can still tie up the
+ sender for a very long time, and very large messages may
+ still spuriously time out (which is a wasteful failure!).
+
+ Using the recommended option (a), a timer is set for each
+ SMTP command and for each buffer of the data transfer.
+ The latter means that the overall timeout is inherently
+ proportional to the size of the message.
+
+ Based on extensive experience with busy mail-relay hosts, the
+ minimum per-command timeout values SHOULD be as follows:
+
+ o Initial 220 Message: 5 minutes
+
+ A Sender-SMTP process needs to distinguish between a
+ failed TCP connection and a delay in receiving the initial
+ 220 greeting message. Many receiver-SMTPs will accept a
+ TCP connection but delay delivery of the 220 message until
+ their system load will permit more mail to be processed.
+
+ o MAIL Command: 5 minutes
+
+
+ o RCPT Command: 5 minutes
+
+ A longer timeout would be required if processing of
+ mailing lists and aliases were not deferred until after
+ the message was accepted.
+
+ o DATA Initiation: 2 minutes
+
+ This is while awaiting the "354 Start Input" reply to a
+ DATA command.
+
+ o Data Block: 3 minutes
+
+ This is while awaiting the completion of each TCP SEND
+ call transmitting a chunk of data.
+
+ o DATA Termination: 10 minutes.
+
+ This is while awaiting the "250 OK" reply. When the
+ receiver gets the final period terminating the message
+ data, it typically performs processing to deliver the
+ message to a user mailbox. A spurious timeout at this
+ point would be very wasteful, since the message has been
+
+
+
+Internet Engineering Task Force [Page 62]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ successfully sent.
+
+ A receiver-SMTP SHOULD have a timeout of at least 5 minutes
+ while it is awaiting the next command from the sender.
+
+ 5.3.3 Reliable Mail Receipt
+
+ When the receiver-SMTP accepts a piece of mail (by sending a
+ "250 OK" message in response to DATA), it is accepting
+ responsibility for delivering or relaying the message. It must
+ take this responsibility seriously, i.e., it MUST NOT lose the
+ message for frivolous reasons, e.g., because the host later
+ crashes or because of a predictable resource shortage.
+
+ If there is a delivery failure after acceptance of a message,
+ the receiver-SMTP MUST formulate and mail a notification
+ message. This notification MUST be sent using a null ("<>")
+ reverse path in the envelope; see Section 3.6 of RFC-821. The
+ recipient of this notification SHOULD be the address from the
+ envelope return path (or the Return-Path: line). However, if
+ this address is null ("<>"), the receiver-SMTP MUST NOT send a
+ notification. If the address is an explicit source route, it
+ SHOULD be stripped down to its final hop.
+
+ DISCUSSION:
+ For example, suppose that an error notification must be
+ sent for a message that arrived with:
+ "MAIL FROM:<@a,@b:user@d>". The notification message
+ should be sent to: "RCPT TO:<user@d>".
+
+ Some delivery failures after the message is accepted by
+ SMTP will be unavoidable. For example, it may be
+ impossible for the receiver-SMTP to validate all the
+ delivery addresses in RCPT command(s) due to a "soft"
+ domain system error or because the target is a mailing
+ list (see earlier discussion of RCPT).
+
+ To avoid receiving duplicate messages as the result of
+ timeouts, a receiver-SMTP MUST seek to minimize the time
+ required to respond to the final "." that ends a message
+ transfer. See RFC-1047 [SMTP:4] for a discussion of this
+ problem.
+
+ 5.3.4 Reliable Mail Transmission
+
+ To transmit a message, a sender-SMTP determines the IP address
+ of the target host from the destination address in the
+ envelope. Specifically, it maps the string to the right of the
+
+
+
+Internet Engineering Task Force [Page 63]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ "@" sign into an IP address. This mapping or the transfer
+ itself may fail with a soft error, in which case the sender-
+ SMTP will requeue the outgoing mail for a later retry, as
+ required in Section 5.3.1.1.
+
+ When it succeeds, the mapping can result in a list of
+ alternative delivery addresses rather than a single address,
+ because of (a) multiple MX records, (b) multihoming, or both.
+ To provide reliable mail transmission, the sender-SMTP MUST be
+ able to try (and retry) each of the addresses in this list in
+ order, until a delivery attempt succeeds. However, there MAY
+ also be a configurable limit on the number of alternate
+ addresses that can be tried. In any case, a host SHOULD try at
+ least two addresses.
+
+ The following information is to be used to rank the host
+ addresses:
+
+ (1) Multiple MX Records -- these contain a preference
+ indication that should be used in sorting. If there are
+ multiple destinations with the same preference and there
+ is no clear reason to favor one (e.g., by address
+ preference), then the sender-SMTP SHOULD pick one at
+ random to spread the load across multiple mail exchanges
+ for a specific organization; note that this is a
+ refinement of the procedure in [DNS:3].
+
+ (2) Multihomed host -- The destination host (perhaps taken
+ from the preferred MX record) may be multihomed, in which
+ case the domain name resolver will return a list of
+ alternative IP addresses. It is the responsibility of the
+ domain name resolver interface (see Section 6.1.3.4 below)
+ to have ordered this list by decreasing preference, and
+ SMTP MUST try them in the order presented.
+
+ DISCUSSION:
+ Although the capability to try multiple alternative
+ addresses is required, there may be circumstances where
+ specific installations want to limit or disable the use of
+ alternative addresses. The question of whether a sender
+ should attempt retries using the different addresses of a
+ multihomed host has been controversial. The main argument
+ for using the multiple addresses is that it maximizes the
+ probability of timely delivery, and indeed sometimes the
+ probability of any delivery; the counter argument is that
+ it may result in unnecessary resource use.
+
+ Note that resource use is also strongly determined by the
+
+
+
+Internet Engineering Task Force [Page 64]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ sending strategy discussed in Section 5.3.1.
+
+ 5.3.5 Domain Name Support
+
+ SMTP implementations MUST use the mechanism defined in Section
+ 6.1 for mapping between domain names and IP addresses. This
+ means that every Internet SMTP MUST include support for the
+ Internet DNS.
+
+ In particular, a sender-SMTP MUST support the MX record scheme
+ [SMTP:3]. See also Section 7.4 of [DNS:2] for information on
+ domain name support for SMTP.
+
+ 5.3.6 Mailing Lists and Aliases
+
+ An SMTP-capable host SHOULD support both the alias and the list
+ form of address expansion for multiple delivery. When a
+ message is delivered or forwarded to each address of an
+ expanded list form, the return address in the envelope
+ ("MAIL FROM:") MUST be changed to be the address of a person
+ who administers the list, but the message header MUST be left
+ unchanged; in particular, the "From" field of the message is
+ unaffected.
+
+ DISCUSSION:
+ An important mail facility is a mechanism for multi-
+ destination delivery of a single message, by transforming
+ or "expanding" a pseudo-mailbox address into a list of
+ destination mailbox addresses. When a message is sent to
+ such a pseudo-mailbox (sometimes called an "exploder"),
+ copies are forwarded or redistributed to each mailbox in
+ the expanded list. We classify such a pseudo-mailbox as
+ an "alias" or a "list", depending upon the expansion
+ rules:
+
+ (a) Alias
+
+ To expand an alias, the recipient mailer simply
+ replaces the pseudo-mailbox address in the envelope
+ with each of the expanded addresses in turn; the rest
+ of the envelope and the message body are left
+ unchanged. The message is then delivered or
+ forwarded to each expanded address.
+
+ (b) List
+
+ A mailing list may be said to operate by
+ "redistribution" rather than by "forwarding". To
+
+
+
+Internet Engineering Task Force [Page 65]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ expand a list, the recipient mailer replaces the
+ pseudo-mailbox address in the envelope with each of
+ the expanded addresses in turn. The return address in
+ the envelope is changed so that all error messages
+ generated by the final deliveries will be returned to
+ a list administrator, not to the message originator,
+ who generally has no control over the contents of the
+ list and will typically find error messages annoying.
+
+
+ 5.3.7 Mail Gatewaying
+
+ Gatewaying mail between different mail environments, i.e.,
+ different mail formats and protocols, is complex and does not
+ easily yield to standardization. See for example [SMTP:5a],
+ [SMTP:5b]. However, some general requirements may be given for
+ a gateway between the Internet and another mail environment.
+
+ (A) Header fields MAY be rewritten when necessary as messages
+ are gatewayed across mail environment boundaries.
+
+ DISCUSSION:
+ This may involve interpreting the local-part of the
+ destination address, as suggested in Section 5.2.16.
+
+ The other mail systems gatewayed to the Internet
+ generally use a subset of RFC-822 headers, but some
+ of them do not have an equivalent to the SMTP
+ envelope. Therefore, when a message leaves the
+ Internet environment, it may be necessary to fold the
+ SMTP envelope information into the message header. A
+ possible solution would be to create new header
+ fields to carry the envelope information (e.g., "X-
+ SMTP-MAIL:" and "X-SMTP-RCPT:"); however, this would
+ require changes in mail programs in the foreign
+ environment.
+
+ (B) When forwarding a message into or out of the Internet
+ environment, a gateway MUST prepend a Received: line, but
+ it MUST NOT alter in any way a Received: line that is
+ already in the header.
+
+ DISCUSSION:
+ This requirement is a subset of the general
+ "Received:" line requirement of Section 5.2.8; it is
+ restated here for emphasis.
+
+ Received: fields of messages originating from other
+
+
+
+Internet Engineering Task Force [Page 66]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ environments may not conform exactly to RFC822.
+ However, the most important use of Received: lines is
+ for debugging mail faults, and this debugging can be
+ severely hampered by well-meaning gateways that try
+ to "fix" a Received: line.
+
+ The gateway is strongly encouraged to indicate the
+ environment and protocol in the "via" clauses of
+ Received field(s) that it supplies.
+
+ (C) From the Internet side, the gateway SHOULD accept all
+ valid address formats in SMTP commands and in RFC-822
+ headers, and all valid RFC-822 messages. Although a
+ gateway must accept an RFC-822 explicit source route
+ ("@...:" format) in either the RFC-822 header or in the
+ envelope, it MAY or may not act on the source route; see
+ Sections 5.2.6 and 5.2.19.
+
+ DISCUSSION:
+ It is often tempting to restrict the range of
+ addresses accepted at the mail gateway to simplify
+ the translation into addresses for the remote
+ environment. This practice is based on the
+ assumption that mail users have control over the
+ addresses their mailers send to the mail gateway. In
+ practice, however, users have little control over the
+ addresses that are finally sent; their mailers are
+ free to change addresses into any legal RFC-822
+ format.
+
+ (D) The gateway MUST ensure that all header fields of a
+ message that it forwards into the Internet meet the
+ requirements for Internet mail. In particular, all
+ addresses in "From:", "To:", "Cc:", etc., fields must be
+ transformed (if necessary) to satisfy RFC-822 syntax, and
+ they must be effective and useful for sending replies.
+
+
+ (E) The translation algorithm used to convert mail from the
+ Internet protocols to another environment's protocol
+ SHOULD try to ensure that error messages from the foreign
+ mail environment are delivered to the return path from the
+ SMTP envelope, not to the sender listed in the "From:"
+ field of the RFC-822 message.
+
+ DISCUSSION:
+ Internet mail lists usually place the address of the
+ mail list maintainer in the envelope but leave the
+
+
+
+Internet Engineering Task Force [Page 67]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ original message header intact (with the "From:"
+ field containing the original sender). This yields
+ the behavior the average recipient expects: a reply
+ to the header gets sent to the original sender, not
+ to a mail list maintainer; however, errors get sent
+ to the maintainer (who can fix the problem) and not
+ the sender (who probably cannot).
+
+ (F) Similarly, when forwarding a message from another
+ environment into the Internet, the gateway SHOULD set the
+ envelope return path in accordance with an error message
+ return address, if any, supplied by the foreign
+ environment.
+
+
+ 5.3.8 Maximum Message Size
+
+ Mailer software MUST be able to send and receive messages of at
+ least 64K bytes in length (including header), and a much larger
+ maximum size is highly desirable.
+
+ DISCUSSION:
+ Although SMTP does not define the maximum size of a
+ message, many systems impose implementation limits.
+
+ The current de facto minimum limit in the Internet is 64K
+ bytes. However, electronic mail is used for a variety of
+ purposes that create much larger messages. For example,
+ mail is often used instead of FTP for transmitting ASCII
+ files, and in particular to transmit entire documents. As
+ a result, messages can be 1 megabyte or even larger. We
+ note that the present document together with its lower-
+ layer companion contains 0.5 megabytes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 68]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ 5.4 SMTP REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-----------------------------------------------|----------|-|-|-|-|-|--
+ | | | | | | |
+RECEIVER-SMTP: | | | | | | |
+ Implement VRFY |5.2.3 |x| | | | |
+ Implement EXPN |5.2.3 | |x| | | |
+ EXPN, VRFY configurable |5.2.3 | | |x| | |
+ Implement SEND, SOML, SAML |5.2.4 | | |x| | |
+ Verify HELO parameter |5.2.5 | | |x| | |
+ Refuse message with bad HELO |5.2.5 | | | | |x|
+ Accept explicit src-route syntax in env. |5.2.6 |x| | | | |
+ Support "postmaster" |5.2.7 |x| | | | |
+ Process RCPT when received (except lists) |5.2.7 | | |x| | |
+ Long delay of RCPT responses |5.2.7 | | | | |x|
+ | | | | | | |
+ Add Received: line |5.2.8 |x| | | | |
+ Received: line include domain literal |5.2.8 | |x| | | |
+ Change previous Received: line |5.2.8 | | | | |x|
+ Pass Return-Path info (final deliv/gwy) |5.2.8 |x| | | | |
+ Support empty reverse path |5.2.9 |x| | | | |
+ Send only official reply codes |5.2.10 | |x| | | |
+ Send text from RFC-821 when appropriate |5.2.10 | |x| | | |
+ Delete "." for transparency |5.2.11 |x| | | | |
+ Accept and recognize self domain literal(s) |5.2.17 |x| | | | |
+ | | | | | | |
+ Error message about error message |5.3.1 | | | | |x|
+ Keep pending listen on SMTP port |5.3.1.2 | |x| | | |
+ Provide limit on recv concurrency |5.3.1.2 | | |x| | |
+ Wait at least 5 mins for next sender cmd |5.3.2 | |x| | | |
+ Avoidable delivery failure after "250 OK" |5.3.3 | | | | |x|
+ Send error notification msg after accept |5.3.3 |x| | | | |
+ Send using null return path |5.3.3 |x| | | | |
+ Send to envelope return path |5.3.3 | |x| | | |
+ Send to null address |5.3.3 | | | | |x|
+ Strip off explicit src route |5.3.3 | |x| | | |
+ Minimize acceptance delay (RFC-1047) |5.3.3 |x| | | | |
+-----------------------------------------------|----------|-|-|-|-|-|--
+
+
+
+Internet Engineering Task Force [Page 69]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ | | | | | | |
+SENDER-SMTP: | | | | | | |
+ Canonicalized domain names in MAIL, RCPT |5.2.2 |x| | | | |
+ Implement SEND, SOML, SAML |5.2.4 | | |x| | |
+ Send valid principal host name in HELO |5.2.5 |x| | | | |
+ Send explicit source route in RCPT TO: |5.2.6 | | | |x| |
+ Use only reply code to determine action |5.2.10 |x| | | | |
+ Use only high digit of reply code when poss. |5.2.10 | |x| | | |
+ Add "." for transparency |5.2.11 |x| | | | |
+ | | | | | | |
+ Retry messages after soft failure |5.3.1.1 |x| | | | |
+ Delay before retry |5.3.1.1 |x| | | | |
+ Configurable retry parameters |5.3.1.1 |x| | | | |
+ Retry once per each queued dest host |5.3.1.1 | |x| | | |
+ Multiple RCPT's for same DATA |5.3.1.1 | |x| | | |
+ Support multiple concurrent transactions |5.3.1.1 | | |x| | |
+ Provide limit on concurrency |5.3.1.1 | |x| | | |
+ | | | | | | |
+ Timeouts on all activities |5.3.1 |x| | | | |
+ Per-command timeouts |5.3.2 | |x| | | |
+ Timeouts easily reconfigurable |5.3.2 | |x| | | |
+ Recommended times |5.3.2 | |x| | | |
+ Try alternate addr's in order |5.3.4 |x| | | | |
+ Configurable limit on alternate tries |5.3.4 | | |x| | |
+ Try at least two alternates |5.3.4 | |x| | | |
+ Load-split across equal MX alternates |5.3.4 | |x| | | |
+ Use the Domain Name System |5.3.5 |x| | | | |
+ Support MX records |5.3.5 |x| | | | |
+ Use WKS records in MX processing |5.2.12 | | | |x| |
+-----------------------------------------------|----------|-|-|-|-|-|--
+ | | | | | | |
+MAIL FORWARDING: | | | | | | |
+ Alter existing header field(s) |5.2.6 | | | |x| |
+ Implement relay function: 821/section 3.6 |5.2.6 | | |x| | |
+ If not, deliver to RHS domain |5.2.6 | |x| | | |
+ Interpret 'local-part' of addr |5.2.16 | | | | |x|
+ | | | | | | |
+MAILING LISTS AND ALIASES | | | | | | |
+ Support both |5.3.6 | |x| | | |
+ Report mail list error to local admin. |5.3.6 |x| | | | |
+ | | | | | | |
+MAIL GATEWAYS: | | | | | | |
+ Embed foreign mail route in local-part |5.2.16 | | |x| | |
+ Rewrite header fields when necessary |5.3.7 | | |x| | |
+ Prepend Received: line |5.3.7 |x| | | | |
+ Change existing Received: line |5.3.7 | | | | |x|
+ Accept full RFC-822 on Internet side |5.3.7 | |x| | | |
+ Act on RFC-822 explicit source route |5.3.7 | | |x| | |
+
+
+
+Internet Engineering Task Force [Page 70]
+
+
+
+
+RFC1123 MAIL -- SMTP & RFC-822 October 1989
+
+
+ Send only valid RFC-822 on Internet side |5.3.7 |x| | | | |
+ Deliver error msgs to envelope addr |5.3.7 | |x| | | |
+ Set env return path from err return addr |5.3.7 | |x| | | |
+ | | | | | | |
+USER AGENT -- RFC-822 | | | | | | |
+ Allow user to enter <route> address |5.2.6 | | | |x| |
+ Support RFC-1049 Content Type field |5.2.13 | | |x| | |
+ Use 4-digit years |5.2.14 | |x| | | |
+ Generate numeric timezones |5.2.14 | |x| | | |
+ Accept all timezones |5.2.14 |x| | | | |
+ Use non-num timezones from RFC-822 |5.2.14 |x| | | | |
+ Omit phrase before route-addr |5.2.15 | | |x| | |
+ Accept and parse dot.dec. domain literals |5.2.17 |x| | | | |
+ Accept all RFC-822 address formats |5.2.18 |x| | | | |
+ Generate invalid RFC-822 address format |5.2.18 | | | | |x|
+ Fully-qualified domain names in header |5.2.18 |x| | | | |
+ Create explicit src route in header |5.2.19 | | | |x| |
+ Accept explicit src route in header |5.2.19 |x| | | | |
+ | | | | | | |
+Send/recv at least 64KB messages |5.3.8 |x| | | | |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 71]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+6. SUPPORT SERVICES
+
+ 6.1 DOMAIN NAME TRANSLATION
+
+ 6.1.1 INTRODUCTION
+
+ Every host MUST implement a resolver for the Domain Name System
+ (DNS), and it MUST implement a mechanism using this DNS
+ resolver to convert host names to IP addresses and vice-versa
+ [DNS:1, DNS:2].
+
+ In addition to the DNS, a host MAY also implement a host name
+ translation mechanism that searches a local Internet host
+ table. See Section 6.1.3.8 for more information on this
+ option.
+
+ DISCUSSION:
+ Internet host name translation was originally performed by
+ searching local copies of a table of all hosts. This
+ table became too large to update and distribute in a
+ timely manner and too large to fit into many hosts, so the
+ DNS was invented.
+
+ The DNS creates a distributed database used primarily for
+ the translation between host names and host addresses.
+ Implementation of DNS software is required. The DNS
+ consists of two logically distinct parts: name servers and
+ resolvers (although implementations often combine these
+ two logical parts in the interest of efficiency) [DNS:2].
+
+ Domain name servers store authoritative data about certain
+ sections of the database and answer queries about the
+ data. Domain resolvers query domain name servers for data
+ on behalf of user processes. Every host therefore needs a
+ DNS resolver; some host machines will also need to run
+ domain name servers. Since no name server has complete
+ information, in general it is necessary to obtain
+ information from more than one name server to resolve a
+ query.
+
+ 6.1.2 PROTOCOL WALK-THROUGH
+
+ An implementor must study references [DNS:1] and [DNS:2]
+ carefully. They provide a thorough description of the theory,
+ protocol, and implementation of the domain name system, and
+ reflect several years of experience.
+
+
+
+
+
+Internet Engineering Task Force [Page 72]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ 6.1.2.1 Resource Records with Zero TTL: RFC-1035 Section 3.2.1
+
+ All DNS name servers and resolvers MUST properly handle RRs
+ with a zero TTL: return the RR to the client but do not
+ cache it.
+
+ DISCUSSION:
+ Zero TTL values are interpreted to mean that the RR can
+ only be used for the transaction in progress, and
+ should not be cached; they are useful for extremely
+ volatile data.
+
+ 6.1.2.2 QCLASS Values: RFC-1035 Section 3.2.5
+
+ A query with "QCLASS=*" SHOULD NOT be used unless the
+ requestor is seeking data from more than one class. In
+ particular, if the requestor is only interested in Internet
+ data types, QCLASS=IN MUST be used.
+
+ 6.1.2.3 Unused Fields: RFC-1035 Section 4.1.1
+
+ Unused fields in a query or response message MUST be zero.
+
+ 6.1.2.4 Compression: RFC-1035 Section 4.1.4
+
+ Name servers MUST use compression in responses.
+
+ DISCUSSION:
+ Compression is essential to avoid overflowing UDP
+ datagrams; see Section 6.1.3.2.
+
+ 6.1.2.5 Misusing Configuration Info: RFC-1035 Section 6.1.2
+
+ Recursive name servers and full-service resolvers generally
+ have some configuration information containing hints about
+ the location of root or local name servers. An
+ implementation MUST NOT include any of these hints in a
+ response.
+
+ DISCUSSION:
+ Many implementors have found it convenient to store
+ these hints as if they were cached data, but some
+ neglected to ensure that this "cached data" was not
+ included in responses. This has caused serious
+ problems in the Internet when the hints were obsolete
+ or incorrect.
+
+
+
+
+
+Internet Engineering Task Force [Page 73]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ 6.1.3 SPECIFIC ISSUES
+
+ 6.1.3.1 Resolver Implementation
+
+ A name resolver SHOULD be able to multiplex concurrent
+ requests if the host supports concurrent processes.
+
+ In implementing a DNS resolver, one of two different models
+ MAY optionally be chosen: a full-service resolver, or a stub
+ resolver.
+
+
+ (A) Full-Service Resolver
+
+ A full-service resolver is a complete implementation of
+ the resolver service, and is capable of dealing with
+ communication failures, failure of individual name
+ servers, location of the proper name server for a given
+ name, etc. It must satisfy the following requirements:
+
+ o The resolver MUST implement a local caching
+ function to avoid repeated remote access for
+ identical requests, and MUST time out information
+ in the cache.
+
+ o The resolver SHOULD be configurable with start-up
+ information pointing to multiple root name servers
+ and multiple name servers for the local domain.
+ This insures that the resolver will be able to
+ access the whole name space in normal cases, and
+ will be able to access local domain information
+ should the local network become disconnected from
+ the rest of the Internet.
+
+
+ (B) Stub Resolver
+
+ A "stub resolver" relies on the services of a recursive
+ name server on the connected network or a "nearby"
+ network. This scheme allows the host to pass on the
+ burden of the resolver function to a name server on
+ another host. This model is often essential for less
+ capable hosts, such as PCs, and is also recommended
+ when the host is one of several workstations on a local
+ network, because it allows all of the workstations to
+ share the cache of the recursive name server and hence
+ reduce the number of domain requests exported by the
+ local network.
+
+
+
+Internet Engineering Task Force [Page 74]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ At a minimum, the stub resolver MUST be capable of
+ directing its requests to redundant recursive name
+ servers. Note that recursive name servers are allowed
+ to restrict the sources of requests that they will
+ honor, so the host administrator must verify that the
+ service will be provided. Stub resolvers MAY implement
+ caching if they choose, but if so, MUST timeout cached
+ information.
+
+
+ 6.1.3.2 Transport Protocols
+
+ DNS resolvers and recursive servers MUST support UDP, and
+ SHOULD support TCP, for sending (non-zone-transfer) queries.
+ Specifically, a DNS resolver or server that is sending a
+ non-zone-transfer query MUST send a UDP query first. If the
+ Answer section of the response is truncated and if the
+ requester supports TCP, it SHOULD try the query again using
+ TCP.
+
+ DNS servers MUST be able to service UDP queries and SHOULD
+ be able to service TCP queries. A name server MAY limit the
+ resources it devotes to TCP queries, but it SHOULD NOT
+ refuse to service a TCP query just because it would have
+ succeeded with UDP.
+
+ Truncated responses MUST NOT be saved (cached) and later
+ used in such a way that the fact that they are truncated is
+ lost.
+
+ DISCUSSION:
+ UDP is preferred over TCP for queries because UDP
+ queries have much lower overhead, both in packet count
+ and in connection state. The use of UDP is essential
+ for heavily-loaded servers, especially the root
+ servers. UDP also offers additional robustness, since
+ a resolver can attempt several UDP queries to different
+ servers for the cost of a single TCP query.
+
+ It is possible for a DNS response to be truncated,
+ although this is a very rare occurrence in the present
+ Internet DNS. Practically speaking, truncation cannot
+ be predicted, since it is data-dependent. The
+ dependencies include the number of RRs in the answer,
+ the size of each RR, and the savings in space realized
+ by the name compression algorithm. As a rule of thumb,
+ truncation in NS and MX lists should not occur for
+ answers containing 15 or fewer RRs.
+
+
+
+Internet Engineering Task Force [Page 75]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ Whether it is possible to use a truncated answer
+ depends on the application. A mailer must not use a
+ truncated MX response, since this could lead to mail
+ loops.
+
+ Responsible practices can make UDP suffice in the vast
+ majority of cases. Name servers must use compression
+ in responses. Resolvers must differentiate truncation
+ of the Additional section of a response (which only
+ loses extra information) from truncation of the Answer
+ section (which for MX records renders the response
+ unusable by mailers). Database administrators should
+ list only a reasonable number of primary names in lists
+ of name servers, MX alternatives, etc.
+
+ However, it is also clear that some new DNS record
+ types defined in the future will contain information
+ exceeding the 512 byte limit that applies to UDP, and
+ hence will require TCP. Thus, resolvers and name
+ servers should implement TCP services as a backup to
+ UDP today, with the knowledge that they will require
+ the TCP service in the future.
+
+ By private agreement, name servers and resolvers MAY arrange
+ to use TCP for all traffic between themselves. TCP MUST be
+ used for zone transfers.
+
+ A DNS server MUST have sufficient internal concurrency that
+ it can continue to process UDP queries while awaiting a
+ response or performing a zone transfer on an open TCP
+ connection [DNS:2].
+
+ A server MAY support a UDP query that is delivered using an
+ IP broadcast or multicast address. However, the Recursion
+ Desired bit MUST NOT be set in a query that is multicast,
+ and MUST be ignored by name servers receiving queries via a
+ broadcast or multicast address. A host that sends broadcast
+ or multicast DNS queries SHOULD send them only as occasional
+ probes, caching the IP address(es) it obtains from the
+ response(s) so it can normally send unicast queries.
+
+ DISCUSSION:
+ Broadcast or (especially) IP multicast can provide a
+ way to locate nearby name servers without knowing their
+ IP addresses in advance. However, general broadcasting
+ of recursive queries can result in excessive and
+ unnecessary load on both network and servers.
+
+
+
+
+Internet Engineering Task Force [Page 76]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ 6.1.3.3 Efficient Resource Usage
+
+ The following requirements on servers and resolvers are very
+ important to the health of the Internet as a whole,
+ particularly when DNS services are invoked repeatedly by
+ higher level automatic servers, such as mailers.
+
+ (1) The resolver MUST implement retransmission controls to
+ insure that it does not waste communication bandwidth,
+ and MUST impose finite bounds on the resources consumed
+ to respond to a single request. See [DNS:2] pages 43-
+ 44 for specific recommendations.
+
+ (2) After a query has been retransmitted several times
+ without a response, an implementation MUST give up and
+ return a soft error to the application.
+
+ (3) All DNS name servers and resolvers SHOULD cache
+ temporary failures, with a timeout period of the order
+ of minutes.
+
+ DISCUSSION:
+ This will prevent applications that immediately
+ retry soft failures (in violation of Section 2.2
+ of this document) from generating excessive DNS
+ traffic.
+
+ (4) All DNS name servers and resolvers SHOULD cache
+ negative responses that indicate the specified name, or
+ data of the specified type, does not exist, as
+ described in [DNS:2].
+
+ (5) When a DNS server or resolver retries a UDP query, the
+ retry interval SHOULD be constrained by an exponential
+ backoff algorithm, and SHOULD also have upper and lower
+ bounds.
+
+ IMPLEMENTATION:
+ A measured RTT and variance (if available) should
+ be used to calculate an initial retransmission
+ interval. If this information is not available, a
+ default of no less than 5 seconds should be used.
+ Implementations may limit the retransmission
+ interval, but this limit must exceed twice the
+ Internet maximum segment lifetime plus service
+ delay at the name server.
+
+ (6) When a resolver or server receives a Source Quench for
+
+
+
+Internet Engineering Task Force [Page 77]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ a query it has issued, it SHOULD take steps to reduce
+ the rate of querying that server in the near future. A
+ server MAY ignore a Source Quench that it receives as
+ the result of sending a response datagram.
+
+ IMPLEMENTATION:
+ One recommended action to reduce the rate is to
+ send the next query attempt to an alternate
+ server, if there is one available. Another is to
+ backoff the retry interval for the same server.
+
+
+ 6.1.3.4 Multihomed Hosts
+
+ When the host name-to-address function encounters a host
+ with multiple addresses, it SHOULD rank or sort the
+ addresses using knowledge of the immediately connected
+ network number(s) and any other applicable performance or
+ history information.
+
+ DISCUSSION:
+ The different addresses of a multihomed host generally
+ imply different Internet paths, and some paths may be
+ preferable to others in performance, reliability, or
+ administrative restrictions. There is no general way
+ for the domain system to determine the best path. A
+ recommended approach is to base this decision on local
+ configuration information set by the system
+ administrator.
+
+ IMPLEMENTATION:
+ The following scheme has been used successfully:
+
+ (a) Incorporate into the host configuration data a
+ Network-Preference List, that is simply a list of
+ networks in preferred order. This list may be
+ empty if there is no preference.
+
+ (b) When a host name is mapped into a list of IP
+ addresses, these addresses should be sorted by
+ network number, into the same order as the
+ corresponding networks in the Network-Preference
+ List. IP addresses whose networks do not appear
+ in the Network-Preference List should be placed at
+ the end of the list.
+
+
+
+
+
+
+Internet Engineering Task Force [Page 78]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ 6.1.3.5 Extensibility
+
+ DNS software MUST support all well-known, class-independent
+ formats [DNS:2], and SHOULD be written to minimize the
+ trauma associated with the introduction of new well-known
+ types and local experimentation with non-standard types.
+
+ DISCUSSION:
+ The data types and classes used by the DNS are
+ extensible, and thus new types will be added and old
+ types deleted or redefined. Introduction of new data
+ types ought to be dependent only upon the rules for
+ compression of domain names inside DNS messages, and
+ the translation between printable (i.e., master file)
+ and internal formats for Resource Records (RRs).
+
+ Compression relies on knowledge of the format of data
+ inside a particular RR. Hence compression must only be
+ used for the contents of well-known, class-independent
+ RRs, and must never be used for class-specific RRs or
+ RR types that are not well-known. The owner name of an
+ RR is always eligible for compression.
+
+ A name server may acquire, via zone transfer, RRs that
+ the server doesn't know how to convert to printable
+ format. A resolver can receive similar information as
+ the result of queries. For proper operation, this data
+ must be preserved, and hence the implication is that
+ DNS software cannot use textual formats for internal
+ storage.
+
+ The DNS defines domain name syntax very generally -- a
+ string of labels each containing up to 63 8-bit octets,
+ separated by dots, and with a maximum total of 255
+ octets. Particular applications of the DNS are
+ permitted to further constrain the syntax of the domain
+ names they use, although the DNS deployment has led to
+ some applications allowing more general names. In
+ particular, Section 2.1 of this document liberalizes
+ slightly the syntax of a legal Internet host name that
+ was defined in RFC-952 [DNS:4].
+
+ 6.1.3.6 Status of RR Types
+
+ Name servers MUST be able to load all RR types except MD and
+ MF from configuration files. The MD and MF types are
+ obsolete and MUST NOT be implemented; in particular, name
+ servers MUST NOT load these types from configuration files.
+
+
+
+Internet Engineering Task Force [Page 79]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ DISCUSSION:
+ The RR types MB, MG, MR, NULL, MINFO and RP are
+ considered experimental, and applications that use the
+ DNS cannot expect these RR types to be supported by
+ most domains. Furthermore these types are subject to
+ redefinition.
+
+ The TXT and WKS RR types have not been widely used by
+ Internet sites; as a result, an application cannot rely
+ on the the existence of a TXT or WKS RR in most
+ domains.
+
+ 6.1.3.7 Robustness
+
+ DNS software may need to operate in environments where the
+ root servers or other servers are unavailable due to network
+ connectivity or other problems. In this situation, DNS name
+ servers and resolvers MUST continue to provide service for
+ the reachable part of the name space, while giving temporary
+ failures for the rest.
+
+ DISCUSSION:
+ Although the DNS is meant to be used primarily in the
+ connected Internet, it should be possible to use the
+ system in networks which are unconnected to the
+ Internet. Hence implementations must not depend on
+ access to root servers before providing service for
+ local names.
+
+ 6.1.3.8 Local Host Table
+
+ DISCUSSION:
+ A host may use a local host table as a backup or
+ supplement to the DNS. This raises the question of
+ which takes precedence, the DNS or the host table; the
+ most flexible approach would make this a configuration
+ option.
+
+ Typically, the contents of such a supplementary host
+ table will be determined locally by the site. However,
+ a publically-available table of Internet hosts is
+ maintained by the DDN Network Information Center (DDN
+ NIC), with a format documented in [DNS:4]. This table
+ can be retrieved from the DDN NIC using a protocol
+ described in [DNS:5]. It must be noted that this table
+ contains only a small fraction of all Internet hosts.
+ Hosts using this protocol to retrieve the DDN NIC host
+ table should use the VERSION command to check if the
+
+
+
+Internet Engineering Task Force [Page 80]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ table has changed before requesting the entire table
+ with the ALL command. The VERSION identifier should be
+ treated as an arbitrary string and tested only for
+ equality; no numerical sequence may be assumed.
+
+ The DDN NIC host table includes administrative
+ information that is not needed for host operation and
+ is therefore not currently included in the DNS
+ database; examples include network and gateway entries.
+ However, much of this additional information will be
+ added to the DNS in the future. Conversely, the DNS
+ provides essential services (in particular, MX records)
+ that are not available from the DDN NIC host table.
+
+ 6.1.4 DNS USER INTERFACE
+
+ 6.1.4.1 DNS Administration
+
+ This document is concerned with design and implementation
+ issues in host software, not with administrative or
+ operational issues. However, administrative issues are of
+ particular importance in the DNS, since errors in particular
+ segments of this large distributed database can cause poor
+ or erroneous performance for many sites. These issues are
+ discussed in [DNS:6] and [DNS:7].
+
+ 6.1.4.2 DNS User Interface
+
+ Hosts MUST provide an interface to the DNS for all
+ application programs running on the host. This interface
+ will typically direct requests to a system process to
+ perform the resolver function [DNS:1, 6.1:2].
+
+ At a minimum, the basic interface MUST support a request for
+ all information of a specific type and class associated with
+ a specific name, and it MUST return either all of the
+ requested information, a hard error code, or a soft error
+ indication. When there is no error, the basic interface
+ returns the complete response information without
+ modification, deletion, or ordering, so that the basic
+ interface will not need to be changed to accommodate new
+ data types.
+
+ DISCUSSION:
+ The soft error indication is an essential part of the
+ interface, since it may not always be possible to
+ access particular information from the DNS; see Section
+ 6.1.3.3.
+
+
+
+Internet Engineering Task Force [Page 81]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ A host MAY provide other DNS interfaces tailored to
+ particular functions, transforming the raw domain data into
+ formats more suited to these functions. In particular, a
+ host MUST provide a DNS interface to facilitate translation
+ between host addresses and host names.
+
+ 6.1.4.3 Interface Abbreviation Facilities
+
+ User interfaces MAY provide a method for users to enter
+ abbreviations for commonly-used names. Although the
+ definition of such methods is outside of the scope of the
+ DNS specification, certain rules are necessary to insure
+ that these methods allow access to the entire DNS name space
+ and to prevent excessive use of Internet resources.
+
+ If an abbreviation method is provided, then:
+
+ (a) There MUST be some convention for denoting that a name
+ is already complete, so that the abbreviation method(s)
+ are suppressed. A trailing dot is the usual method.
+
+ (b) Abbreviation expansion MUST be done exactly once, and
+ MUST be done in the context in which the name was
+ entered.
+
+
+ DISCUSSION:
+ For example, if an abbreviation is used in a mail
+ program for a destination, the abbreviation should be
+ expanded into a full domain name and stored in the
+ queued message with an indication that it is already
+ complete. Otherwise, the abbreviation might be
+ expanded with a mail system search list, not the
+ user's, or a name could grow due to repeated
+ canonicalizations attempts interacting with wildcards.
+
+ The two most common abbreviation methods are:
+
+ (1) Interface-level aliases
+
+ Interface-level aliases are conceptually implemented as
+ a list of alias/domain name pairs. The list can be
+ per-user or per-host, and separate lists can be
+ associated with different functions, e.g. one list for
+ host name-to-address translation, and a different list
+ for mail domains. When the user enters a name, the
+ interface attempts to match the name to the alias
+ component of a list entry, and if a matching entry can
+
+
+
+Internet Engineering Task Force [Page 82]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ be found, the name is replaced by the domain name found
+ in the pair.
+
+ Note that interface-level aliases and CNAMEs are
+ completely separate mechanisms; interface-level aliases
+ are a local matter while CNAMEs are an Internet-wide
+ aliasing mechanism which is a required part of any DNS
+ implementation.
+
+ (2) Search Lists
+
+ A search list is conceptually implemented as an ordered
+ list of domain names. When the user enters a name, the
+ domain names in the search list are used as suffixes to
+ the user-supplied name, one by one, until a domain name
+ with the desired associated data is found, or the
+ search list is exhausted. Search lists often contain
+ the name of the local host's parent domain or other
+ ancestor domains. Search lists are often per-user or
+ per-process.
+
+ It SHOULD be possible for an administrator to disable a
+ DNS search-list facility. Administrative denial may be
+ warranted in some cases, to prevent abuse of the DNS.
+
+ There is danger that a search-list mechanism will
+ generate excessive queries to the root servers while
+ testing whether user input is a complete domain name,
+ lacking a final period to mark it as complete. A
+ search-list mechanism MUST have one of, and SHOULD have
+ both of, the following two provisions to prevent this:
+
+ (a) The local resolver/name server can implement
+ caching of negative responses (see Section
+ 6.1.3.3).
+
+ (b) The search list expander can require two or more
+ interior dots in a generated domain name before it
+ tries using the name in a query to non-local
+ domain servers, such as the root.
+
+ DISCUSSION:
+ The intent of this requirement is to avoid
+ excessive delay for the user as the search list is
+ tested, and more importantly to prevent excessive
+ traffic to the root and other high-level servers.
+ For example, if the user supplied a name "X" and
+ the search list contained the root as a component,
+
+
+
+Internet Engineering Task Force [Page 83]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ a query would have to consult a root server before
+ the next search list alternative could be tried.
+ The resulting load seen by the root servers and
+ gateways near the root would be multiplied by the
+ number of hosts in the Internet.
+
+ The negative caching alternative limits the effect
+ to the first time a name is used. The interior
+ dot rule is simpler to implement but can prevent
+ easy use of some top-level names.
+
+
+ 6.1.5 DOMAIN NAME SYSTEM REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-----------------------------------------------|-----------|-|-|-|-|-|--
+GENERAL ISSUES | | | | | | |
+ | | | | | | |
+Implement DNS name-to-address conversion |6.1.1 |x| | | | |
+Implement DNS address-to-name conversion |6.1.1 |x| | | | |
+Support conversions using host table |6.1.1 | | |x| | |
+Properly handle RR with zero TTL |6.1.2.1 |x| | | | |
+Use QCLASS=* unnecessarily |6.1.2.2 | |x| | | |
+ Use QCLASS=IN for Internet class |6.1.2.2 |x| | | | |
+Unused fields zero |6.1.2.3 |x| | | | |
+Use compression in responses |6.1.2.4 |x| | | | |
+ | | | | | | |
+Include config info in responses |6.1.2.5 | | | | |x|
+Support all well-known, class-indep. types |6.1.3.5 |x| | | | |
+Easily expand type list |6.1.3.5 | |x| | | |
+Load all RR types (except MD and MF) |6.1.3.6 |x| | | | |
+Load MD or MF type |6.1.3.6 | | | | |x|
+Operate when root servers, etc. unavailable |6.1.3.7 |x| | | | |
+-----------------------------------------------|-----------|-|-|-|-|-|--
+RESOLVER ISSUES: | | | | | | |
+ | | | | | | |
+Resolver support multiple concurrent requests |6.1.3.1 | |x| | | |
+Full-service resolver: |6.1.3.1 | | |x| | |
+ Local caching |6.1.3.1 |x| | | | |
+
+
+
+Internet Engineering Task Force [Page 84]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ Information in local cache times out |6.1.3.1 |x| | | | |
+ Configurable with starting info |6.1.3.1 | |x| | | |
+Stub resolver: |6.1.3.1 | | |x| | |
+ Use redundant recursive name servers |6.1.3.1 |x| | | | |
+ Local caching |6.1.3.1 | | |x| | |
+ Information in local cache times out |6.1.3.1 |x| | | | |
+Support for remote multi-homed hosts: | | | | | | |
+ Sort multiple addresses by preference list |6.1.3.4 | |x| | | |
+ | | | | | | |
+-----------------------------------------------|-----------|-|-|-|-|-|--
+TRANSPORT PROTOCOLS: | | | | | | |
+ | | | | | | |
+Support UDP queries |6.1.3.2 |x| | | | |
+Support TCP queries |6.1.3.2 | |x| | | |
+ Send query using UDP first |6.1.3.2 |x| | | | |1
+ Try TCP if UDP answers are truncated |6.1.3.2 | |x| | | |
+Name server limit TCP query resources |6.1.3.2 | | |x| | |
+ Punish unnecessary TCP query |6.1.3.2 | | | |x| |
+Use truncated data as if it were not |6.1.3.2 | | | | |x|
+Private agreement to use only TCP |6.1.3.2 | | |x| | |
+Use TCP for zone transfers |6.1.3.2 |x| | | | |
+TCP usage not block UDP queries |6.1.3.2 |x| | | | |
+Support broadcast or multicast queries |6.1.3.2 | | |x| | |
+ RD bit set in query |6.1.3.2 | | | | |x|
+ RD bit ignored by server is b'cast/m'cast |6.1.3.2 |x| | | | |
+ Send only as occasional probe for addr's |6.1.3.2 | |x| | | |
+-----------------------------------------------|-----------|-|-|-|-|-|--
+RESOURCE USAGE: | | | | | | |
+ | | | | | | |
+Transmission controls, per [DNS:2] |6.1.3.3 |x| | | | |
+ Finite bounds per request |6.1.3.3 |x| | | | |
+Failure after retries => soft error |6.1.3.3 |x| | | | |
+Cache temporary failures |6.1.3.3 | |x| | | |
+Cache negative responses |6.1.3.3 | |x| | | |
+Retries use exponential backoff |6.1.3.3 | |x| | | |
+ Upper, lower bounds |6.1.3.3 | |x| | | |
+Client handle Source Quench |6.1.3.3 | |x| | | |
+Server ignore Source Quench |6.1.3.3 | | |x| | |
+-----------------------------------------------|-----------|-|-|-|-|-|--
+USER INTERFACE: | | | | | | |
+ | | | | | | |
+All programs have access to DNS interface |6.1.4.2 |x| | | | |
+Able to request all info for given name |6.1.4.2 |x| | | | |
+Returns complete info or error |6.1.4.2 |x| | | | |
+Special interfaces |6.1.4.2 | | |x| | |
+ Name<->Address translation |6.1.4.2 |x| | | | |
+ | | | | | | |
+Abbreviation Facilities: |6.1.4.3 | | |x| | |
+
+
+
+Internet Engineering Task Force [Page 85]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- DOMAINS October 1989
+
+
+ Convention for complete names |6.1.4.3 |x| | | | |
+ Conversion exactly once |6.1.4.3 |x| | | | |
+ Conversion in proper context |6.1.4.3 |x| | | | |
+ Search list: |6.1.4.3 | | |x| | |
+ Administrator can disable |6.1.4.3 | |x| | | |
+ Prevention of excessive root queries |6.1.4.3 |x| | | | |
+ Both methods |6.1.4.3 | |x| | | |
+-----------------------------------------------|-----------|-|-|-|-|-|--
+-----------------------------------------------|-----------|-|-|-|-|-|--
+
+1. Unless there is private agreement between particular resolver and
+ particular server.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 86]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- INITIALIZATION October 1989
+
+
+ 6.2 HOST INITIALIZATION
+
+ 6.2.1 INTRODUCTION
+
+ This section discusses the initialization of host software
+ across a connected network, or more generally across an
+ Internet path. This is necessary for a diskless host, and may
+ optionally be used for a host with disk drives. For a diskless
+ host, the initialization process is called "network booting"
+ and is controlled by a bootstrap program located in a boot ROM.
+
+ To initialize a diskless host across the network, there are two
+ distinct phases:
+
+ (1) Configure the IP layer.
+
+ Diskless machines often have no permanent storage in which
+ to store network configuration information, so that
+ sufficient configuration information must be obtained
+ dynamically to support the loading phase that follows.
+ This information must include at least the IP addresses of
+ the host and of the boot server. To support booting
+ across a gateway, the address mask and a list of default
+ gateways are also required.
+
+ (2) Load the host system code.
+
+ During the loading phase, an appropriate file transfer
+ protocol is used to copy the system code across the
+ network from the boot server.
+
+ A host with a disk may perform the first step, dynamic
+ configuration. This is important for microcomputers, whose
+ floppy disks allow network configuration information to be
+ mistakenly duplicated on more than one host. Also,
+ installation of new hosts is much simpler if they automatically
+ obtain their configuration information from a central server,
+ saving administrator time and decreasing the probability of
+ mistakes.
+
+ 6.2.2 REQUIREMENTS
+
+ 6.2.2.1 Dynamic Configuration
+
+ A number of protocol provisions have been made for dynamic
+ configuration.
+
+ o ICMP Information Request/Reply messages
+
+
+
+Internet Engineering Task Force [Page 87]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- INITIALIZATION October 1989
+
+
+ This obsolete message pair was designed to allow a host
+ to find the number of the network it is on.
+ Unfortunately, it was useful only if the host already
+ knew the host number part of its IP address,
+ information that hosts requiring dynamic configuration
+ seldom had.
+
+ o Reverse Address Resolution Protocol (RARP) [BOOT:4]
+
+ RARP is a link-layer protocol for a broadcast medium
+ that allows a host to find its IP address given its
+ link layer address. Unfortunately, RARP does not work
+ across IP gateways and therefore requires a RARP server
+ on every network. In addition, RARP does not provide
+ any other configuration information.
+
+ o ICMP Address Mask Request/Reply messages
+
+ These ICMP messages allow a host to learn the address
+ mask for a particular network interface.
+
+ o BOOTP Protocol [BOOT:2]
+
+ This protocol allows a host to determine the IP
+ addresses of the local host and the boot server, the
+ name of an appropriate boot file, and optionally the
+ address mask and list of default gateways. To locate a
+ BOOTP server, the host broadcasts a BOOTP request using
+ UDP. Ad hoc gateway extensions have been used to
+ transmit the BOOTP broadcast through gateways, and in
+ the future the IP Multicasting facility will provide a
+ standard mechanism for this purpose.
+
+
+ The suggested approach to dynamic configuration is to use
+ the BOOTP protocol with the extensions defined in "BOOTP
+ Vendor Information Extensions" RFC-1084 [BOOT:3]. RFC-1084
+ defines some important general (not vendor-specific)
+ extensions. In particular, these extensions allow the
+ address mask to be supplied in BOOTP; we RECOMMEND that the
+ address mask be supplied in this manner.
+
+ DISCUSSION:
+ Historically, subnetting was defined long after IP, and
+ so a separate mechanism (ICMP Address Mask messages)
+ was designed to supply the address mask to a host.
+ However, the IP address mask and the corresponding IP
+ address conceptually form a pair, and for operational
+
+
+
+Internet Engineering Task Force [Page 88]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- INITIALIZATION October 1989
+
+
+ simplicity they ought to be defined at the same time
+ and by the same mechanism, whether a configuration file
+ or a dynamic mechanism like BOOTP.
+
+ Note that BOOTP is not sufficiently general to specify
+ the configurations of all interfaces of a multihomed
+ host. A multihomed host must either use BOOTP
+ separately for each interface, or configure one
+ interface using BOOTP to perform the loading, and
+ perform the complete initialization from a file later.
+
+ Application layer configuration information is expected
+ to be obtained from files after loading of the system
+ code.
+
+ 6.2.2.2 Loading Phase
+
+ A suggested approach for the loading phase is to use TFTP
+ [BOOT:1] between the IP addresses established by BOOTP.
+
+ TFTP to a broadcast address SHOULD NOT be used, for reasons
+ explained in Section 4.2.3.4.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 89]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ 6.3 REMOTE MANAGEMENT
+
+ 6.3.1 INTRODUCTION
+
+ The Internet community has recently put considerable effort
+ into the development of network management protocols. The
+ result has been a two-pronged approach [MGT:1, MGT:6]: the
+ Simple Network Management Protocol (SNMP) [MGT:4] and the
+ Common Management Information Protocol over TCP (CMOT) [MGT:5].
+
+ In order to be managed using SNMP or CMOT, a host will need to
+ implement an appropriate management agent. An Internet host
+ SHOULD include an agent for either SNMP or CMOT.
+
+ Both SNMP and CMOT operate on a Management Information Base
+ (MIB) that defines a collection of management values. By
+ reading and setting these values, a remote application may
+ query and change the state of the managed system.
+
+ A standard MIB [MGT:3] has been defined for use by both
+ management protocols, using data types defined by the Structure
+ of Management Information (SMI) defined in [MGT:2]. Additional
+ MIB variables can be introduced under the "enterprises" and
+ "experimental" subtrees of the MIB naming space [MGT:2].
+
+ Every protocol module in the host SHOULD implement the relevant
+ MIB variables. A host SHOULD implement the MIB variables as
+ defined in the most recent standard MIB, and MAY implement
+ other MIB variables when appropriate and useful.
+
+ 6.3.2 PROTOCOL WALK-THROUGH
+
+ The MIB is intended to cover both hosts and gateways, although
+ there may be detailed differences in MIB application to the two
+ cases. This section contains the appropriate interpretation of
+ the MIB for hosts. It is likely that later versions of the MIB
+ will include more entries for host management.
+
+ A managed host must implement the following groups of MIB
+ object definitions: System, Interfaces, Address Translation,
+ IP, ICMP, TCP, and UDP.
+
+ The following specific interpretations apply to hosts:
+
+ o ipInHdrErrors
+
+ Note that the error "time-to-live exceeded" can occur in a
+ host only when it is forwarding a source-routed datagram.
+
+
+
+Internet Engineering Task Force [Page 90]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ o ipOutNoRoutes
+
+ This object counts datagrams discarded because no route
+ can be found. This may happen in a host if all the
+ default gateways in the host's configuration are down.
+
+ o ipFragOKs, ipFragFails, ipFragCreates
+
+ A host that does not implement intentional fragmentation
+ (see "Fragmentation" section of [INTRO:1]) MUST return the
+ value zero for these three objects.
+
+ o icmpOutRedirects
+
+ For a host, this object MUST always be zero, since hosts
+ do not send Redirects.
+
+ o icmpOutAddrMaskReps
+
+ For a host, this object MUST always be zero, unless the
+ host is an authoritative source of address mask
+ information.
+
+ o ipAddrTable
+
+ For a host, the "IP Address Table" object is effectively a
+ table of logical interfaces.
+
+ o ipRoutingTable
+
+ For a host, the "IP Routing Table" object is effectively a
+ combination of the host's Routing Cache and the static
+ route table described in "Routing Outbound Datagrams"
+ section of [INTRO:1].
+
+ Within each ipRouteEntry, ipRouteMetric1...4 normally will
+ have no meaning for a host and SHOULD always be -1, while
+ ipRouteType will normally have the value "remote".
+
+ If destinations on the connected network do not appear in
+ the Route Cache (see "Routing Outbound Datagrams section
+ of [INTRO:1]), there will be no entries with ipRouteType
+ of "direct".
+
+
+ DISCUSSION:
+ The current MIB does not include Type-of-Service in an
+ ipRouteEntry, but a future revision is expected to make
+
+
+
+Internet Engineering Task Force [Page 91]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ this addition.
+
+ We also expect the MIB to be expanded to allow the remote
+ management of applications (e.g., the ability to partially
+ reconfigure mail systems). Network service applications
+ such as mail systems should therefore be written with the
+ "hooks" for remote management.
+
+ 6.3.3 MANAGEMENT REQUIREMENTS SUMMARY
+
+ | | | | |S| |
+ | | | | |H| |F
+ | | | | |O|M|o
+ | | |S| |U|U|o
+ | | |H| |L|S|t
+ | |M|O| |D|T|n
+ | |U|U|M| | |o
+ | |S|L|A|N|N|t
+ | |T|D|Y|O|O|t
+FEATURE |SECTION | | | |T|T|e
+-----------------------------------------------|-----------|-|-|-|-|-|--
+Support SNMP or CMOT agent |6.3.1 | |x| | | |
+Implement specified objects in standard MIB |6.3.1 | |x| | | |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 92]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+7. REFERENCES
+
+ This section lists the primary references with which every
+ implementer must be thoroughly familiar. It also lists some
+ secondary references that are suggested additional reading.
+
+ INTRODUCTORY REFERENCES:
+
+
+ [INTRO:1] "Requirements for Internet Hosts -- Communication Layers,"
+ IETF Host Requirements Working Group, R. Braden, Ed., RFC-1122,
+ October 1989.
+
+ [INTRO:2] "DDN Protocol Handbook," NIC-50004, NIC-50005, NIC-50006,
+ (three volumes), SRI International, December 1985.
+
+ [INTRO:3] "Official Internet Protocols," J. Reynolds and J. Postel,
+ RFC-1011, May 1987.
+
+ This document is republished periodically with new RFC numbers;
+ the latest version must be used.
+
+ [INTRO:4] "Protocol Document Order Information," O. Jacobsen and J.
+ Postel, RFC-980, March 1986.
+
+ [INTRO:5] "Assigned Numbers," J. Reynolds and J. Postel, RFC-1010,
+ May 1987.
+
+ This document is republished periodically with new RFC numbers;
+ the latest version must be used.
+
+
+ TELNET REFERENCES:
+
+
+ [TELNET:1] "Telnet Protocol Specification," J. Postel and J.
+ Reynolds, RFC-854, May 1983.
+
+ [TELNET:2] "Telnet Option Specification," J. Postel and J. Reynolds,
+ RFC-855, May 1983.
+
+ [TELNET:3] "Telnet Binary Transmission," J. Postel and J. Reynolds,
+ RFC-856, May 1983.
+
+ [TELNET:4] "Telnet Echo Option," J. Postel and J. Reynolds, RFC-857,
+ May 1983.
+
+ [TELNET:5] "Telnet Suppress Go Ahead Option," J. Postel and J.
+
+
+
+Internet Engineering Task Force [Page 93]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ Reynolds, RFC-858, May 1983.
+
+ [TELNET:6] "Telnet Status Option," J. Postel and J. Reynolds, RFC-
+ 859, May 1983.
+
+ [TELNET:7] "Telnet Timing Mark Option," J. Postel and J. Reynolds,
+ RFC-860, May 1983.
+
+ [TELNET:8] "Telnet Extended Options List," J. Postel and J.
+ Reynolds, RFC-861, May 1983.
+
+ [TELNET:9] "Telnet End-Of-Record Option," J. Postel, RFC-855,
+ December 1983.
+
+ [TELNET:10] "Telnet Terminal-Type Option," J. VanBokkelen, RFC-1091,
+ February 1989.
+
+ This document supercedes RFC-930.
+
+ [TELNET:11] "Telnet Window Size Option," D. Waitzman, RFC-1073,
+ October 1988.
+
+ [TELNET:12] "Telnet Linemode Option," D. Borman, RFC-1116, August
+ 1989.
+
+ [TELNET:13] "Telnet Terminal Speed Option," C. Hedrick, RFC-1079,
+ December 1988.
+
+ [TELNET:14] "Telnet Remote Flow Control Option," C. Hedrick, RFC-
+ 1080, November 1988.
+
+
+ SECONDARY TELNET REFERENCES:
+
+
+ [TELNET:15] "Telnet Protocol," MIL-STD-1782, U.S. Department of
+ Defense, May 1984.
+
+ This document is intended to describe the same protocol as RFC-
+ 854. In case of conflict, RFC-854 takes precedence, and the
+ present document takes precedence over both.
+
+ [TELNET:16] "SUPDUP Protocol," M. Crispin, RFC-734, October 1977.
+
+ [TELNET:17] "Telnet SUPDUP Option," M. Crispin, RFC-736, October
+ 1977.
+
+ [TELNET:18] "Data Entry Terminal Option," J. Day, RFC-732, June 1977.
+
+
+
+Internet Engineering Task Force [Page 94]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ [TELNET:19] "TELNET Data Entry Terminal option -- DODIIS
+ Implementation," A. Yasuda and T. Thompson, RFC-1043, February
+ 1988.
+
+
+ FTP REFERENCES:
+
+
+ [FTP:1] "File Transfer Protocol," J. Postel and J. Reynolds, RFC-
+ 959, October 1985.
+
+ [FTP:2] "Document File Format Standards," J. Postel, RFC-678,
+ December 1974.
+
+ [FTP:3] "File Transfer Protocol," MIL-STD-1780, U.S. Department of
+ Defense, May 1984.
+
+ This document is based on an earlier version of the FTP
+ specification (RFC-765) and is obsolete.
+
+
+ TFTP REFERENCES:
+
+
+ [TFTP:1] "The TFTP Protocol Revision 2," K. Sollins, RFC-783, June
+ 1981.
+
+
+ MAIL REFERENCES:
+
+
+ [SMTP:1] "Simple Mail Transfer Protocol," J. Postel, RFC-821, August
+ 1982.
+
+ [SMTP:2] "Standard For The Format of ARPA Internet Text Messages,"
+ D. Crocker, RFC-822, August 1982.
+
+ This document obsoleted an earlier specification, RFC-733.
+
+ [SMTP:3] "Mail Routing and the Domain System," C. Partridge, RFC-
+ 974, January 1986.
+
+ This RFC describes the use of MX records, a mandatory extension
+ to the mail delivery process.
+
+ [SMTP:4] "Duplicate Messages and SMTP," C. Partridge, RFC-1047,
+ February 1988.
+
+
+
+
+Internet Engineering Task Force [Page 95]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ [SMTP:5a] "Mapping between X.400 and RFC 822," S. Kille, RFC-987,
+ June 1986.
+
+ [SMTP:5b] "Addendum to RFC-987," S. Kille, RFC-???, September 1987.
+
+ The two preceding RFC's define a proposed standard for
+ gatewaying mail between the Internet and the X.400 environments.
+
+ [SMTP:6] "Simple Mail Transfer Protocol," MIL-STD-1781, U.S.
+ Department of Defense, May 1984.
+
+ This specification is intended to describe the same protocol as
+ does RFC-821. However, MIL-STD-1781 is incomplete; in
+ particular, it does not include MX records [SMTP:3].
+
+ [SMTP:7] "A Content-Type Field for Internet Messages," M. Sirbu,
+ RFC-1049, March 1988.
+
+
+ DOMAIN NAME SYSTEM REFERENCES:
+
+
+ [DNS:1] "Domain Names - Concepts and Facilities," P. Mockapetris,
+ RFC-1034, November 1987.
+
+ This document and the following one obsolete RFC-882, RFC-883,
+ and RFC-973.
+
+ [DNS:2] "Domain Names - Implementation and Specification," RFC-1035,
+ P. Mockapetris, November 1987.
+
+
+ [DNS:3] "Mail Routing and the Domain System," C. Partridge, RFC-974,
+ January 1986.
+
+
+ [DNS:4] "DoD Internet Host Table Specification," K. Harrenstein,
+ RFC-952, M. Stahl, E. Feinler, October 1985.
+
+ SECONDARY DNS REFERENCES:
+
+
+ [DNS:5] "Hostname Server," K. Harrenstein, M. Stahl, E. Feinler,
+ RFC-953, October 1985.
+
+ [DNS:6] "Domain Administrators Guide," M. Stahl, RFC-1032, November
+ 1987.
+
+
+
+
+Internet Engineering Task Force [Page 96]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+ [DNS:7] "Domain Administrators Operations Guide," M. Lottor, RFC-
+ 1033, November 1987.
+
+ [DNS:8] "The Domain Name System Handbook," Vol. 4 of Internet
+ Protocol Handbook, NIC 50007, SRI Network Information Center,
+ August 1989.
+
+
+ SYSTEM INITIALIZATION REFERENCES:
+
+
+ [BOOT:1] "Bootstrap Loading Using TFTP," R. Finlayson, RFC-906, June
+ 1984.
+
+ [BOOT:2] "Bootstrap Protocol (BOOTP)," W. Croft and J. Gilmore, RFC-
+ 951, September 1985.
+
+ [BOOT:3] "BOOTP Vendor Information Extensions," J. Reynolds, RFC-
+ 1084, December 1988.
+
+ Note: this RFC revised and obsoleted RFC-1048.
+
+ [BOOT:4] "A Reverse Address Resolution Protocol," R. Finlayson, T.
+ Mann, J. Mogul, and M. Theimer, RFC-903, June 1984.
+
+
+ MANAGEMENT REFERENCES:
+
+
+ [MGT:1] "IAB Recommendations for the Development of Internet Network
+ Management Standards," V. Cerf, RFC-1052, April 1988.
+
+ [MGT:2] "Structure and Identification of Management Information for
+ TCP/IP-based internets," M. Rose and K. McCloghrie, RFC-1065,
+ August 1988.
+
+ [MGT:3] "Management Information Base for Network Management of
+ TCP/IP-based internets," M. Rose and K. McCloghrie, RFC-1066,
+ August 1988.
+
+ [MGT:4] "A Simple Network Management Protocol," J. Case, M. Fedor,
+ M. Schoffstall, and C. Davin, RFC-1098, April 1989.
+
+ [MGT:5] "The Common Management Information Services and Protocol
+ over TCP/IP," U. Warrier and L. Besaw, RFC-1095, April 1989.
+
+ [MGT:6] "Report of the Second Ad Hoc Network Management Review
+ Group," V. Cerf, RFC-1109, August 1989.
+
+
+
+Internet Engineering Task Force [Page 97]
+
+
+
+
+RFC1123 SUPPORT SERVICES -- MANAGEMENT October 1989
+
+
+Security Considerations
+
+ There are many security issues in the application and support
+ programs of host software, but a full discussion is beyond the scope
+ of this RFC. Security-related issues are mentioned in sections
+ concerning TFTP (Sections 4.2.1, 4.2.3.4, 4.2.3.5), the SMTP VRFY and
+ EXPN commands (Section 5.2.3), the SMTP HELO command (5.2.5), and the
+ SMTP DATA command (Section 5.2.8).
+
+Author's Address
+
+ Robert Braden
+ USC/Information Sciences Institute
+ 4676 Admiralty Way
+ Marina del Rey, CA 90292-6695
+
+ Phone: (213) 822 1511
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internet Engineering Task Force [Page 98]
+
diff --git a/lib/inets/doc/archive/rfc1945.html b/lib/inets/doc/archive/rfc1945.html
new file mode 100644
index 0000000000..cf88f53319
--- /dev/null
+++ b/lib/inets/doc/archive/rfc1945.html
@@ -0,0 +1,3035 @@
+<!--
+ ``The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved via the world wide web at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson Utvecklings AB.
+ Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
+ AB. All Rights Reserved.''
+
+ $Id$
+-->
+<HTML><HEAD>
+<TITLE>Hypertext Transfer Protocol -- HTTP/1.0</TITLE>
+</HEAD><BODY>
+<PRE>
+Network Working Group T. Berners-Lee, MIT/LCS
+Request for Comments: 1945 R. Fielding, UC Irvine
+Category: Informational H. Frystyk, MIT/LCS
+ May 1996
+</PRE>
+
+<H1 ALIGN=CENTER>Hypertext Transfer Protocol -- HTTP/1.0</H1>
+
+<H2><A NAME="Status">Status of this Memo</A></H2>
+
+ This memo provides information for the Internet community. This memo
+ does not specify an Internet standard of any kind. Distribution of
+ this memo is unlimited.
+
+<H2>IESG Note:</H2>
+
+ The IESG has concerns about this protocol, and expects this document
+ to be replaced relatively soon by a standards track document.
+
+<H2><A NAME="Abstract">Abstract</A></H2>
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and
+ speed necessary for distributed, collaborative, hypermedia information systems. It is a generic,
+ stateless, object-oriented protocol which can be used for many tasks, such as name servers and
+ distributed object management systems, through extension of its request methods (commands).
+ A feature of HTTP is the typing of data representation, allowing systems to be built
+ independently of the data being transferred.
+<P>
+
+ HTTP has been in use by the World-Wide Web global information initiative since 1990. This
+ specification reflects common usage of the protocol referred to as "HTTP/1.0".
+<P>
+
+<H2><A NAME="Contents">Table of Contents</A></H2>
+
+<PRE>
+1. <A HREF="#Introduction">Introduction</A>
+ 1.1 <A HREF="#Purpose">Purpose</A>
+ 1.2 <A HREF="#Terminology">Terminology</A>
+ 1.3 <A HREF="#Operation">Overall Operation</A>
+ 1.4 <A HREF="#HTTP-and-MIME">HTTP and MIME</A>
+
+2. <A HREF="#Grammar">Notational Conventions and Generic Grammar</A>
+ 2.1 <A HREF="#Augmented-BNF">Augmented BNF</A>
+ 2.2 <A HREF="#Basic-Rules">Basic Rules</A>
+
+3. <A HREF="#Protocol-Parameters">Protocol Parameters</A>
+ 3.1 <A HREF="#HTTP-Version">HTTP Version</A>
+ 3.2 <A HREF="#URI">Uniform Resource Identifiers</A>
+ 3.2.1 <A HREF="#URI-syntax">General Syntax</A>
+ 3.2.2 <A HREF="#http-URL">http URL</A>
+ 3.3 <A HREF="#DateFormats">Date/Time Formats</A>
+ 3.4 <A HREF="#Charset">Character Sets</A>
+ 3.5 <A HREF="#Content-Codings">Content Codings</A>
+ 3.6 <A HREF="#Media-Types">Media Types</A>
+ 3.6.1 <A HREF="#TextCanonicalization">Canonicalization and Text Defaults</A>
+ 3.6.2 <A HREF="#Multipart">Multipart Types</A>
+ 3.7 <A HREF="#Product">Product Tokens</A>
+
+4. <A HREF="#Message">HTTP Message</A>
+ 4.1 <A HREF="#Message-Types">Message Types</A>
+ 4.2 <A HREF="#Message-Headers">Message Headers</A>
+ 4.3 <A HREF="#General-Header">General Header Fields</A>
+
+5. <A HREF="#Request">Request</A>
+ 5.1 <A HREF="#Request-Line">Request-Line</A>
+ 5.1.1 <A HREF="#Method">Method</A>
+ 5.1.2 <A HREF="#Request-URI">Request-URI</A>
+ 5.2 <A HREF="#Request-Header">Request Header Fields</A>
+
+6. <A HREF="#Response">Response</A>
+ 6.1 <A HREF="#Status-Line">Status-Line</A>
+ 6.1.1 <A HREF="#Status-Code">Status Code and Reason Phrase</A>
+ 6.2 <A HREF="#Response-Header">Response Header Fields</A>
+
+7. <A HREF="#Entity">Entity</A>
+ 7.1 <A HREF="#Entity-Header">Entity Header Fields</A>
+ 7.2 <A HREF="#Entity-Body">Entity Body</A>
+ 7.2.1 <A HREF="#BodyType">Type</A>
+ 7.2.2 <A HREF="#BodyLength">Length</A>
+
+8. <A HREF="#Methods">Method Definitions</A>
+ 8.1 <A HREF="#GET">GET</A>
+ 8.2 <A HREF="#HEAD">HEAD</A>
+ 8.3 <A HREF="#POST">POST</A>
+
+9. <A HREF="#Status-Codes">Status Code Definitions</A>
+ 9.1 <A HREF="#Code1xx">Informational 1xx</A>
+ 9.2 <A HREF="#Code2xx">Successful 2xx</A>
+ <A HREF="#Code200">200 OK</A>
+ <A HREF="#Code201">201 Created</A>
+ <A HREF="#Code202">202 Accepted</A>
+ <A HREF="#Code204">204 No Content</A>
+ 9.3 <A HREF="#Code3xx">Redirection 3xx</A>
+ <A HREF="#Code300">300 Multiple Choices</A>
+ <A HREF="#Code301">301 Moved Permanently</A>
+ <A HREF="#Code302">302 Moved Temporarily</A>
+ <A HREF="#Code304">304 Not Modified</A>
+ 9.4 <A HREF="#Code4xx">Client Error 4xx</A>
+ <A HREF="#Code400">400 Bad Request</A>
+ <A HREF="#Code401">401 Unauthorized</A>
+ <A HREF="#Code403">403 Forbidden</A>
+ <A HREF="#Code404">404 Not Found</A>
+ 9.5 <A HREF="#Code5xx">Server Error 5xx</A>
+ <A HREF="#Code500">500 Internal Server Error</A>
+ <A HREF="#Code501">501 Not Implemented</A>
+ <A HREF="#Code502">502 Bad Gateway</A>
+ <A HREF="#Code503">503 Service Unavailable</A>
+
+10. <A HREF="#HeaderFields">Header Field Definitions</A>
+ 10.1 <A HREF="#Allow">Allow</A>
+ 10.2 <A HREF="#Authorization">Authorization</A>
+ 10.3 <A HREF="#Content-Encoding">Content-Encoding</A>
+ 10.4 <A HREF="#Content-Length">Content-Length</A>
+ 10.5 <A HREF="#Content-Type">Content-Type</A>
+ 10.6 <A HREF="#Date">Date</A>
+ 10.7 <A HREF="#Expires">Expires</A>
+ 10.8 <A HREF="#From">From</A>
+ 10.9 <A HREF="#If-Modified-Since">If-Modified-Since</A>
+ 10.10 <A HREF="#Last-Modified">Last-Modified</A>
+ 10.11 <A HREF="#Location">Location</A>
+ 10.12 <A HREF="#Pragma">Pragma</A>
+ 10.13 <A HREF="#Referer">Referer</A>
+ 10.14 <A HREF="#Server">Server</A>
+ 10.15 <A HREF="#User-Agent">User-Agent</A>
+ 10.16 <A HREF="#WWW-Authenticate">WWW-Authenticate</A>
+
+11. <A HREF="#AA">Access Authentication</A>
+ 11.1 <A HREF="#BasicAA">Basic Authentication Scheme</A>
+
+12. <A HREF="#Security">Security Considerations</A>
+ 12.1 <A HREF="#AuthSecurity">Authentication of Clients</A>
+ 12.2 <A HREF="#SafeMethods">Safe Methods</A>
+ 12.3 <A HREF="#LogAbuse">Abuse of Server Log Information</A>
+ 12.4 <A HREF="#Sensitive">Transfer of Sensitive Information</A>
+ 12.5 <A HREF="#PathNameSecurity">Attacks Based On File and Path Names</A>
+
+13. <A HREF="#Acknowledgments">Acknowledgments</A>
+
+14. <A HREF="#References">References</A>
+
+15. <A HREF="#Authors">Authors' Addresses</A>
+
+Appendix A. <A HREF="#message_http">Internet Media Type message/http</A>
+
+Appendix B. <A HREF="#Tolerant">Tolerant Applications</A>
+
+Appendix C. <A HREF="#MIME">Relationship to MIME</A>
+ C.1 <A HREF="#MIME-Canonical">Conversion to Canonical Form</A>
+ C.2 <A HREF="#MIME-Date">Conversion of Date Formats</A>
+ C.3 <A HREF="#MIME-CE">Introduction of Content-Encoding</A>
+ C.4 <A HREF="#MIME-CTE">No Content-Transfer-Encoding</A>
+ C.5 <A HREF="#MIME-parts">HTTP Header Fields in Multipart Body-Parts</A>
+
+Appendix D. <A HREF="#Additional">Additional Features</A>
+ D.1 <A HREF="#Additional-Methods">Additional Request Methods</A>
+ D.1.1 <A HREF="#PUT">PUT</A>
+ D.1.2 <A HREF="#DELETE">DELETE</A>
+ D.1.3 <A HREF="#LINK">LINK</A>
+ D.1.4 <A HREF="#UNLINK">UNLINK</A>
+ D.2 <A HREF="#Additional-Headers">Additional Header Field Definitions</A>
+ D.2.1 <A HREF="#Accept">Accept</A>
+ D.2.2 <A HREF="#Accept-Charset">Accept-Charset</A>
+ D.2.3 <A HREF="#Accept-Encoding">Accept-Encoding</A>
+ D.2.4 <A HREF="#Accept-Language">Accept-Language</A>
+ D.2.5 <A HREF="#Content-Language">Content-Language</A>
+ D.2.6 <A HREF="#Link">Link</A>
+ D.2.7 <A HREF="#MIME-Version">MIME-Version</A>
+ D.2.8 <A HREF="#Retry-After">Retry-After</A>
+ D.2.9 <A HREF="#Title">Title</A>
+ D.2.10 <A HREF="#URI-header">URI</A>
+
+
+</PRE>
+
+<H2>1. <A NAME="Introduction">Introduction</A></H2>
+
+<H3>1.1 <A NAME="Purpose">Purpose</A></H3>
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and
+ speed necessary for distributed, collaborative, hypermedia information systems. HTTP has
+ been in use by the World-Wide Web global information initiative since 1990. This specification
+ reflects common usage of the protocol referred to as "HTTP/1.0". This specification describes
+ the features that seem to be consistently implemented in most HTTP/1.0 clients and servers.
+ The specification is split into two sections. Those features of HTTP for which implementations
+ are usually consistent are described in the main body of this document. Those features which
+ have few or inconsistent implementations are listed in <A HREF="#Additional">Appendix D</A>.
+<P>
+
+ Practical information systems require more functionality than simple retrieval, including
+ search, front-end update, and annotation. HTTP allows an open-ended set of methods to be
+ used to indicate the purpose of a request. It builds on the discipline of reference provided by
+ the Uniform Resource Identifier (URI)<A HREF="#RefURI"> [2]</A>, as a location (URL)<A HREF="#RefURL"> [4]</A> or name (URN)<A HREF="#RefURN"> [16]</A>, for
+ indicating the resource on which a method is to be applied. Messages are passed in a format
+ similar to that used by Internet Mail<A HREF="#RefSTD11"> [7]</A> and the Multipurpose Internet Mail Extensions
+ (MIME)<A HREF="#RefMIME1"> [5]</A>.
+<P>
+
+ HTTP is also used as a generic protocol for communication between user agents and
+ proxies/gateways to other Internet protocols, such as SMTP<A HREF="#RefSMTP"> [12]</A>, NNTP<A HREF="#RefNNTP"> [11]</A>, FTP<A HREF="#RefFTP"> [14]</A>,
+ Gopher<A HREF="#RefGopher"> [1]</A>, and WAIS<A HREF="#RefWAIS"> [8]</A>, allowing basic hypermedia access to resources available from
+ diverse applications and simplifying the implementation of user agents.
+<P>
+
+<H3>1.2 <A NAME="Terminology">Terminology</A></H3>
+
+ This specification uses a number of terms to refer to the roles played by participants in, and
+ objects of, the HTTP communication.
+<P>
+
+<DL>
+<DT>connection
+<DD>A transport layer virtual circuit established between two application programs for the
+ purpose of communication.
+
+<P>
+<DT>message
+<DD>The basic unit of HTTP communication, consisting of a structured sequence of octets
+ matching the syntax defined in <A HREF="#Message">Section 4</A> and transmitted via the connection.
+
+<P>
+<DT>request
+<DD>An HTTP request message (as defined in <A HREF="#Request">Section 5</A>).
+
+<P>
+<DT>response
+<DD>An HTTP response message (as defined in <A HREF="#Response">Section 6</A>).
+
+<P>
+<DT>resource
+<DD>A network data object or service which can be identified by a URI (<A HREF="#URI">Section 3.2</A>).
+
+<P>
+<DT>entity
+<DD>A particular representation or rendition of a data resource, or reply from a service resource,
+ that may be enclosed within a request or response message. An entity consists of
+ metainformation in the form of entity headers and content in the form of an entity body.
+
+<P>
+<DT>client
+<DD>An application program that establishes connections for the purpose of sending requests.
+
+<P>
+<DT>user agent
+<DD>The client which initiates a request. These are often browsers, editors, spiders
+ (web-traversing robots), or other end user tools.
+
+<P>
+<DT>server
+<DD>An application program that accepts connections in order to service requests by sending
+ back responses.
+
+<P>
+<DT>origin server
+<DD>The server on which a given resource resides or is to be created.
+
+<P>
+<DT>proxy
+<DD>An intermediary program which acts as both a server and a client for the purpose of making
+ requests on behalf of other clients. Requests are serviced internally or by passing them, with
+ possible translation, on to other servers. A proxy must interpret and, if necessary, rewrite a
+ request message before forwarding it. Proxies are often used as client-side portals through
+ network firewalls and as helper applications for handling requests via protocols not
+ implemented by the user agent.
+
+<P>
+<DT>gateway
+<DD>A server which acts as an intermediary for some other server. Unlike a proxy, a gateway
+ receives requests as if it were the origin server for the requested resource; the requesting
+ client may not be aware that it is communicating with a gateway. Gateways are often used
+ as server-side portals through network firewalls and as protocol translators for access to
+ resources stored on non-HTTP systems.
+
+<P>
+<DT>tunnel
+<DD>A tunnel is an intermediary program which is acting as a blind relay between two
+ connections. Once active, a tunnel is not considered a party to the HTTP communication,
+ though the tunnel may have been initiated by an HTTP request. The tunnel ceases to exist
+ when both ends of the relayed connections are closed. Tunnels are used when a portal is
+ necessary and the intermediary cannot, or should not, interpret the relayed communication.
+
+<P>
+<DT>cache
+<DD>A program's local store of response messages and the subsystem that controls its message
+ storage, retrieval, and deletion. A cache stores cachable responses in order to reduce the
+ response time and network bandwidth consumption on future, equivalent requests. Any
+ client or server may include a cache, though a cache cannot be used by a server while it is
+ acting as a tunnel.
+</DL>
+
+ Any given program may be capable of being both a client and a server; our use of these terms
+ refers only to the role being performed by the program for a particular connection, rather than
+ to the program's capabilities in general. Likewise, any server may act as an origin server, proxy,
+ gateway, or tunnel, switching behavior based on the nature of each request.
+<P>
+
+<H3>1.3 <A NAME="Operation">Overall Operation</A></H3>
+
+ The HTTP protocol is based on a request/response paradigm. A client establishes a connection
+ with a server and sends a request to the server in the form of a request method, URI, and
+ protocol version, followed by a MIME-like message containing request modifiers, client
+ information, and possible body content. The server responds with a status line, including the
+ message's protocol version and a success or error code, followed by a MIME-like message
+ containing server information, entity metainformation, and possible body content.
+<P>
+
+ Most HTTP communication is initiated by a user agent and consists of a request to be applied
+ to a resource on some origin server. In the simplest case, this may be accomplished via a single
+ connection (v) between the user agent (UA) and the origin server (O).
+<P>
+
+<PRE>
+ request chain ------------------------&gt;
+ UA -------------------v------------------- O
+ &lt;----------------------- response chain
+</PRE>
+
+ A more complicated situation occurs when one or more intermediaries are present in the
+ request/response chain. There are three common forms of intermediary: proxy, gateway, and
+ tunnel. A proxy is a forwarding agent, receiving requests for a URI in its absolute form,
+ rewriting all or parts of the message, and forwarding the reformatted request toward the server
+ identified by the URI. A gateway is a receiving agent, acting as a layer above some other
+ server(s) and, if necessary, translating the requests to the underlying server's protocol. A tunnel
+ acts as a relay point between two connections without changing the messages; tunnels are used
+ when the communication needs to pass through an intermediary (such as a firewall) even when
+ the intermediary cannot understand the contents of the messages.
+<P>
+
+<PRE>
+ request chain --------------------------------------&gt;
+ UA -----v----- A -----v----- B -----v----- C -----v----- O
+ &lt;------------------------------------- response chain
+</PRE>
+
+ The figure above shows three intermediaries (A, B, and C) between the user agent and origin
+ server. A request or response message that travels the whole chain must pass through four
+ separate connections. This distinction is important because some HTTP communication
+ options may apply only to the connection with the nearest, non-tunnel neighbor, only to the
+ end-points of the chain, or to all connections along the chain. Although the diagram is linear,
+ each participant may be engaged in multiple, simultaneous communications. For example, B
+ may be receiving requests from many clients other than A, and/or forwarding requests to
+ servers other than C, at the same time that it is handling A's request.
+<P>
+
+ Any party to the communication which is not acting as a tunnel may employ an internal cache
+ for handling requests. The effect of a cache is that the request/response chain is shortened if
+ one of the participants along the chain has a cached response applicable to that request. The
+ following illustrates the resulting chain if B has a cached copy of an earlier response from O
+ (via C) for a request which has not been cached by UA or A.
+<P>
+
+<PRE>
+ request chain ----------&gt;
+ UA -----v----- A -----v----- B - - - - - - C - - - - - - O
+ &lt;--------- response chain
+</PRE>
+
+ Not all responses are cachable, and some requests may contain modifiers which place special
+ requirements on cache behavior. Some HTTP/1.0 applications use heuristics to describe what
+ is or is not a "cachable" response, but these rules are not standardized.
+<P>
+
+ On the Internet, HTTP communication generally takes place over TCP/IP connections. The
+ default port is TCP 80<A HREF="#RefIANA"> [15]</A>, but other ports can be used. This does not preclude HTTP from
+ being implemented on top of any other protocol on the Internet, or on other networks. HTTP
+ only presumes a reliable transport; any protocol that provides such guarantees can be used, and
+ the mapping of the HTTP/1.0 request and response structures onto the transport data units of
+ the protocol in question is outside the scope of this specification.
+<P>
+
+ Except for experimental applications, current practice requires that the connection be
+ established by the client prior to each request and closed by the server after sending the
+ response. Both clients and servers should be aware that either party may close the connection
+ prematurely, due to user action, automated time-out, or program failure, and should handle
+ such closing in a predictable fashion. In any case, the closing of the connection by either or both
+ parties always terminates the current request, regardless of its status.
+<P>
+
+<H3>1.4 <A NAME="HTTP-and-MIME">HTTP and MIME</A></H3>
+
+ HTTP/1.0 uses many of the constructs defined for MIME, as defined in RFC 1521<A HREF="#RefMIME1"> [5]</A>.
+ <A HREF="#MIME">Appendix C</A> describes the ways in which the context of HTTP allows for different use of
+ Internet Media Types than is typically found in Internet mail, and gives the rationale for those
+ differences.
+<P>
+
+<H2>2. <A NAME="Grammar">Notational Conventions and Generic Grammar</A></H2>
+
+<H3>2.1 <A NAME="Augmented-BNF">Augmented BNF</A></H3>
+
+ All of the mechanisms specified in this document are described in both prose and an augmented
+ Backus-Naur Form (BNF) similar to that used by RFC 822<A HREF="#RefSTD11"> [7]</A>. Implementors will need to be
+ familiar with the notation in order to understand this specification. The augmented BNF
+ includes the following constructs:
+<P>
+
+<DL>
+<DT><CODE>name = definition</CODE>
+<DD>The name of a rule is simply the name itself (without any enclosing <CODE>"&lt;"</CODE> and <CODE>"&gt;"</CODE>) and is
+ separated from its definition by the equal character <CODE>"="</CODE>. Whitespace is only significant in
+ that indentation of continuation lines is used to indicate a rule definition that spans more
+ than one line. Certain basic rules are in uppercase, such as <CODE>SP</CODE>, <CODE>LWS</CODE>, <CODE>HT</CODE>, <CODE>CRLF</CODE>, <CODE>DIGIT</CODE>,
+ <CODE>ALPHA</CODE>, etc. Angle brackets are used within definitions whenever their presence will
+ facilitate discerning the use of rule names.
+
+<P>
+<DT><CODE>"literal"</CODE>
+<DD>Quotation marks surround literal text. Unless stated otherwise, the text is case-insensitive.
+
+<P>
+<DT><CODE>rule1 | rule2</CODE>
+<DD>Elements separated by a bar (<CODE>"I"</CODE>) are alternatives, e.g., <CODE>"yes | no"</CODE> will accept <CODE>yes</CODE> or <CODE>no</CODE>.
+
+<P>
+<DT><CODE>(rule1 rule2)</CODE>
+<DD>Elements enclosed in parentheses are treated as a single element. Thus,
+ <CODE>"(elem (foo | bar) elem)"</CODE> allows the token sequences <CODE>"elem foo elem"</CODE> and <CODE>"elem bar elem"</CODE>.
+
+<P>
+<DT><CODE>*rule</CODE>
+<DD>The character <CODE>"*"</CODE> preceding an element indicates repetition. The full form is
+ <CODE>"&lt;n&gt;*&lt;m&gt;element"</CODE> indicating at least <CODE>&lt;n&gt;</CODE> and at most <CODE>&lt;m&gt;</CODE> occurrences of <CODE>element</CODE>. Default
+ values are <CODE>0</CODE> and infinity so that <CODE>"*(element)"</CODE> allows any number, including zero; <CODE>"1*element"</CODE>
+ requires at least one; and <CODE>"1*2element"</CODE> allows one or two.
+
+<P>
+<DT><CODE>[rule]</CODE>
+<DD>Square brackets enclose optional elements; <CODE>"[foo bar]"</CODE> is equivalent to <CODE>"*1(foo bar)"</CODE>.
+
+<P>
+<DT><EM>N</EM> <CODE>rule</CODE>
+<DD>Specific repetition: <CODE>"&lt;n&gt;(element)"</CODE> is equivalent to <CODE>"&lt;n&gt;*&lt;n&gt;(element)"</CODE>; that is, exactly <CODE>&lt;n&gt;</CODE>
+ occurrences of <CODE>(element)</CODE>. Thus <CODE>2DIGIT</CODE> is a 2-digit number, and <CODE>3ALPHA</CODE> is a string of three
+ alphabetic characters.
+
+<P>
+<DT><CODE>#rule</CODE>
+<DD>A construct <CODE>"#"</CODE> is defined, similar to <CODE>"*"</CODE>, for defining lists of elements. The full form is
+ <CODE>"&lt;n&gt;#&lt;m&gt;element"</CODE> indicating at least <CODE>&lt;n&gt;</CODE> and at most <CODE>&lt;m&gt;</CODE> elements, each separated by one
+ or more commas (<CODE>","</CODE>) and optional linear whitespace (LWS). This makes the usual form of
+ lists very easy; a rule such as <CODE>"( *LWS element *( *LWS "," *LWS element ))</CODE>" can be shown as
+ <CODE>"1#element"</CODE>. Wherever this construct is used, null elements are allowed, but do not
+ contribute to the count of elements present. That is, <CODE>"(element), , (element)"</CODE> is permitted, but
+ counts as only two elements. Therefore, where at least one element is required, at least one
+ non-null element must be present. Default values are <CODE>0</CODE> and infinity so that <CODE>"#(element)"</CODE>
+ allows any number, including zero; <CODE>"1#element"</CODE> requires at least one; and <CODE>"1#2element"</CODE>
+ allows one or two.
+
+<P>
+<DT><CODE>; comment</CODE>
+<DD>A semi-colon, set off some distance to the right of rule text, starts a comment that continues
+ to the end of line. This is a simple way of including useful notes in parallel with the
+ specifications.
+
+<P>
+<DT><CODE>implied *LWS</CODE>
+<DD>The grammar described by this specification is word-based. Except where noted otherwise,
+ linear whitespace (<CODE>LWS</CODE>) can be included between any two adjacent words (<CODE>token</CODE> or
+ <CODE>quoted-string</CODE>), and between adjacent tokens and delimiters (<CODE>tspecials</CODE>), without changing the
+ interpretation of a field. At least one delimiter (<CODE>tspecials</CODE>) must exist between any two
+ tokens, since they would otherwise be interpreted as a single token. However, applications
+ should attempt to follow "common form" when generating HTTP constructs, since there
+ exist some implementations that fail to accept anything beyond the common forms.
+</DL>
+
+<H3>2.2 <A NAME="Basic-Rules">Basic Rules</A></H3>
+
+ The following rules are used throughout this specification to describe basic parsing constructs.
+ The US-ASCII coded character set is defined by<A HREF="#RefASCII"> [17]</A>.
+<P>
+
+<PRE>
+ OCTET = &lt;any 8-bit sequence of data&gt;
+ CHAR = &lt;any US-ASCII character (octets 0 - 127)&gt;
+ UPALPHA = &lt;any US-ASCII uppercase letter "A".."Z"&gt;
+ LOALPHA = &lt;any US-ASCII lowercase letter "a".."z"&gt;
+ ALPHA = UPALPHA | LOALPHA
+ DIGIT = &lt;any US-ASCII digit "0".."9"&gt;
+ CTL = &lt;any US-ASCII control character
+ (octets 0 - 31) and DEL (127)&gt;
+ CR = &lt;US-ASCII CR, carriage return (13)&gt;
+ LF = &lt;US-ASCII LF, linefeed (10)&gt;
+ SP = &lt;US-ASCII SP, space (32)&gt;
+ HT = &lt;US-ASCII HT, horizontal-tab (9)&gt;
+ &lt;"&gt; = &lt;US-ASCII double-quote mark (34)&gt;
+</PRE>
+
+ HTTP/1.0 defines the octet sequence <CODE>CR LF</CODE> as the end-of-line marker for all protocol elements
+ except the <CODE>Entity-Body</CODE> (see <A HREF="#Tolerant">Appendix B</A> for tolerant applications). The end-of-line marker
+ within an <CODE>Entity-Body</CODE> is defined by its associated media type, as described in <A HREF="#Media-Types">Section 3.6</A>.
+<P>
+
+<PRE>
+ CRLF = CR LF
+</PRE>
+
+ HTTP/1.0 headers may be folded onto multiple lines if each continuation line begins with a
+ space or horizontal tab. All linear whitespace, including folding, has the same semantics as <CODE>SP</CODE>.
+<P>
+
+<PRE>
+ LWS = [CRLF] 1*( SP | HT )
+</PRE>
+
+ However, folding of header lines is not expected by some applications, and should not be
+ generated by HTTP/1.0 applications.
+<P>
+
+ The <CODE>TEXT</CODE> rule is only used for descriptive field contents and values that are not intended to be
+ interpreted by the message parser. Words of <CODE>*TEXT</CODE> may contain octets from character sets other
+ than US-ASCII.
+<P>
+
+<PRE>
+ TEXT = &lt;any OCTET except CTLs,
+ but including LWS&gt;
+</PRE>
+
+ Recipients of header field <CODE>TEXT</CODE> containing octets outside the US-ASCII character set may
+ assume that they represent ISO-8859-1 characters.
+<P>
+
+ Hexadecimal numeric characters are used in several protocol elements.
+<P>
+
+<PRE>
+ HEX = "A" | "B" | "C" | "D" | "E" | "F"
+ | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
+</PRE>
+
+ Many HTTP/1.0 header field values consist of words separated by <CODE>LWS</CODE> or special characters.
+ These special characters must be in a quoted string to be used within a parameter value.
+<P>
+
+<PRE>
+ word = token | quoted-string
+</PRE>
+
+<PRE>
+ token = 1*&lt;any CHAR except CTLs or tspecials&gt;
+</PRE>
+
+<PRE>
+ tspecials = "(" | ")" | "&lt;" | "&gt;" | "@"
+ | "," | ";" | ":" | "\" | &lt;"&gt;
+ | "/" | "[" | "]" | "?" | "="
+ | "{" | "}" | SP | HT
+</PRE>
+
+ Comments may be included in some HTTP header fields by surrounding the comment text with
+ parentheses. Comments are only allowed in fields containing "<CODE>comment</CODE>" as part of their field
+ value definition. In all other fields, parentheses are considered part of the field value.
+<P>
+
+<PRE>
+ comment = "(" *( ctext | comment ) ")"
+ ctext = &lt;any TEXT excluding "(" and ")"&gt;
+</PRE>
+
+ A string of text is parsed as a single word if it is quoted using double-quote marks.
+<P>
+
+<PRE>
+ quoted-string = ( &lt;"&gt; *(qdtext) &lt;"&gt; )
+</PRE>
+
+<PRE>
+ qdtext = &lt;any CHAR except &lt;"&gt; and CTLs,
+ but including LWS&gt;
+</PRE>
+
+ Single-character quoting using the backslash ("\") character is not permitted in HTTP/1.0.
+<P>
+
+<H2>3. <A NAME="Protocol-Parameters">Protocol Parameters</A></H2>
+
+<H3>3.1 <A NAME="HTTP-Version">HTTP Version</A></H3>
+
+ HTTP uses a "&lt;major&gt;.&lt;minor&gt;" numbering scheme to indicate versions of the protocol. The
+ protocol versioning policy is intended to allow the sender to indicate the format of a message
+ and its capacity for understanding further HTTP communication, rather than the features
+ obtained via that communication. No change is made to the version number for the addition of
+ message components which do not affect communication behavior or which only add to
+ extensible field values. The &lt;minor&gt; number is incremented when the changes made to the
+ protocol add features which do not change the general message parsing algorithm, but which
+ may add to the message semantics and imply additional capabilities of the sender. The &lt;major&gt;
+ number is incremented when the format of a message within the protocol is changed.
+<P>
+
+ The version of an HTTP message is indicated by an <CODE>HTTP-Version</CODE> field in the first line of the
+ message. If the protocol version is not specified, the recipient must assume that the message is
+ in the simple HTTP/0.9 format.
+<P>
+
+<PRE>
+ HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
+</PRE>
+
+ Note that the major and minor numbers should be treated as separate integers and that each may
+ be incremented higher than a single digit. Thus, HTTP/2.4 is a lower version than HTTP/2.13,
+ which in turn is lower than HTTP/12.3. Leading zeros should be ignored by recipients and
+ never generated by senders.
+<P>
+
+ This document defines both the 0.9 and 1.0 versions of the HTTP protocol. Applications
+ sending <CODE>Full-Request</CODE> or <CODE>Full-Response</CODE> messages, as defined by this specification, must include
+ an <CODE>HTTP-Version</CODE> of "<CODE>HTTP/1.0</CODE>".
+<P>
+
+HTTP/1.0 servers must:
+<UL>
+<LI>recognize the format of the <CODE>Request-Line</CODE> for HTTP/0.9 and HTTP/1.0 requests;
+<LI>understand any valid request in the format of HTTP/0.9 or HTTP/1.0;
+<LI>respond appropriately with a message in the same protocol version used by the client.
+</UL>
+
+HTTP/1.0 clients must:
+<UL>
+<LI>recognize the format of the <CODE>Status-Line</CODE> for HTTP/1.0 responses;
+<LI>understand any valid response in the format of HTTP/0.9 or HTTP/1.0.
+</UL>
+
+ Proxy and gateway applications must be careful in forwarding requests that are received in a
+ format different than that of the application's native HTTP version. Since the protocol version
+ indicates the protocol capability of the sender, a proxy/gateway must never send a message
+ with a version indicator which is greater than its native version; if a higher version request is
+ received, the proxy/gateway must either downgrade the request version or respond with an
+ error. Requests with a version lower than that of the application's native format may be
+ upgraded before being forwarded; the proxy/gateway's response to that request must follow the
+ server requirements listed above.
+<P>
+
+<H3>3.2 <A NAME="URI">Uniform Resource Identifiers</A></H3>
+
+ URIs have been known by many names: WWW addresses, Universal Document Identifiers,
+ Universal Resource Identifiers<A HREF="#RefURI"> [2]</A>, and finally the combination of Uniform Resource Locators
+ (URL)<A HREF="#RefURL"> [4]</A> and Names (URN)<A HREF="#RefURN"> [16]</A>. As far as HTTP is concerned, Uniform Resource Identifiers
+ are simply formatted strings which identify--via name, location, or any other characteristic--a
+ network resource.
+<P>
+
+<H4>3.2.1 <A NAME="URI-syntax">General Syntax</A></H4>
+
+ URIs in HTTP can be represented in absolute form or relative to some known base URI<A HREF="#RefRelURL"> [9]</A>,
+ depending upon the context of their use. The two forms are differentiated by the fact that
+ absolute URIs always begin with a scheme name followed by a colon.
+<P>
+
+<PRE>
+ URI = ( absoluteURI | relativeURI ) [ "#" fragment ]
+</PRE>
+
+<PRE>
+ absoluteURI = scheme ":" *( uchar | reserved )
+</PRE>
+
+<PRE>
+ relativeURI = net_path | abs_path | rel_path
+</PRE>
+
+<PRE>
+ net_path = "//" net_loc [ abs_path ]
+ abs_path = "/" rel_path
+ rel_path = [ path ] [ ";" params ] [ "?" query ]
+</PRE>
+
+<PRE>
+ path = fsegment *( "/" segment )
+ fsegment = 1*pchar
+ segment = *pchar
+</PRE>
+
+<PRE>
+ params = param *( ";" param )
+ param = *( pchar | "/" )
+</PRE>
+
+<PRE>
+ scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." )
+ net_loc = *( pchar | ";" | "?" )
+ query = *( uchar | reserved )
+ fragment = *( uchar | reserved )
+</PRE>
+
+<PRE>
+ pchar = uchar | ":" | "@" | "&amp;" | "=" | "+"
+ uchar = unreserved | escape
+ unreserved = ALPHA | DIGIT | safe | extra | national
+</PRE>
+
+<PRE>
+ escape = "%" HEX HEX
+ reserved = ";" | "/" | "?" | ":" | "@" | "&amp;" | "=" | "+"
+ extra = "!" | "*" | "'" | "(" | ")" | ","
+ safe = "$" | "-" | "_" | "."
+ unsafe = CTL | SP | &lt;"&gt; | "#" | "%" | "&lt;" | "&gt;"
+ national = &lt;any OCTET excluding ALPHA, DIGIT,
+ reserved, extra, safe, and unsafe&gt;
+</PRE>
+
+ For definitive information on URL syntax and semantics, see RFC 1738<A HREF="#RefURL"> [4]</A> and RFC 1808<A HREF="#RefRelURL"> [9]</A>.
+ The BNF above includes <CODE>national</CODE> characters not allowed in valid URLs as specified by
+ RFC 1738, since HTTP servers are not restricted in the set of <CODE>unreserved</CODE> characters allowed to
+ represent the <CODE>rel_path</CODE> part of addresses, and HTTP proxies may receive requests for URIs not
+ defined by RFC 1738.
+<P>
+
+<H4>3.2.2 <A NAME="http-URL">http URL</A></H4>
+
+ The "http" scheme is used to locate network resources via the HTTP protocol. This section
+ defines the scheme-specific syntax and semantics for http URLs.
+<P>
+
+<PRE>
+ http_URL = "http:" "//" host [ ":" port ] [ abs_path ]
+</PRE>
+
+<PRE>
+ host = &lt;A legal Internet host domain name
+ or IP address (in dotted-decimal form),
+ as defined by Section 2.1 of RFC 1123&gt;
+</PRE>
+
+<PRE>
+ port = *DIGIT
+</PRE>
+
+ If the <CODE>port</CODE> is empty or not given, port 80 is assumed. The semantics are that the identified
+ resource is located at the server listening for TCP connections on that <CODE>port</CODE> of that <CODE>host</CODE>, and the
+ <CODE>Request-URI</CODE> for the resource is <CODE>abs_path</CODE>. If the <CODE>abs_path</CODE> is not present in the URL, it must be
+ given as "/" when used as a <CODE>Request-URI</CODE> (<A HREF="#Request-URI">Section 5.1.2</A>).
+<P>
+
+<BLOCKQUOTE>
+ Note: Although the HTTP protocol is independent of the transport layer protocol, the
+ http URL only identifies resources by their TCP location, and thus non-TCP resources
+ must be identified by some other URI scheme.
+</BLOCKQUOTE>
+
+ The canonical form for "http" URLs is obtained by converting any <CODE>UPALPHA</CODE> characters in <CODE>host</CODE>
+ to their <CODE>LOALPHA</CODE> equivalent (hostnames are case-insensitive), eliding the <CODE>[ ":" port ]</CODE> if the port
+ is 80, and replacing an empty <CODE>abs_path</CODE> with "/".
+<P>
+
+<H3>3.3 <A NAME="DateFormats">Date/Time Formats</A></H3>
+
+ HTTP/1.0 applications have historically allowed three different formats for the representation
+ of date/time stamps:
+<P>
+
+<PRE>
+ Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
+ Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
+ Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
+</PRE>
+
+ The first format is preferred as an Internet standard and represents a fixed-length subset of that
+ defined by RFC 1123<A HREF="#RefSTD3"> [6]</A> (an update to RFC 822<A HREF="#RefSTD11"> [7]</A>). The second format is in common use, but
+ is based on the obsolete RFC 850<A HREF="#RefUSENET"> [10]</A> date format and lacks a four-digit year. HTTP/1.0 clients
+ and servers that parse the date value should accept all three formats, though they must never
+ generate the third (asctime) format.
+<P>
+
+<BLOCKQUOTE>
+ Note: Recipients of date values are encouraged to be robust in accepting date values
+ that may have been generated by non-HTTP applications, as is sometimes the case
+ when retrieving or posting messages via proxies/gateways to SMTP or NNTP.
+</BLOCKQUOTE>
+
+ All HTTP/1.0 date/time stamps must be represented in Universal Time (UT), also known as
+ Greenwich Mean Time (GMT), without exception. This is indicated in the first two formats by
+ the inclusion of "GMT" as the three-letter abbreviation for time zone, and should be assumed
+ when reading the asctime format.
+<P>
+
+<PRE>
+ HTTP-date = rfc1123-date | rfc850-date | asctime-date
+</PRE>
+
+<PRE>
+ rfc1123-date = wkday "," SP date1 SP time SP "GMT"
+ rfc850-date = weekday "," SP date2 SP time SP "GMT"
+ asctime-date = wkday SP date3 SP time SP 4DIGIT
+</PRE>
+
+<PRE>
+ date1 = 2DIGIT SP month SP 4DIGIT
+ ; day month year (e.g., 02 Jun 1982)
+ date2 = 2DIGIT "-" month "-" 2DIGIT
+ ; day-month-year (e.g., 02-Jun-82)
+ date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
+ ; month day (e.g., Jun 2)
+</PRE>
+
+<PRE>
+ time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+ ; 00:00:00 - 23:59:59
+</PRE>
+
+<PRE>
+ wkday = "Mon" | "Tue" | "Wed"
+ | "Thu" | "Fri" | "Sat" | "Sun"
+</PRE>
+
+<PRE>
+ weekday = "Monday" | "Tuesday" | "Wednesday"
+ | "Thursday" | "Friday" | "Saturday" | "Sunday"
+</PRE>
+
+<PRE>
+ month = "Jan" | "Feb" | "Mar" | "Apr"
+ | "May" | "Jun" | "Jul" | "Aug"
+ | "Sep" | "Oct" | "Nov" | "Dec"
+</PRE>
+
+<BLOCKQUOTE>
+ Note: HTTP requirements for the date/time stamp format apply only to their usage
+ within the protocol stream. Clients and servers are not required to use these formats
+ for user presentation, request logging, etc.
+</BLOCKQUOTE>
+
+<H3>3.4 <A NAME="Charset">Character Sets</A></H3>
+
+ HTTP uses the same definition of the term "character set" as that described for MIME:
+<P>
+
+<BLOCKQUOTE>
+ The term "character set" is used in this document to refer to a method used with
+ one or more tables to convert a sequence of octets into a sequence of characters.
+ Note that unconditional conversion in the other direction is not required, in that
+ not all characters may be available in a given character set and a character set may
+ provide more than one sequence of octets to represent a particular character. This
+ definition is intended to allow various kinds of character encodings, from simple
+ single-table mappings such as US-ASCII to complex table switching methods
+ such as those that use ISO 2022's techniques. However, the definition associated
+ with a MIME character set name must fully specify the mapping to be performed
+ from octets to characters. In particular, use of external profiling information to
+ determine the exact mapping is not permitted.
+</BLOCKQUOTE>
+
+<BLOCKQUOTE>
+ Note: This use of the term "character set" is more commonly referred to as a
+ "character encoding." However, since HTTP and MIME share the same registry, it is
+ important that the terminology also be shared.
+</BLOCKQUOTE>
+
+ HTTP character sets are identified by case-insensitive tokens. The complete set of tokens are
+ defined by the IANA Character Set registry<A HREF="#RefIANA"> [15]</A>. However, because that registry does not
+ define a single, consistent token for each character set, we define here the preferred names for
+ those character sets most likely to be used with HTTP entities. These character sets include
+ those registered by RFC 1521<A HREF="#RefMIME1"> [5]</A> -- the US-ASCII<A HREF="#RefASCII"> [17]</A>
+ and ISO-8859<A HREF="#RefISO8859"> [18]</A> character sets --
+ and other names specifically recommended for use within MIME charset parameters.
+<P>
+
+<PRE>
+ charset = "US-ASCII"
+ | "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3"
+ | "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6"
+ | "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9"
+ | "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR"
+ | "UNICODE-1-1" | "UNICODE-1-1-UTF-7" | "UNICODE-1-1-UTF-8"
+ | token
+</PRE>
+
+ Although HTTP allows an arbitrary token to be used as a charset value, any token that has a
+ predefined value within the IANA Character Set registry<A HREF="#RefIANA"> [15]</A> must represent the character set
+ defined by that registry. Applications should limit their use of character sets to those defined by
+ the IANA registry.
+<P>
+
+ The character set of an entity body should be labelled as the lowest common denominator of
+ the character codes used within that body, with the exception that no label is preferred over the
+ labels US-ASCII or ISO-8859-1.
+<P>
+
+<H3>3.5 <A NAME="Content-Codings">Content Codings</A></H3>
+
+ Content coding values are used to indicate an encoding transformation that has been applied to
+ a resource. Content codings are primarily used to allow a document to be compressed or
+ encrypted without losing the identity of its underlying media type. Typically, the resource is
+ stored in this encoding and only decoded before rendering or analogous usage.
+<P>
+
+<PRE>
+ content-coding = "x-gzip" | "x-compress" | token
+</PRE>
+
+<BLOCKQUOTE>
+ Note: For future compatibility, HTTP/1.0 applications should consider "gzip" and
+ "compress" to be equivalent to "x-gzip" and "x-compress", respectively.
+</BLOCKQUOTE>
+
+ All <CODE>content-coding</CODE> values are case-insensitive. HTTP/1.0 uses <CODE>content-coding</CODE> values in the
+ <CODE>Content-Encoding</CODE> (<A HREF="#Content-Encoding">Section 10.3</A>) header field. Although the value describes the content-coding,
+ what is more important is that it indicates what decoding mechanism will be required to remove
+ the encoding. Note that a single program may be capable of decoding multiple content-coding
+ formats. Two values are defined by this specification:
+<P>
+
+<DL>
+<DT><CODE>x-gzip</CODE>
+<DD>An encoding format produced by the file compression program "gzip" (GNU zip)
+ developed by Jean-loup Gailly. This format is typically a Lempel-Ziv coding (LZ77) with
+ a 32 bit CRC.
+
+<P>
+<DT><CODE>x-compress</CODE>
+<DD>The encoding format produced by the file compression program "compress". This format
+ is an adaptive Lempel-Ziv-Welch coding (LZW).
+</DL>
+
+<BLOCKQUOTE>
+ Note: Use of program names for the identification of encoding formats is not
+ desirable and should be discouraged for future encodings. Their use here is
+ representative of historical practice, not good design.
+</BLOCKQUOTE>
+
+<H3>3.6 <A NAME="Media-Types">Media Types</A></H3>
+
+ HTTP uses Internet Media Types<A HREF="#RefMediaType"> [13]</A> in the <CODE>Content-Type</CODE> header field (<A HREF="#Content-Type">Section 10.5</A>) in order
+ to provide open and extensible data typing.
+<P>
+
+<PRE>
+ media-type = type "/" subtype *( ";" parameter )
+ type = token
+ subtype = token
+</PRE>
+
+ Parameters may follow the type/subtype in the form of attribute/value pairs.
+<P>
+
+<PRE>
+ parameter = attribute "=" value
+ attribute = token
+ value = token | quoted-string
+</PRE>
+
+ The type, subtype, and parameter attribute names are case-insensitive. Parameter values may
+ or may not be case-sensitive, depending on the semantics of the parameter name. <CODE>LWS</CODE> must not
+ be generated between the type and subtype, nor between an attribute and its value. Upon receipt
+ of a media type with an unrecognized parameter, a user agent should treat the media type as if
+ the unrecognized parameter and its value were not present.
+<P>
+
+ Some older HTTP applications do not recognize media type parameters. HTTP/1.0
+ applications should only use media type parameters when they are necessary to define the
+ content of a message.
+<P>
+
+ Media-type values are registered with the Internet Assigned Number Authority (IANA<A HREF="#RefIANA"> [15]</A>).
+ The media type registration process is outlined in RFC 1590<A HREF="#RefMediaType"> [13]</A>. Use of non-registered media
+ types is discouraged.
+<P>
+
+<H4>3.6.1 <A NAME="TextCanonicalization">Canonicalization and Text Defaults</A></H4>
+
+ Internet media types are registered with a canonical form. In general, an <CODE>Entity-Body</CODE> transferred
+ via HTTP must be represented in the appropriate canonical form prior to its transmission. If the
+ body has been encoded with a <CODE>Content-Encoding</CODE>, the underlying data should be in canonical
+ form prior to being encoded.
+<P>
+
+ Media subtypes of the "text" type use <CODE>CRLF</CODE> as the text line break when in canonical form.
+ However, HTTP allows the transport of text media with plain <CODE>CR</CODE> or <CODE>LF</CODE> alone representing a line
+ break when used consistently within the <CODE>Entity-Body</CODE>. HTTP applications must accept <CODE>CRLF</CODE>, bare
+ <CODE>CR</CODE>, and bare <CODE>LF</CODE> as being representative of a line break in text media received via HTTP.
+<P>
+
+ In addition, if the text media is represented in a character set that does not use octets 13 and 10
+ for <CODE>CR</CODE> and <CODE>LF</CODE> respectively, as is the case for some multi-byte character sets, HTTP allows the
+ use of whatever octet sequences are defined by that character set to represent the equivalent of
+ <CODE>CR</CODE> and <CODE>LF</CODE> for line breaks. This flexibility regarding line breaks applies only to text media in
+ the <CODE>Entity-Body</CODE>; a bare <CODE>CR</CODE> or <CODE>LF</CODE> should not be substituted for <CODE>CRLF</CODE> within any of the HTTP
+ control structures (such as header fields and multipart boundaries).
+<P>
+
+ The "charset" parameter is used with some media types to define the character set (<A HREF="#Charset">Section 3.4</A>)
+ of the data. When no explicit charset parameter is provided by the sender, media subtypes of
+ the "text" type are defined to have a default charset value of "ISO-8859-1" when received via
+ HTTP. Data in character sets other than "ISO-8859-1" or its subsets must be labelled with an
+ appropriate charset value in order to be consistently interpreted by the recipient.
+<P>
+
+<BLOCKQUOTE>
+ Note: Many current HTTP servers provide data using charsets other than
+ "ISO-8859-1" without proper labelling. This situation reduces interoperability and is
+ not recommended. To compensate for this, some HTTP user agents provide a
+ configuration option to allow the user to change the default interpretation of the
+ media type character set when no charset parameter is given.
+</BLOCKQUOTE>
+
+<H4>3.6.2 <A NAME="Multipart">Multipart Types</A></H4>
+
+ MIME provides for a number of "multipart" types -- encapsulations of several entities within
+ a single message's <CODE>Entity-Body</CODE>. The multipart types registered by IANA<A HREF="#RefIANA"> [15]</A> do not have any
+ special meaning for HTTP/1.0, though user agents may need to understand each type in order
+ to correctly interpret the purpose of each body-part. An HTTP user agent should follow the
+ same or similar behavior as a MIME user agent does upon receipt of a multipart type. HTTP
+ servers should not assume that all HTTP clients are prepared to handle multipart types.
+<P>
+
+ All multipart types share a common syntax and must include a boundary parameter as part of
+ the media type value. The message body is itself a protocol element and must therefore use only
+ <CODE>CRLF</CODE> to represent line breaks between body-parts. Multipart body-parts may contain HTTP
+ header fields which are significant to the meaning of that part.
+<P>
+
+<H3>3.7 <A NAME="Product">Product Tokens</A></H3>
+
+ Product tokens are used to allow communicating applications to identify themselves via a
+ simple product token, with an optional slash and version designator. Most fields using product
+ tokens also allow subproducts which form a significant part of the application to be listed,
+ separated by whitespace. By convention, the products are listed in order of their significance
+ for identifying the application.
+<P>
+
+<PRE>
+ product = token ["/" product-version]
+ product-version = token
+</PRE>
+
+ Examples:
+<P>
+
+<PRE>
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+
+ Server: Apache/0.8.4
+</PRE>
+
+ Product tokens should be short and to the point -- use of them for advertizing or other
+ non-essential information is explicitly forbidden. Although any token character may appear in
+ a <CODE>product-version</CODE>, this token should only be used for a version identifier (i.e., successive versions
+ of the same product should only differ in the <CODE>product-version</CODE> portion of the <CODE>product</CODE> value).
+<P>
+
+<H2>4. <A NAME="Message">HTTP Message</A></H2>
+
+<H3>4.1 <A NAME="Message-Types">Message Types</A></H3>
+
+ HTTP messages consist of requests from client to server and responses from server to client.
+<P>
+
+<PRE>
+ HTTP-message = Simple-Request ; HTTP/0.9 messages
+ | Simple-Response
+ | Full-Request ; HTTP/1.0 messages
+ | Full-Response
+</PRE>
+
+ <CODE>Full-Request</CODE> and <CODE>Full-Response</CODE> use the generic message format of RFC 822<A HREF="#RefSTD11"> [7]</A> for transferring
+ entities. Both messages may include optional header fields (also known as "headers") and an
+ entity body. The entity body is separated from the headers by a null line (i.e., a line with nothing
+ preceding the <CODE>CRLF</CODE>).
+<P>
+
+<PRE>
+ Full-Request = Request-Line ; <A HREF="#Request-Line">Section 5.1</A>
+ *( General-Header ; <A HREF="#General-Header">Section 4.3</A>
+ | Request-Header ; <A HREF="#Request-Header">Section 5.2</A>
+ | Entity-Header ) ; <A HREF="#Entity-Header">Section 7.1</A>
+ CRLF
+ [ Entity-Body ] ; <A HREF="#Entity-Body">Section 7.2</A>
+</PRE>
+
+<PRE>
+ Full-Response = Status-Line ; <A HREF="#Status-Line">Section 6.1</A>
+ *( General-Header ; <A HREF="#General-Header">Section 4.3</A>
+ | Response-Header ; <A HREF="#Response-Header">Section 6.2</A>
+ | Entity-Header ) ; <A HREF="#Entity-Header">Section 7.1</A>
+ CRLF
+ [ Entity-Body ] ; <A HREF="#Entity-Body">Section 7.2</A>
+</PRE>
+
+ <CODE>Simple-Request</CODE> and <CODE>Simple-Response</CODE> do not allow the use of any header information and are
+ limited to a single request method (<CODE>GET</CODE>).
+<P>
+
+<PRE>
+ Simple-Request = "GET" SP Request-URI CRLF
+</PRE>
+
+<PRE>
+ Simple-Response = [ Entity-Body ]
+</PRE>
+
+ Use of the <CODE>Simple-Request</CODE> format is discouraged because it prevents the server from identifying
+ the media type of the returned entity.
+<P>
+
+<H3>4.2 <A NAME="Message-Headers">Message Headers</A></H3>
+
+ HTTP header fields, which include <CODE>General-Header</CODE> (<A HREF="#General-Header">Section 4.3</A>), <CODE>Request-Header</CODE> (<A HREF="#Request-Header">Section 5.2</A>),
+ <CODE>Response-Header</CODE> (<A HREF="#Response-Header">Section 6.2</A>), and <CODE>Entity-Header</CODE> (<A HREF="#Entity-Header">Section 7.1</A>) fields, follow the same generic
+ format as that given in Section 3.1 of RFC 822<A HREF="#RefSTD11"> [7]</A>. Each header field consists of a name
+ followed immediately by a colon (<CODE>":"</CODE>), a single space (<CODE>SP</CODE>) character, and the field value. Field
+ names are case-insensitive. Header fields can be extended over multiple lines by preceding
+ each extra line with at least one <CODE>SP</CODE> or <CODE>HT</CODE>, though this is not recommended.
+<P>
+
+<PRE>
+ HTTP-header = field-name ":" [ field-value ] CRLF
+</PRE>
+
+<PRE>
+ field-name = token
+ field-value = *( field-content | LWS )
+</PRE>
+
+<PRE>
+ field-content = &lt;the OCTETs making up the field-value
+ and consisting of either *TEXT or combinations
+ of token, tspecials, and quoted-string&gt;
+</PRE>
+
+ The order in which header fields are received is not significant. However, it is "good practice"
+ to send <CODE>General-Header</CODE> fields first, followed by <CODE>Request-Header</CODE> or <CODE>Response-Header</CODE> fields prior
+ to the <CODE>Entity-Header</CODE> fields.
+<P>
+
+ Multiple <CODE>HTTP-header</CODE> fields with the same <CODE>field-name</CODE> may be present in a message if and only
+ if the entire <CODE>field-value</CODE> for that header field is defined as a comma-separated list [i.e., <CODE>#(values)</CODE>].
+ It must be possible to combine the multiple header fields into one "field-name: field-value" pair,
+ without changing the semantics of the message, by appending each subsequent field-value to
+ the first, each separated by a comma.
+<P>
+
+<H3>4.3 <A NAME="General-Header">General Header Fields</A></H3>
+
+ There are a few header fields which have general applicability for both request and response
+ messages, but which do not apply to the entity being transferred. These headers apply only to
+ the message being transmitted.
+<P>
+
+<PRE>
+ General-Header = Date ; <A HREF="#Date">Section 10.6</A>
+ | Pragma ; <A HREF="#Pragma">Section 10.12</A>
+</PRE>
+
+ General header field names can be extended reliably only in combination with a change in the
+ protocol version. However, new or experimental header fields may be given the semantics of
+ general header fields if all parties in the communication recognize them to be general header
+ fields. Unrecognized header fields are treated as <CODE>Entity-Header</CODE> fields.
+<P>
+
+<H2>5. <A NAME="Request">Request</A></H2>
+
+ A request message from a client to a server includes, within the first line of that message, the
+ method to be applied to the resource, the identifier of the resource, and the protocol version in
+ use. For backwards compatibility with the more limited HTTP/0.9 protocol, there are two valid
+ formats for an HTTP request:
+<P>
+
+<PRE>
+ Request = Simple-Request | Full-Request
+</PRE>
+
+<PRE>
+ Simple-Request = "GET" SP Request-URI CRLF
+</PRE>
+
+<PRE>
+ Full-Request = Request-Line ; <A HREF="#Request-Line">Section 5.1</A>
+ *( General-Header ; <A HREF="#General-Header">Section 4.3</A>
+ | Request-Header ; <A HREF="#Request-Header">Section 5.2</A>
+ | Entity-Header ) ; <A HREF="#Entity-Header">Section 7.1</A>
+ CRLF
+ [ Entity-Body ] ; <A HREF="#Entity-Body">Section 7.2</A>
+</PRE>
+
+ If an HTTP/1.0 server receives a <CODE>Simple-Request</CODE>, it must respond with an HTTP/0.9
+ <CODE>Simple-Response</CODE>. An HTTP/1.0 client capable of receiving a <CODE>Full-Response</CODE> should never
+ generate a <CODE>Simple-Request</CODE>.
+<P>
+
+<H3>5.1 <A NAME="Request-Line">Request-Line</A></H3>
+
+ The <CODE>Request-Line</CODE> begins with a method token, followed by the <CODE>Request-URI</CODE> and the protocol
+ version, and ending with <CODE>CRLF</CODE>. The elements are separated by <CODE>SP</CODE> characters.
+ No <CODE>CR</CODE> or <CODE>LF</CODE> are allowed except in the final <CODE>CRLF</CODE> sequence.
+<P>
+
+<PRE>
+ Request-Line = Method SP Request-URI SP HTTP-Version CRLF
+</PRE>
+
+ Note that the difference between a <CODE>Simple-Request</CODE> and the <CODE>Request-Line</CODE> of a <CODE>Full-Request</CODE> is the
+ presence of the <CODE>HTTP-Version</CODE> field and the availability of methods other than <CODE>GET</CODE>.
+<P>
+
+<H4>5.1.1 <A NAME="Method">Method</A></H4>
+
+ The <CODE>Method</CODE> token indicates the method to be performed on the resource identified by the
+ <CODE>Request-URI</CODE>. The method is case-sensitive.
+<P>
+
+<PRE>
+ Method = "GET" ; <A HREF="#GET">Section 8.1</A>
+ | "HEAD" ; <A HREF="#HEAD">Section 8.2</A>
+ | "POST" ; <A HREF="#POST">Section 8.3</A>
+ | extension-method
+</PRE>
+
+<PRE>
+ extension-method = token
+</PRE>
+
+ The list of methods acceptable by a specific resource can change dynamically; the client is
+ notified through the return code of the response if a method is not allowed on a resource.
+ Servers should return the status code 501 (not implemented) if the method is unrecognized or
+ not implemented.
+<P>
+
+ The methods commonly used by HTTP/1.0 applications are fully defined in <A HREF="#Methods">Section 8</A>.
+<P>
+
+<H4>5.1.2 <A NAME="Request-URI">Request-URI</A></H4>
+
+ The <CODE>Request-URI</CODE> is a Uniform Resource Identifier (<A HREF="#URI">Section 3.2</A>) and identifies the resource upon
+ which to apply the request.
+<P>
+
+<PRE>
+ Request-URI = absoluteURI | abs_path
+</PRE>
+
+ The two options for <CODE>Request-URI</CODE> are dependent on the nature of the request.
+<P>
+
+ The <CODE>absoluteURI</CODE> form is only allowed when the request is being made to a proxy. The proxy is
+ requested to forward the request and return the response. If the request is <CODE>GET</CODE> or <CODE>HEAD</CODE> and a
+ prior response is cached, the proxy may use the cached message if it passes any restrictions in
+ the <CODE>Expires</CODE> header field. Note that the proxy may forward the request on to another proxy or
+ directly to the server specified by the <CODE>absoluteURI</CODE>. In order to avoid request loops, a proxy must
+ be able to recognize all of its server names, including any aliases, local variations, and the
+ numeric IP address. An example <CODE>Request-Line</CODE> would be:
+<P>
+
+<PRE>
+ GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.0
+</PRE>
+
+ The most common form of <CODE>Request-URI</CODE> is that used to identify a resource on an origin server
+ or gateway. In this case, only the absolute path of the URI is transmitted (see <A HREF="#URI-syntax">Section 3.2.1</A>,
+ <CODE>abs_path</CODE>). For example, a client wishing to retrieve the resource above directly from the origin
+ server would create a TCP connection to port 80 of the host "www.w3.org" and send the line:
+<P>
+
+<PRE>
+ GET /pub/WWW/TheProject.html HTTP/1.0
+</PRE>
+
+ followed by the remainder of the <CODE>Full-Request</CODE>. Note that the absolute path cannot be empty; if
+ none is present in the original URI, it must be given as "/" (the server root).
+<P>
+
+ The <CODE>Request-URI</CODE> is transmitted as an encoded string, where some characters may be escaped
+ using the "% HEX HEX" encoding defined by RFC 1738<A HREF="#RefURL"> [4]</A>. The origin server must decode
+ the <CODE>Request-URI</CODE> in order to properly interpret the request.
+<P>
+
+<H3>5.2 <A NAME="Request-Header">Request Header Fields</A></H3>
+
+ The request header fields allow the client to pass additional information about the request, and
+ about the client itself, to the server. These fields act as request modifiers, with semantics
+ equivalent to the parameters on a programming language method (procedure) invocation.
+<P>
+
+<PRE>
+ Request-Header = Authorization ; <A HREF="#Authorization">Section 10.2</A>
+ | From ; <A HREF="#From">Section 10.8</A>
+ | If-Modified-Since ; <A HREF="#If-Modified-Since">Section 10.9</A>
+ | Referer ; <A HREF="#Referer">Section 10.13</A>
+ | User-Agent ; <A HREF="#User-Agent">Section 10.15</A>
+</PRE>
+
+ <CODE>Request-Header</CODE> field names can be extended reliably only in combination with a change in the
+ protocol version. However, new or experimental header fields may be given the semantics of
+ request header fields if all parties in the communication recognize them to be request header
+ fields. Unrecognized header fields are treated as <CODE>Entity-Header</CODE> fields.
+<P>
+
+<H2>6. <A NAME="Response">Response</A></H2>
+
+ After receiving and interpreting a request message, a server responds in the form of an HTTP
+ response message.
+<P>
+
+<PRE>
+ Response = Simple-Response | Full-Response
+</PRE>
+
+<PRE>
+ Simple-Response = [ Entity-Body ]
+</PRE>
+
+<PRE>
+ Full-Response = Status-Line ; <A HREF="#Status-Line">Section 6.1</A>
+ *( General-Header ; <A HREF="#General-Header">Section 4.3</A>
+ | Response-Header ; <A HREF="#Response-Header">Section 6.2</A>
+ | Entity-Header ) ; <A HREF="#Entity-Header">Section 7.1</A>
+ CRLF
+ [ Entity-Body ] ; <A HREF="#Entity-Body">Section 7.2</A>
+</PRE>
+
+ A <CODE>Simple-Response</CODE> should only be sent in response to an HTTP/0.9 <CODE>Simple-Request</CODE> or if the
+ server only supports the more limited HTTP/0.9 protocol. If a client sends an HTTP/1.0
+ <CODE>Full-Request</CODE> and receives a response that does not begin with a <CODE>Status-Line</CODE>, it should assume that
+ the response is a <CODE>Simple-Response</CODE> and parse it accordingly. Note that the <CODE>Simple-Response</CODE>
+ consists only of the entity body and is terminated by the server closing the connection.
+<P>
+
+<H3>6.1 <A NAME="Status-Line">Status-Line</A></H3>
+
+ The first line of a <CODE>Full-Response</CODE> message is the <CODE>Status-Line</CODE>, consisting of the protocol version
+ followed by a numeric status code and its associated textual phrase, with each element
+ separated by <CODE>SP</CODE> characters. No <CODE>CR</CODE> or <CODE>LF</CODE> is allowed except in the final <CODE>CRLF</CODE> sequence.
+<P>
+
+<PRE>
+ Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
+</PRE>
+
+ Since a status line always begins with the protocol version and status code
+<P>
+
+<PRE>
+ "HTTP/" 1*DIGIT "." 1*DIGIT SP 3DIGIT SP
+</PRE>
+
+ (e.g., <CODE>"HTTP/1.0 200 "</CODE>), the presence of that expression is sufficient to differentiate a
+ <CODE>Full-Response</CODE> from a <CODE>Simple-Response</CODE>. Although the <CODE>Simple-Response</CODE> format may allow such
+ an expression to occur at the beginning of an entity body, and thus cause a misinterpretation of
+ the message if it was given in response to a <CODE>Full-Request</CODE>, most HTTP/0.9 servers are limited to
+ responses of type "text/html" and therefore would never generate such a response.
+<P>
+
+<H4>6.1.1 <A NAME="Status-Code">Status Code and Reason Phrase</A></H4>
+
+ The <CODE>Status-Code</CODE> element is a 3-digit integer result code of the attempt to understand and satisfy
+ the request. The <CODE>Reason-Phrase</CODE> is intended to give a short textual description of the <CODE>Status-Code</CODE>.
+ The <CODE>Status-Code</CODE> is intended for use by automata and the <CODE>Reason-Phrase</CODE> is intended for the
+ human user. The client is not required to examine or display the <CODE>Reason-Phrase</CODE>.
+<P>
+
+ The first digit of the <CODE>Status-Code</CODE> defines the class of response. The last two digits do not have
+ any categorization role. There are 5 values for the first digit:
+<P>
+
+<UL>
+<LI>1xx: Informational - Not used, but reserved for future use
+<LI>2xx: Success - The action was successfully received, understood, and accepted.
+<LI>3xx: Redirection - Further action must be taken in order to complete the request
+<LI>4xx: Client Error - The request contains bad syntax or cannot be fulfilled
+<LI>5xx: Server Error - The server failed to fulfill an apparently valid request
+</UL>
+
+ The individual values of the numeric status codes defined for HTTP/1.0, and an example set of
+ corresponding <CODE>Reason-Phrase</CODE>'s, are presented below. The reason phrases listed here are only
+ recommended -- they may be replaced by local equivalents without affecting the protocol.
+ These codes are fully defined in <A HREF="#Status-Codes">Section 9</A>.
+<P>
+
+<PRE>
+ Status-Code = "200" ; OK
+ | "201" ; Created
+ | "202" ; Accepted
+ | "204" ; No Content
+ | "301" ; Moved Permanently
+ | "302" ; Moved Temporarily
+ | "304" ; Not Modified
+ | "400" ; Bad Request
+ | "401" ; Unauthorized
+ | "403" ; Forbidden
+ | "404" ; Not Found
+ | "500" ; Internal Server Error
+ | "501" ; Not Implemented
+ | "502" ; Bad Gateway
+ | "503" ; Service Unavailable
+ | extension-code
+</PRE>
+
+<PRE>
+ extension-code = 3DIGIT
+</PRE>
+
+<PRE>
+ Reason-Phrase = *&lt;TEXT, excluding CR, LF&gt;
+</PRE>
+
+ HTTP status codes are extensible, but the above codes are the only ones generally recognized
+ in current practice. HTTP applications are not required to understand the meaning of all
+ registered status codes, though such understanding is obviously desirable. However,
+ applications must understand the class of any status code, as indicated by the first digit, and
+ treat any unrecognized response as being equivalent to the x00 status code of that class, with
+ the exception that an unrecognized response must not be cached. For example, if an
+ unrecognized status code of 431 is received by the client, it can safely assume that there was
+ something wrong with its request and treat the response as if it had received a 400 status code.
+ In such cases, user agents should present to the user the entity returned with the response, since
+ that entity is likely to include human-readable information which will explain the unusual
+ status.
+<P>
+
+<H3>6.2 <A NAME="Response-Header">Response Header Fields</A></H3>
+
+ The response header fields allow the server to pass additional information about the response
+ which cannot be placed in the <CODE>Status-Line</CODE>. These header fields give information about the server
+ and about further access to the resource identified by the <CODE>Request-URI</CODE>.
+<P>
+
+<PRE>
+ Response-Header = Location ; <A HREF="#Location">Section 10.11</A>
+ | Server ; <A HREF="#Server">Section 10.14</A>
+ | WWW-Authenticate ; <A HREF="#WWW-Authenticate">Section 10.16</A>
+</PRE>
+
+ <CODE>Response-Header</CODE> field names can be extended reliably only in combination with a change in the
+ protocol version. However, new or experimental header fields may be given the semantics of
+ response header fields if all parties in the communication recognize them to be response header
+ fields. Unrecognized header fields are treated as <CODE>Entity-Header</CODE> fields.
+<P>
+
+<H2>7. <A NAME="Entity">Entity</A></H2>
+
+ <CODE>Full-Request</CODE> and <CODE>Full-Response</CODE> messages may transfer an entity within some requests and
+ responses. An entity consists of <CODE>Entity-Header</CODE> fields and (usually) an <CODE>Entity-Body</CODE>. In this section,
+ both <EM>sender</EM> and <EM>recipient</EM> refer to either the client or the server, depending on who sends and
+ who receives the entity.
+<P>
+
+<H3>7.1 <A NAME="Entity-Header">Entity Header Fields</A></H3>
+
+ <CODE>Entity-Header</CODE> fields define optional metainformation about the <CODE>Entity-Body</CODE> or, if no body is
+ present, about the resource identified by the request.
+<P>
+
+<PRE>
+ Entity-Header = Allow ; <A HREF="#Allow">Section 10.1</A>
+ | Content-Encoding ; <A HREF="#Content-Encoding">Section 10.3</A>
+ | Content-Length ; <A HREF="#Content-Length">Section 10.4</A>
+ | Content-Type ; <A HREF="#Content-Type">Section 10.5</A>
+ | Expires ; <A HREF="#Expires">Section 10.7</A>
+ | Last-Modified ; <A HREF="#Last-Modified">Section 10.10</A>
+ | extension-header
+</PRE>
+
+<PRE>
+ extension-header = HTTP-header
+</PRE>
+
+ The <CODE>extension-header</CODE> mechanism allows additional <CODE>Entity-Header</CODE> fields to be defined without
+ changing the protocol, but these fields cannot be assumed to be recognizable by the recipient.
+ Unrecognized header fields should be ignored by the recipient and forwarded by proxies.
+<P>
+
+<H3>7.2 <A NAME="Entity-Body">Entity Body</A></H3>
+
+ The entity body (if any) sent with an HTTP request or response is in a format and encoding
+ defined by the <CODE>Entity-Header</CODE> fields.
+<P>
+
+<PRE>
+ Entity-Body = *OCTET
+</PRE>
+
+ An entity body is included with a request message only when the request method calls for one.
+ The presence of an entity body in a request is signaled by the inclusion of a <CODE>Content-Length</CODE>
+ header field in the request message headers. HTTP/1.0 requests containing an entity body must
+ include a valid <CODE>Content-Length</CODE> header field.
+<P>
+
+ For response messages, whether or not an entity body is included with a message is dependent
+ on both the request method and the response code. All responses to the <CODE>HEAD</CODE> request method
+ must not include a body, even though the presence of entity header fields may lead one to
+ believe they do. All 1xx (informational), 204 (no content), and 304 (not modified) responses
+ must not include a body. All other responses must include an entity body or a <CODE>Content-Length</CODE>
+ header field defined with a value of zero (0).
+<P>
+
+<H4>7.2.1 <A NAME="BodyType">Type</A></H4>
+
+ When an <CODE>Entity-Body</CODE> is included with a message, the data type of that body is determined via
+ the header fields <CODE>Content-Type</CODE> and <CODE>Content-Encoding</CODE>. These define a two-layer, ordered
+ encoding model:
+<P>
+
+<PRE>
+ entity-body := Content-Encoding( Content-Type( data ) )
+</PRE>
+
+ A <CODE>Content-Type</CODE> specifies the media type of the underlying data. A <CODE>Content-Encoding</CODE> may be used
+ to indicate any additional content coding applied to the type, usually for the purpose of data
+ compression, that is a property of the resource requested. The default for the content encoding
+ is none (i.e., the identity function).
+<P>
+
+ Any HTTP/1.0 message containing an entity body should include a <CODE>Content-Type</CODE> header field
+ defining the media type of that body. If and <STRONG>only if</STRONG> the media type is not given by a <CODE>Content-Type</CODE>
+ header, as is the case for <CODE>Simple-Response</CODE> messages, the recipient may attempt to guess the
+ media type via inspection of its content and/or the name extension(s) of the URL used to
+ identify the resource. If the media type remains unknown, the recipient should treat it as type
+ "<CODE>application/octet-stream</CODE>".
+<P>
+
+<H4>7.2.2 <A NAME="BodyLength">Length</A></H4>
+
+ When an <CODE>Entity-Body</CODE> is included with a message, the length of that body may be determined in
+ one of two ways. If a <CODE>Content-Length</CODE> header field is present, its value in bytes represents the
+ length of the <CODE>Entity-Body</CODE>. Otherwise, the body length is determined by the closing of the
+ connection by the server.
+<P>
+
+ Closing the connection cannot be used to indicate the end of a request body, since it leaves no
+ possibility for the server to send back a response. Therefore, HTTP/1.0 requests containing an
+ entity body must include a valid <CODE>Content-Length</CODE> header field. If a request contains an entity body
+ and <CODE>Content-Length</CODE> is not specified, and the server does not recognize or cannot calculate the
+ length from other fields, then the server should send a 400 (bad request) response.
+
+<BLOCKQUOTE>
+ Note: Some older servers supply an invalid Content-Length when sending a
+ document that contains server-side includes dynamically inserted into the data
+ stream. It must be emphasized that this will not be tolerated by future versions of
+ HTTP. Unless the client knows that it is receiving a response from a compliant server,
+ it should not depend on the Content-Length value being correct.
+</BLOCKQUOTE>
+
+<H2>8. <A NAME="Methods">Method Definitions</A></H2>
+
+ The set of common methods for HTTP/1.0 is defined below. Although this set can be expanded,
+ additional methods cannot be assumed to share the same semantics for separately extended
+ clients and servers.
+<P>
+
+<H3>8.1 <A NAME="GET">GET</A></H3>
+
+ The <CODE>GET</CODE> method means retrieve whatever information (in the form of an entity) is identified by
+ the <CODE>Request-URI</CODE>. If the <CODE>Request-URI</CODE> refers to a data-producing process, it is the produced data
+ which shall be returned as the entity in the response and not the source text of the process,
+ unless that text happens to be the output of the process.
+<P>
+
+ The semantics of the <CODE>GET</CODE> method changes to a "conditional <CODE>GET</CODE>" if the request message
+ includes an <CODE>If-Modified-Since</CODE> header field. A conditional <CODE>GET</CODE> method requests that the identified
+ resource be transferred only if it has been modified since the date given by the <CODE>If-Modified-Since</CODE>
+ header, as described in <A HREF="#If-Modified-Since">Section 10.9</A>. The conditional <CODE>GET</CODE> method is intended to reduce
+ network usage by allowing cached entities to be refreshed without requiring multiple requests
+ or transferring unnecessary data.
+<P>
+
+<H3>8.2 <A NAME="HEAD">HEAD</A></H3>
+
+ The <CODE>HEAD</CODE> method is identical to <CODE>GET</CODE> except that the server must not return any <CODE>Entity-Body</CODE> in
+ the response. The metainformation contained in the HTTP headers in response to a <CODE>HEAD</CODE>
+ request should be identical to the information sent in response to a <CODE>GET</CODE> request. This method
+ can be used for obtaining metainformation about the resource identified by the <CODE>Request-URI</CODE>
+ without transferring the <CODE>Entity-Body</CODE> itself. This method is often used for testing hypertext links
+ for validity, accessibility, and recent modification.
+<P>
+
+ There is no "conditional <CODE>HEAD</CODE>" request analogous to the conditional <CODE>GET</CODE>. If an <CODE>If-Modified-Since</CODE>
+ header field is included with a <CODE>HEAD</CODE> request, it should be ignored.
+<P>
+
+<H3>8.3 <A NAME="POST">POST</A></H3>
+
+ The <CODE>POST</CODE> method is used to request that the destination server accept the entity enclosed in the
+ request as a new subordinate of the resource identified by the <CODE>Request-URI</CODE> in the <CODE>Request-Line</CODE>.
+ <CODE>POST</CODE> is designed to allow a uniform method to cover the following functions:
+<P>
+
+<UL>
+<LI>Annotation of existing resources;
+<LI>Posting a message to a bulletin board, newsgroup, mailing list, or similar group of
+ articles;
+<LI>Providing a block of data, such as the result of submitting a form<A HREF="#RefHTML"> [3]</A>, to a data-handling
+ process;
+<LI>Extending a database through an append operation.
+</UL>
+
+ The actual function performed by the <CODE>POST</CODE> method is determined by the server and is usually
+ dependent on the <CODE>Request-URI</CODE>. The posted entity is subordinate to that URI in the same way
+ that a file is subordinate to a directory containing it, a news article is subordinate to a
+ newsgroup to which it is posted, or a record is subordinate to a database.
+<P>
+
+ A successful <CODE>POST</CODE> does not require that the entity be created as a resource on the origin server
+ or made accessible for future reference. That is, the action performed by the <CODE>POST</CODE> method
+ might not result in a resource that can be identified by a URI. In this case, either 200 (ok) or
+ 204 (no content) is the appropriate response status, depending on whether or not the response
+ includes an entity that describes the result.
+<P>
+
+ If a resource has been created on the origin server, the response should be 201 (created) and
+ contain an entity (preferably of type "text/html") which describes the status of the request and
+ refers to the new resource.
+<P>
+
+ A valid <CODE>Content-Length</CODE> is required on all HTTP/1.0 <CODE>POST</CODE> requests. An HTTP/1.0 server should
+ respond with a 400 (bad request) message if it cannot determine the length of the request
+ message's content.
+<P>
+
+ Applications must not cache responses to a POST request because the application has no way
+ of knowing that the server would return an equivalent response on some future request.
+<P>
+
+<H2>9. <A NAME="Status-Codes">Status Code Definitions</A></H2>
+
+ Each <CODE>Status-Code</CODE> is described below, including a description of which <CODE>method</CODE>(s) it can follow
+ and any metainformation required in the response.
+<P>
+
+<H3>9.1 <A NAME="Code1xx">Informational 1xx</A></H3>
+
+ This class of status code indicates a provisional response, consisting only of the <CODE>Status-Line</CODE> and
+ optional headers, and is terminated by an empty line. HTTP/1.0 does not define any 1xx status
+ codes and they are not a valid response to a HTTP/1.0 request. However, they may be useful
+ for experimental applications which are outside the scope of this specification.
+<P>
+
+<H3>9.2 <A NAME="Code2xx">Successful 2xx</A></H3>
+
+ This class of status code indicates that the client's request was successfully received,
+ understood, and accepted.
+<P>
+
+<H4> <A NAME="Code200">200 OK</A></H4>
+
+ The request has succeeded. The information returned with the response is dependent on the
+ method used in the request, as follows:
+<P>
+
+<DL COMPACT>
+<DT><CODE>GET</CODE>
+<DD>an entity corresponding to the requested resource is sent in the response;
+
+<DT><CODE>HEAD</CODE>
+<DD>the response must only contain the header information and no <CODE>Entity-Body</CODE>;
+
+<DT><CODE>POST</CODE>
+<DD>an entity describing or containing the result of the action.
+</DL>
+
+<H4> <A NAME="Code201">201 Created</A></H4>
+
+ The request has been fulfilled and resulted in a new resource being created. The newly created
+ resource can be referenced by the URI(s) returned in the entity of the response. The origin
+ server should create the resource before using this <CODE>Status-Code</CODE>. If the action cannot be carried
+ out immediately, the server must include in the response body a description of when the
+ resource will be available; otherwise, the server should respond with 202 (accepted).
+<P>
+
+ Of the methods defined by this specification, only <CODE>POST</CODE> can create a resource.
+<P>
+
+<H4> <A NAME="Code202">202 Accepted</A></H4>
+
+ The request has been accepted for processing, but the processing has not been completed. The
+ request may or may not eventually be acted upon, as it may be disallowed when processing
+ actually takes place. There is no facility for re-sending a status code from an asynchronous
+ operation such as this.
+<P>
+
+ The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a
+ request for some other process (perhaps a batch-oriented process that is only run once per day)
+ without requiring that the user agent's connection to the server persist until the process is
+ completed. The entity returned with this response should include an indication of the request's
+ current status and either a pointer to a status monitor or some estimate of when the user can
+ expect the request to be fulfilled.
+<P>
+
+<H4> <A NAME="Code204">204 No Content</A></H4>
+
+ The server has fulfilled the request but there is no new information to send back. If the client is
+ a user agent, it should not change its document view from that which caused the request to be
+ generated. This response is primarily intended to allow input for scripts or other actions to take
+ place without causing a change to the user agent's active document view. The response may
+ include new metainformation in the form of entity headers, which should apply to the
+ document currently in the user agent's active view.
+<P>
+
+<H3>9.3 <A NAME="Code3xx">Redirection 3xx</A></H3>
+
+ This class of status code indicates that further action needs to be taken by the user agent in order
+ to fulfill the request. The action required may be carried out by the user agent without
+ interaction with the user if and only if the method used in the subsequent request is <CODE>GET</CODE> or
+ <CODE>HEAD</CODE>. A user agent should never automatically redirect a request more than 5 times, since such
+ redirections usually indicate an infinite loop.
+<P>
+
+<H4> <A NAME="Code300">300 Multiple Choices</A></H4>
+
+ This response code is not directly used by HTTP/1.0 applications, but serves as the default for
+ interpreting the 3xx class of responses.
+<P>
+
+ The requested resource is available at one or more locations. Unless it was a <CODE>HEAD</CODE> request, the
+ response should include an entity containing a list of resource characteristics and locations
+ from which the user or user agent can choose the one most appropriate. If the server has a
+ preferred choice, it should include the URL in a <CODE>Location</CODE> field; user agents may use this field
+ value for automatic redirection.
+<P>
+
+<H4> <A NAME="Code301">301 Moved Permanently</A></H4>
+
+ The requested resource has been assigned a new permanent URL and any future references to
+ this resource should be done using that URL. Clients with link editing capabilities should
+ automatically relink references to the <CODE>Request-URI</CODE> to the new reference returned by the server,
+ where possible.
+<P>
+
+ The new URL must be given by the <CODE>Location</CODE> field in the response. Unless it was a <CODE>HEAD</CODE> request,
+ the <CODE>Entity-Body</CODE> of the response should contain a short note with a hyperlink to the new URL.
+<P>
+
+ If the 301 status code is received in response to a request using the <CODE>POST</CODE> method, the user agent
+ must not automatically redirect the request unless it can be confirmed by the user, since this
+ might change the conditions under which the request was issued.
+<P>
+
+<BLOCKQUOTE>
+ Note: When automatically redirecting a POST request after receiving a 301 status
+ code, some existing user agents will erroneously change it into a GET request.
+</BLOCKQUOTE>
+
+<H4> <A NAME="Code302">302 Moved Temporarily</A></H4>
+
+ The requested resource resides temporarily under a different URL. Since the redirection may
+ be altered on occasion, the client should continue to use the <CODE>Request-URI</CODE> for future requests.
+<P>
+
+ The URL must be given by the <CODE>Location</CODE> field in the response. Unless it was a <CODE>HEAD</CODE> request, the
+ <CODE>Entity-Body</CODE> of the response should contain a short note with a hyperlink to the new URI(s).
+<P>
+
+ If the 302 status code is received in response to a request using the <CODE>POST</CODE> method, the user agent
+ must not automatically redirect the request unless it can be confirmed by the user, since this
+ might change the conditions under which the request was issued.
+<P>
+
+<BLOCKQUOTE>
+ Note: When automatically redirecting a POST request after receiving a 302 status
+ code, some existing user agents will erroneously change it into a GET request.
+</BLOCKQUOTE>
+
+<H4> <A NAME="Code304">304 Not Modified</A></H4>
+
+ If the client has performed a conditional <CODE>GET</CODE> request and access is allowed, but the document
+ has not been modified since the date and time specified in the <CODE>If-Modified-Since</CODE> field, the server
+ must respond with this status code and not send an <CODE>Entity-Body</CODE> to the client. Header fields
+ contained in the response should only include information which is relevant to cache managers
+ or which may have changed independently of the entity's <CODE>Last-Modified</CODE> date. Examples of
+ relevant header fields include: <CODE>Date</CODE>, <CODE>Server</CODE>, and <CODE>Expires</CODE>. A cache should update its cached entity
+ to reflect any new field values given in the 304 response.
+<P>
+
+<H3>9.4 <A NAME="Code4xx">Client Error 4xx</A></H3>
+
+ The 4xx class of status code is intended for cases in which the client seems to have erred. If the
+ client has not completed the request when a 4xx code is received, it should immediately cease
+ sending data to the server. Except when responding to a <CODE>HEAD</CODE> request, the server should
+ include an entity containing an explanation of the error situation, and whether it is a temporary
+ or permanent condition. These status codes are applicable to any request method.
+<P>
+
+<BLOCKQUOTE>
+ Note: If the client is sending data, server implementations on TCP should be careful
+ to ensure that the client acknowledges receipt of the packet(s) containing the response
+ prior to closing the input connection. If the client continues sending data to the server
+ after the close, the server's controller will send a reset packet to the client, which may
+ erase the client's unacknowledged input buffers before they can be read and
+ interpreted by the HTTP application.
+</BLOCKQUOTE>
+
+<H4> <A NAME="Code400">400 Bad Request</A></H4>
+
+ The request could not be understood by the server due to malformed syntax. The client should
+ not repeat the request without modifications.
+<P>
+
+<H4> <A NAME="Code401">401 Unauthorized</A></H4>
+
+ The request requires user authentication. The response must include a <CODE>WWW-Authenticate</CODE>
+ header field (<A HREF="#WWW-Authenticate">Section 10.16</A>) containing a <CODE>challenge</CODE> applicable to the requested resource. The
+ client may repeat the request with a suitable <CODE>Authorization</CODE> header field (<A HREF="#Authorization">Section 10.2</A>). If the
+ request already included Authorization credentials, then the 401 response indicates that
+ authorization has been refused for those credentials. If the 401 response contains the same
+ challenge as the prior response, and the user agent has already attempted authentication at least
+ once, then the user should be presented the entity that was given in the response, since that
+ entity may include relevant diagnostic information. HTTP access authentication is explained
+ in <A HREF="#AA">Section 11</A>.
+<P>
+
+<H4> <A NAME="Code403">403 Forbidden</A></H4>
+
+ The server understood the request, but is refusing to fulfill it. Authorization will not help and
+ the request should not be repeated. If the request method was not <CODE>HEAD</CODE> and the server wishes
+ to make public why the request has not been fulfilled, it should describe the reason for the
+ refusal in the entity body. This status code is commonly used when the server does not wish to
+ reveal exactly why the request has been refused, or when no other response is applicable.
+<P>
+
+<H4> <A NAME="Code404">404 Not Found</A></H4>
+
+ The server has not found anything matching the <CODE>Request-URI</CODE>. No indication is given of whether
+ the condition is temporary or permanent. If the server does not wish to make this information
+ available to the client, the status code 403 (forbidden) can be used instead.
+<P>
+
+<H3>9.5 <A NAME="Code5xx">Server Error 5xx</A></H3>
+
+ Response status codes beginning with the digit "5" indicate cases in which the server is aware
+ that it has erred or is incapable of performing the request. If the client has not completed the
+ request when a 5xx code is received, it should immediately cease sending data to the server.
+ Except when responding to a <CODE>HEAD</CODE> request, the server should include an entity containing an
+ explanation of the error situation, and whether it is a temporary or permanent condition. These
+ response codes are applicable to any request method and there are no required header fields.
+<P>
+
+<H4> <A NAME="Code500">500 Internal Server Error</A></H4>
+
+ The server encountered an unexpected condition which prevented it from fulfilling the request.
+<P>
+
+<H4> <A NAME="Code501">501 Not Implemented</A></H4>
+
+ The server does not support the functionality required to fulfill the request. This is the
+ appropriate response when the server does not recognize the request method and is not capable
+ of supporting it for any resource.
+<P>
+
+<H4> <A NAME="Code502">502 Bad Gateway</A></H4>
+
+ The server, while acting as a gateway or proxy, received an invalid response from the upstream
+ server it accessed in attempting to fulfill the request.
+<P>
+
+<H4> <A NAME="Code503">503 Service Unavailable</A></H4>
+
+ The server is currently unable to handle the request due to a temporary overloading or
+ maintenance of the server. The implication is that this is a temporary condition which will be
+ alleviated after some delay.
+
+<BLOCKQUOTE>
+ Note: The existence of the 503 status code does not imply that a server must use it
+ when becoming overloaded. Some servers may wish to simply refuse the connection.
+</BLOCKQUOTE>
+
+<H2>10. <A NAME="HeaderFields">Header Field Definitions</A></H2>
+
+ This section defines the syntax and semantics of all commonly used HTTP/1.0 header fields.
+ For general and entity header fields, both <EM>sender </EM>and<EM> recipient</EM> refer to either the client or the
+ server, depending on who sends and who receives the message.
+<P>
+
+<H3>10.1 <A NAME="Allow">Allow</A></H3>
+
+ The <CODE>Allow</CODE> entity-header field lists the set of methods supported by the resource identified by the
+ <CODE>Request-URI</CODE>. The purpose of this field is strictly to inform the recipient of valid methods
+ associated with the resource. The <CODE>Allow</CODE> header field is not permitted in a request using the <CODE>POST</CODE>
+ method, and thus should be ignored if it is received as part of a <CODE>POST</CODE> entity.
+<P>
+
+<PRE>
+ Allow = "Allow" ":" 1#method
+</PRE>
+
+ Example of use:
+<P>
+
+<PRE>
+ Allow: GET, HEAD
+</PRE>
+
+ This field cannot prevent a client from trying other methods. However, the indications given by
+ the <CODE>Allow</CODE> header field value should be followed. The actual set of allowed methods is defined
+ by the origin server at the time of each request.
+<P>
+
+ A proxy must not modify the <CODE>Allow</CODE> header field even if it does not understand all the methods
+ specified, since the user agent may have other means of communicating with the origin server.
+<P>
+
+ The <CODE>Allow</CODE> header field does not indicate what methods are implemented by the server.
+<P>
+
+<H3>10.2 <A NAME="Authorization">Authorization</A></H3>
+
+ A user agent that wishes to authenticate itself with a server--usually, but not necessarily, after
+ receiving a 401 response--may do so by including an <CODE>Authorization</CODE> request-header field with
+ the request. The <CODE>Authorization</CODE> field value consists of <CODE>credentials</CODE> containing the authentication
+ information of the user agent for the realm of the resource being requested.
+<P>
+
+<PRE>
+ Authorization = "Authorization" ":" credentials
+</PRE>
+
+ HTTP access authentication is described in <A HREF="#AA">Section 11</A>. If a request is authenticated and a <CODE>realm</CODE>
+ specified, the same <CODE>credentials</CODE> should be valid for all other requests within this <CODE>realm</CODE>.
+<P>
+
+ Responses to requests containing an <CODE>Authorization</CODE> field are not cachable.
+<P>
+
+<H3>10.3 <A NAME="Content-Encoding">Content-Encoding</A></H3>
+
+ The <CODE>Content-Encoding</CODE> entity-header field is used as a modifier to the <CODE>media-type</CODE>. When present,
+ its value indicates what additional content coding has been applied to the resource, and thus
+ what decoding mechanism must be applied in order to obtain the <CODE>media-type</CODE> referenced by the
+ <CODE>Content-Type</CODE> header field. The <CODE>Content-Encoding</CODE> is primarily used to allow a document to be
+ compressed without losing the identity of its underlying media type.
+<P>
+
+<PRE>
+ Content-Encoding = "Content-Encoding" ":" content-coding
+</PRE>
+
+ Content codings are defined in <A HREF="#Content-Codings">Section 3.5</A>. An example of its use is
+<P>
+
+<PRE>
+ Content-Encoding: x-gzip
+</PRE>
+
+ The <CODE>Content-Encoding</CODE> is a characteristic of the resource identified by the <CODE>Request-URI</CODE>. Typically,
+ the resource is stored with this encoding and is only decoded before rendering or analogous
+ usage.
+<P>
+
+<H3>10.4 <A NAME="Content-Length">Content-Length</A></H3>
+
+ The <CODE>Content-Length</CODE> entity-header field indicates the size of the <CODE>Entity-Body</CODE>, in decimal number
+ of octets, sent to the recipient or, in the case of the <CODE>HEAD</CODE> method, the size of the <CODE>Entity-Body</CODE> that
+ would have been sent had the request been a <CODE>GET</CODE>.
+<P>
+
+<PRE>
+ Content-Length = "Content-Length" ":" 1*DIGIT
+</PRE>
+
+ An example is
+<P>
+
+<PRE>
+ Content-Length: 3495
+</PRE>
+
+ Applications should use this field to indicate the size of the <CODE>Entity-Body</CODE> to be transferred,
+ regardless of the media type of the entity. A valid <CODE>Content-Length</CODE> field value is required on all
+ HTTP/1.0 request messages containing an entity body.
+<P>
+
+ Any <CODE>Content-Length</CODE> greater than or equal to zero is a valid value. <A HREF="#BodyLength">Section 7.2.2</A> describes how
+ to determine the length of a response entity body if a <CODE>Content-Length</CODE> is not given.
+<P>
+
+<BLOCKQUOTE>
+ Note: The meaning of this field is significantly different from the corresponding
+ definition in MIME, where it is an optional field used within the
+ "message/external-body" content-type. In HTTP, it should be used whenever the
+ entity's length can be determined prior to being transferred.
+</BLOCKQUOTE>
+
+<H3>10.5 <A NAME="Content-Type">Content-Type</A></H3>
+
+ The <CODE>Content-Type</CODE> entity-header field indicates the media type of the <CODE>Entity-Body</CODE> sent to the
+ recipient or, in the case of the <CODE>HEAD</CODE> method, the media type that would have been sent had the
+ request been a <CODE>GET</CODE>.
+<P>
+
+<PRE>
+ Content-Type = "Content-Type" ":" media-type
+</PRE>
+
+ Media types are defined in <A HREF="#Media-Types">Section 3.6</A>. An example of the field is
+<P>
+
+<PRE>
+ Content-Type: text/html
+</PRE>
+
+ Further discussion of methods for identifying the media type of an entity is provided in
+ <A HREF="#BodyType">Section 7.2.1</A>.
+<P>
+
+<H3>10.6 <A NAME="Date">Date</A></H3>
+
+ The <CODE>Date</CODE> general-header field represents the date and time at which the message was originated,
+ having the same semantics as <CODE>orig-date</CODE> in RFC 822. The field value is an <CODE>HTTP-date</CODE>, as
+ described in <A HREF="#DateFormats">Section 3.3</A>.
+<P>
+
+<PRE>
+ Date = "Date" ":" HTTP-date
+</PRE>
+
+ An example is
+<P>
+
+<PRE>
+ Date: Tue, 15 Nov 1994 08:12:31 GMT
+</PRE>
+
+ If a message is received via direct connection with the user agent (in the case of requests) or
+ the origin server (in the case of responses), then the date can be assumed to be the current date
+ at the receiving end. However, since the date--as it is believed by the origin--is important for
+ evaluating cached responses, origin servers should always include a <CODE>Date</CODE> header. Clients should
+ only send a <CODE>Date</CODE> header field in messages that include an entity body, as in the case of the <CODE>POST</CODE>
+ request, and even then it is optional. A received message which does not have a <CODE>Date</CODE> header
+ field should be assigned one by the recipient if the message will be cached by that recipient or
+ gatewayed via a protocol which requires a <CODE>Date</CODE>.
+<P>
+
+ In theory, the date should represent the moment just before the entity is generated. In practice,
+ the date can be generated at any time during the message origination without affecting its
+ semantic value.
+<P>
+
+<BLOCKQUOTE>
+ Note: An earlier version of this document incorrectly specified that this field should
+ contain the creation date of the enclosed <CODE>Entity-Body</CODE>. This has been changed to reflect
+ actual (and proper) usage.
+</BLOCKQUOTE>
+
+<H3>10.7 <A NAME="Expires">Expires</A></H3>
+
+ The <CODE>Expires</CODE> entity-header field gives the date/time after which the entity should be considered
+ stale. This allows information providers to suggest the volatility of the resource, or a date after
+ which the information may no longer be valid. Applications must not cache this entity beyond
+ the date given. The presence of an Expires field does not imply that the original resource will
+ change or cease to exist at, before, or after that time. However, information providers that know
+ or even suspect that a resource will change by a certain date should include an Expires header
+ with that date. The format is an absolute date and time as defined by <CODE>HTTP-date</CODE> in <A HREF="#DateFormats">Section 3.3</A>.
+<P>
+
+<PRE>
+ Expires = "Expires" ":" HTTP-date
+</PRE>
+
+ An example of its use is
+<P>
+
+<PRE>
+ Expires: Thu, 01 Dec 1994 16:00:00 GMT
+</PRE>
+
+ If the date given is equal to or earlier than the value of the <CODE>Date</CODE> header, the recipient must not
+ cache the enclosed entity. If a resource is dynamic by nature, as is the case with many
+ data-producing processes, entities from that resource should be given an appropriate Expires
+ value which reflects that dynamism.
+<P>
+
+ The Expires field cannot be used to force a user agent to refresh its display or reload a resource;
+ its semantics apply only to caching mechanisms, and such mechanisms need only check a
+ resource's expiration status when a new request for that resource is initiated.
+<P>
+
+ User agents often have history mechanisms, such as "Back" buttons and history lists, which can
+ be used to redisplay an entity retrieved earlier in a session. By default, the <CODE>Expires</CODE> field does not
+ apply to history mechanisms. If the entity is still in storage, a history mechanism should display
+ it even if the entity has expired, unless the user has specifically configured the agent to refresh
+ expired history documents.
+<P>
+
+<BLOCKQUOTE>
+ Note: Applications are encouraged to be tolerant of bad or misinformed
+ implementations of the Expires header. A value of zero (0) or an invalid date format
+ should be considered equivalent to an "expires immediately." Although these values
+ are not legitimate for HTTP/1.0, a robust implementation is always desirable.
+</BLOCKQUOTE>
+
+<H3>10.8 <A NAME="From">From</A></H3>
+
+ The <CODE>From</CODE> request-header field, if given, should contain an Internet e-mail address for the human
+ user who controls the requesting user agent. The address should be machine-usable, as defined
+ by <CODE>mailbox</CODE> in RFC 822<A HREF="#RefSTD11"> [7]</A> (as updated by RFC 1123<A HREF="#RefSTD3"> [6]</A>):
+<P>
+
+<PRE>
+ From = "From" ":" mailbox
+</PRE>
+
+ An example is:
+<P>
+
+<PRE>
+</PRE>
+
+ This header field may be used for logging purposes and as a means for identifying the source
+ of invalid or unwanted requests. It should not be used as an insecure form of access protection.
+ The interpretation of this field is that the request is being performed on behalf of the person
+ given, who accepts responsibility for the <CODE>method</CODE> performed. In particular, robot agents should
+ include this header so that the person responsible for running the robot can be contacted if
+ problems occur on the receiving end.
+<P>
+
+ The Internet e-mail address in this field may be separate from the Internet host which issued
+ the request. For example, when a request is passed through a proxy, the original issuer's address
+ should be used.
+<P>
+
+<BLOCKQUOTE>
+ Note: The client should not send the <CODE>From</CODE> header field without the user's approval, as
+ it may conflict with the user's privacy interests or their site's security policy. It is
+ strongly recommended that the user be able to disable, enable, and modify the value
+ of this field at any time prior to a request.
+</BLOCKQUOTE>
+
+<H3>10.9 <A NAME="If-Modified-Since">If-Modified-Since</A></H3>
+
+ The <CODE>If-Modified-Since</CODE> request-header field is used with the <CODE>GET</CODE> method to make it conditional:
+ if the requested resource has not been modified since the time specified in this field, a copy of
+ the resource will not be returned from the server; instead, a 304 (not modified) response will
+ be returned without any <CODE>Entity-Body</CODE>.
+<P>
+
+<PRE>
+ If-Modified-Since = "If-Modified-Since" ":" HTTP-date
+</PRE>
+
+ An example of the field is:
+
+<PRE>
+ If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+</PRE>
+
+ A conditional <CODE>GET</CODE> method requests that the identified resource be transferred only if it has been
+ modified since the date given by the <CODE>If-Modified-Since</CODE> header. The algorithm for determining this
+ includes the following cases:
+<P>
+
+<DL COMPACT>
+<DT>a)
+<DD>If the request would normally result in anything other than a 200 (ok) status, or if
+ the passed <CODE>If-Modified-Since</CODE> date is invalid, the response is exactly the same as for a
+ normal <CODE>GET</CODE>. A date which is later than the server's current time is invalid.
+
+<DT>b)
+<DD>If the resource has been modified since the <CODE>If-Modified-Since</CODE> date, the response is
+ exactly the same as for a normal <CODE>GET</CODE>.
+
+<DT>c)
+<DD>If the resource has not been modified since a valid <CODE>If-Modified-Since</CODE> date, the server
+ shall return a 304 (not modified) response.
+</DL>
+
+ The purpose of this feature is to allow efficient updates of cached information with a minimum
+ amount of transaction overhead.
+<P>
+
+<H3>10.10 <A NAME="Last-Modified">Last-Modified</A></H3>
+
+ The <CODE>Last-Modified</CODE> entity-header field indicates the date and time at which the sender believes
+ the resource was last modified. The exact semantics of this field are defined in terms of how the
+ recipient should interpret it: if the recipient has a copy of this resource which is older than the
+ date given by the <CODE>Last-Modified</CODE> field, that copy should be considered stale.
+<P>
+
+<PRE>
+ Last-Modified = "Last-Modified" ":" HTTP-date
+</PRE>
+
+ An example of its use is
+<P>
+
+<PRE>
+ Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
+</PRE>
+
+ The exact meaning of this header field depends on the implementation of the sender and the
+ nature of the original resource. For files, it may be just the file system last-modified time. For
+ entities with dynamically included parts, it may be the most recent of the set of last-modify
+ times for its component parts. For database gateways, it may be the last-update timestamp of
+ the record. For virtual objects, it may be the last time the internal state changed.
+<P>
+
+ An origin server must not send a Last-Modified date which is later than the server's time of
+ message origination. In such cases, where the resource's last modification would indicate some
+ time in the future, the server must replace that date with the message origination date.
+<P>
+
+<H3>10.11 <A NAME="Location">Location</A></H3>
+
+ The Location response-header field defines the exact location of the resource that was identified
+ by the <CODE>Request-URI</CODE>. For 3xx responses, the location must indicate the server's preferred URL
+ for automatic redirection to the resource. Only one absolute URL is allowed.
+<P>
+
+<PRE>
+ Location = "Location" ":" absoluteURI
+</PRE>
+
+ An example is
+<P>
+
+<PRE>
+ Location: http://www.w3.org/hypertext/WWW/NewLocation.html
+</PRE>
+
+<H3>10.12 <A NAME="Pragma">Pragma</A></H3>
+
+ The <CODE>Pragma</CODE> general-header field is used to include implementation-specific directives that may
+ apply to any recipient along the request/response chain. All pragma directives specify optional
+ behavior from the viewpoint of the protocol; however, some systems may require that behavior
+ be consistent with the directives.
+<P>
+
+<PRE>
+ Pragma = "Pragma" ":" 1#pragma-directive
+</PRE>
+
+<PRE>
+ pragma-directive = "no-cache" | extension-pragma
+ extension-pragma = token [ "=" word ]
+</PRE>
+
+ When the "<CODE>no-cache</CODE>" directive is present in a request message, an application should forward
+ the request toward the origin server even if it has a cached copy of what is being requested. This
+ allows a client to insist upon receiving an authoritative response to its request. It also allows a
+ client to refresh a cached copy which is known to be corrupted or stale.
+<P>
+
+ Pragma directives must be passed through by a proxy or gateway application, regardless of
+ their significance to that application, since the directives may be applicable to all recipients
+ along the request/response chain. It is not possible to specify a pragma for a specific recipient;
+ however, any pragma directive not relevant to a recipient should be ignored by that recipient.
+<P>
+
+<H3>10.13 <A NAME="Referer">Referer</A></H3>
+
+ The <CODE>Referer</CODE> request-header field allows the client to specify, for the server's benefit, the address
+ (URI) of the resource from which the <CODE>Request-URI</CODE> was obtained. This allows a server to
+ generate lists of back-links to resources for interest, logging, optimized caching, etc. It also
+ allows obsolete or mistyped links to be traced for maintenance. The <CODE>Referer</CODE> field must not be
+ sent if the <CODE>Request-URI</CODE> was obtained from a source that does not have its own URI, such as input
+ from the user keyboard.
+<P>
+
+<PRE>
+ Referer = "Referer" ":" ( absoluteURI | relativeURI )
+</PRE>
+
+ Example:
+<P>
+
+<PRE>
+ Referer: http://www.w3.org/hypertext/DataSources/Overview.html
+</PRE>
+
+ If a partial URI is given, it should be interpreted relative to the <CODE>Request-URI</CODE>. The URI must not
+ include a fragment.
+<P>
+
+<BLOCKQUOTE>
+ Note: Because the source of a link may be private information or may reveal an
+ otherwise private information source, it is strongly recommended that the user be
+ able to select whether or not the <CODE>Referer</CODE> field is sent. For example, a browser client
+ could have a toggle switch for browsing openly/anonymously, which would
+ respectively enable/disable the sending of <CODE>Referer</CODE> and <CODE>From</CODE> information.
+</BLOCKQUOTE>
+
+<H3>10.14 <A NAME="Server">Server</A></H3>
+
+ The <CODE>Server</CODE> response-header field contains information about the software used by the origin
+ server to handle the request. The field can contain multiple product tokens (<A HREF="#Product">Section 3.7</A>) and
+ comments identifying the server and any significant subproducts. By convention, the product
+ tokens are listed in order of their significance for identifying the application.
+<P>
+
+<PRE>
+ Server = "Server" ":" 1*( product | comment )
+</PRE>
+
+ Example:
+<P>
+
+<PRE>
+ Server: CERN/3.0 libwww/2.17
+</PRE>
+
+ If the response is being forwarded through a proxy, the proxy application must not add its data
+ to the product list.
+<P>
+
+<BLOCKQUOTE>
+ Note: Revealing the specific software version of the server may allow the server
+ machine to become more vulnerable to attacks against software that is known to
+ contain security holes. Server implementors are encouraged to make this field a
+ configurable option.
+</BLOCKQUOTE>
+
+<BLOCKQUOTE>
+ Note: Some existing servers fail to restrict themselves to the product token syntax
+ within the Server field.
+</BLOCKQUOTE>
+
+<H3>10.15 <A NAME="User-Agent">User-Agent</A></H3>
+
+ The <CODE>User-Agent</CODE> request-header field contains information about the user agent originating the
+ request. This is for statistical purposes, the tracing of protocol violations, and automated
+ recognition of user agents for the sake of tailoring responses to avoid particular user agent
+ limitations. Although it is not required, user agents should include this field with requests. The
+ field can contain multiple product tokens (<A HREF="#Product">Section 3.7</A>) and comments identifying the agent and
+ any subproducts which form a significant part of the user agent. By convention, the product
+ tokens are listed in order of their significance for identifying the application.
+<P>
+
+<PRE>
+ User-Agent = "User-Agent" ":" 1*( product | comment )
+</PRE>
+
+ Example:
+<P>
+
+<PRE>
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+</PRE>
+
+<BLOCKQUOTE>
+ Note: Some current proxy applications append their product information to the list in
+ the User-Agent field. This is not recommended, since it makes machine interpretation
+ of these fields ambiguous.
+</BLOCKQUOTE>
+
+<BLOCKQUOTE>
+ Note: Some existing clients fail to restrict themselves to the product token syntax
+ within the User-Agent field.
+</BLOCKQUOTE>
+
+<H3>10.16 <A NAME="WWW-Authenticate">WWW-Authenticate</A></H3>
+
+ The <CODE>WWW-Authenticate</CODE> response-header field must be included in 401 (unauthorized) response
+ messages. The field value consists of at least one <CODE>challenge</CODE> that indicates the authentication
+ scheme(s) and parameters applicable to the <CODE>Request-URI</CODE>.
+<P>
+
+<PRE>
+ WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
+</PRE>
+
+ The HTTP access authentication process is described in <A HREF="#AA">Section 11</A>. User agents must take
+ special care in parsing the <CODE>WWW-Authenticate</CODE> field value if it contains more than one challenge,
+ or if more than one <CODE>WWW-Authenticate</CODE> header field is provided, since the contents of a challenge
+ may itself contain a comma-separated list of authentication parameters.
+<P>
+
+<H2>11. <A NAME="AA">Access Authentication</A></H2>
+
+ HTTP provides a simple challenge-response authentication mechanism which may be used by
+ a server to challenge a client request and by a client to provide authentication information. It
+ uses an extensible, case-insensitive token to identify the authentication scheme, followed by a
+ comma-separated list of attribute-value pairs which carry the parameters necessary for
+ achieving authentication via that scheme.
+<P>
+
+<PRE>
+ auth-scheme = token
+</PRE>
+
+<PRE>
+ auth-param = token "=" quoted-string
+</PRE>
+
+ The 401 (unauthorized) response message is used by an origin server to challenge the
+ authorization of a user agent. This response must include a <CODE>WWW-Authenticate</CODE> header field
+ containing at least one <CODE>challenge</CODE> applicable to the requested resource.
+<P>
+
+<PRE>
+ challenge = auth-scheme 1*SP realm *( "," auth-param )
+</PRE>
+
+<PRE>
+ realm = "realm" "=" realm-value
+ realm-value = quoted-string
+</PRE>
+
+ The realm attribute (case-insensitive) is required for all authentication schemes which issue a
+ challenge. The realm value (case-sensitive), in combination with the canonical root URL of the
+ server being accessed, defines the protection space. These realms allow the protected resources
+ on a server to be partitioned into a set of protection spaces, each with its own authentication
+ scheme and/or authorization database. The realm value is a string, generally assigned by the
+ origin server, which may have additional semantics specific to the authentication scheme.
+<P>
+
+ A user agent that wishes to authenticate itself with a server--usually, but not necessarily, after
+ receiving a 401 response--may do so by including an <CODE>Authorization</CODE> header field with the
+ request. The <CODE>Authorization</CODE> field value consists of <CODE>credentials</CODE> containing the authentication
+ information of the user agent for the realm of the resource being requested.
+<P>
+
+<PRE>
+ credentials = basic-credentials
+ | ( auth-scheme #auth-param )
+</PRE>
+
+ The domain over which credentials can be automatically applied by a user agent is determined
+ by the protection space. If a prior request has been authorized, the same credentials may be
+ reused for all other requests within that protection space for a period of time determined by the
+ authentication scheme, parameters, and/or user preference. Unless otherwise defined by the
+ authentication scheme, a single protection space cannot extend outside the scope of its server.
+<P>
+
+ If the server does not wish to accept the credentials sent with a request, it should return a 403
+ (forbidden) response.
+<P>
+
+ The HTTP protocol does not restrict applications to this simple challenge-response mechanism
+ for access authentication. Additional mechanisms may be used, such as encryption at the
+ transport level or via message encapsulation, and with additional header fields specifying
+ authentication information. However, these additional mechanisms are not defined by this
+ specification.
+<P>
+
+ Proxies must be completely transparent regarding user agent authentication. That is, they must
+ forward the <CODE>WWW-Authenticate</CODE> and <CODE>Authorization</CODE> headers untouched, and must not cache the
+ response to a request containing <CODE>Authorization</CODE>. HTTP/1.0 does not provide a means for a client
+ to be authenticated with a proxy.
+<P>
+
+<H3>11.1 <A NAME="BasicAA">Basic Authentication Scheme</A></H3>
+
+ The "basic" authentication scheme is based on the model that the user agent must authenticate
+ itself with a user-ID and a password for each realm. The realm value should be considered an
+ opaque string which can only be compared for equality with other realms on that server. The
+ server will authorize the request only if it can validate the user-ID and password for the
+ protection space of the <CODE>Request-URI</CODE>. There are no optional authentication parameters.
+<P>
+
+ Upon receipt of an unauthorized request for a URI within the protection space, the server
+ should respond with a challenge like the following:
+<P>
+
+<PRE>
+ WWW-Authenticate: Basic realm="WallyWorld"
+</PRE>
+
+ where "WallyWorld" is the string assigned by the server to identify the protection space of the
+ <CODE>Request-URI</CODE>.
+<P>
+
+ To receive authorization, the client sends the user-ID and password, separated by a single colon
+ (":") character, within a base64<A HREF="#RefMIME1"> [5]</A> encoded string in the <CODE>credentials</CODE>.
+<P>
+
+<PRE>
+ basic-credentials = "Basic" SP basic-cookie
+</PRE>
+
+<PRE>
+ basic-cookie = &lt;base64<A HREF="#RefMIME1"> [5]</A> encoding of userid-password,
+ except not limited to 76 char/line&gt;
+</PRE>
+
+<PRE>
+ userid-password = [ token ] ":" *TEXT
+</PRE>
+
+ If the user agent wishes to send the user-ID "Aladdin" and password "open sesame", it would
+ use the following header field:
+<P>
+
+<PRE>
+ Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+</PRE>
+
+ The basic authentication scheme is a non-secure method of filtering unauthorized access to
+ resources on an HTTP server. It is based on the assumption that the connection between the
+ client and the server can be regarded as a trusted carrier. As this is not generally true on an open
+ network, the basic authentication scheme should be used accordingly. In spite of this, clients
+ should implement the scheme in order to communicate with servers that use it.
+<P>
+
+<H2>12. <A NAME="Security">Security Considerations</A></H2>
+
+ This section is meant to inform application developers, information providers, and users of the
+ security limitations in HTTP/1.0 as described by this document. The discussion does not
+ include definitive solutions to the problems revealed, though it does make some suggestions for
+ reducing security risks.
+<P>
+
+<H3>12.1 <A NAME="AuthSecurity">Authentication of Clients</A></H3>
+
+ As mentioned in <A HREF="#BasicAA">Section 11.1</A>, the Basic authentication scheme is not a secure method of user
+ authentication, nor does it prevent the <CODE>Entity-Body</CODE> from being transmitted in clear text across the
+ physical network used as the carrier. HTTP/1.0 does not prevent additional authentication
+ schemes and encryption mechanisms from being employed to increase security.
+<P>
+
+<H3>12.2 <A NAME="SafeMethods">Safe Methods</A></H3>
+
+ The writers of client software should be aware that the software represents the user in their
+ interactions over the Internet, and should be careful to allow the user to be aware of any actions
+ they may take which may have an unexpected significance to themselves or others.
+<P>
+
+ In particular, the convention has been established that the <CODE>GET</CODE> and <CODE>HEAD</CODE> methods should never
+ have the significance of taking an action other than retrieval. These methods should be
+ considered "safe." This allows user agents to represent other methods, such as <CODE>POST</CODE>, in a
+ special way, so that the user is made aware of the fact that a possibly unsafe action is being
+ requested.
+<P>
+
+ Naturally, it is not possible to ensure that the server does not generate side-effects as a result of
+ performing a <CODE>GET</CODE> request; in fact, some dynamic resources consider that a feature. The
+ important distinction here is that the user did not request the side-effects, so therefore cannot
+ be held accountable for them.
+<P>
+
+<H3>12.3 <A NAME="LogAbuse">Abuse of Server Log Information</A></H3>
+
+ A server is in the position to save personal data about a user's requests which may identify their
+ reading patterns or subjects of interest. This information is clearly confidential in nature and its
+ handling may be constrained by law in certain countries. People using the HTTP protocol to
+ provide data are responsible for ensuring that such material is not distributed without the
+ permission of any individuals that are identifiable by the published results.
+<P>
+
+<H3>12.4 <A NAME="Sensitive">Transfer of Sensitive Information</A></H3>
+
+ Like any generic data transfer protocol, HTTP cannot regulate the content of the data that is
+ transferred, nor is there any a priori method of determining the sensitivity of any particular
+ piece of information within the context of any given request. Therefore, applications should
+ supply as much control over this information as possible to the provider of that information.
+ Three header fields are worth special mention in this context: <CODE>Server</CODE>, <CODE>Referer</CODE> and <CODE>From</CODE>.
+<P>
+
+ Revealing the specific software version of the server may allow the server machine to become
+ more vulnerable to attacks against software that is known to contain security holes.
+ Implementors should make the <CODE>Server</CODE> header field a configurable option.
+<P>
+
+ The <CODE>Referer</CODE> field allows reading patterns to be studied and reverse links drawn. Although it can
+ be very useful, its power can be abused if user details are not separated from the information
+ contained in the <CODE>Referer</CODE>. Even when the personal information has been removed, the <CODE>Referer</CODE>
+ field may indicate a private document's URI whose publication would be inappropriate.
+<P>
+
+ The information sent in the <CODE>From</CODE> field might conflict with the user's privacy interests or their
+ site's security policy, and hence it should not be transmitted without the user being able to
+ disable, enable, and modify the contents of the field. The user must be able to set the contents
+ of this field within a user preference or application defaults configuration.
+<P>
+
+ We suggest, though do not require, that a convenient toggle interface be provided for the user
+ to enable or disable the sending of <CODE>From</CODE> and <CODE>Referer</CODE> information.
+<P>
+
+<H3>12.5 <A NAME="PathNameSecurity">Attacks Based On File and Path Names</A></H3>
+
+ Implementations of HTTP origin servers should be careful to restrict the documents returned
+ by HTTP requests to be only those that were intended by the server administrators. If an HTTP
+ server translates HTTP URIs directly into file system calls, the server must take special care
+ not to serve files that were not intended to be delivered to HTTP clients. For example, Unix,
+ Microsoft Windows, and other operating systems use ".." as a path component to indicate a
+ directory level above the current one. On such a system, an HTTP server must disallow any
+ such construct in the <CODE>Request-URI</CODE> if it would otherwise allow access to a resource outside those
+ intended to be accessible via the HTTP server. Similarly, files intended for reference only
+ internally to the server (such as access control files, configuration files, and script code) must
+ be protected from inappropriate retrieval, since they might contain sensitive information.
+ Experience has shown that minor bugs in such HTTP server implementations have turned into
+ security risks.
+<P>
+
+<H2>13. <A NAME="Acknowledgments">Acknowledgments</A></H2>
+
+ This specification makes heavy use of the augmented BNF and generic constructs defined by
+ David H. Crocker for RFC 822<A HREF="#RefSTD11"> [7]</A>. Similarly, it reuses many of the definitions provided by
+ Nathaniel Borenstein and Ned Freed for MIME<A HREF="#RefMIME1"> [5]</A>. We hope that their inclusion in this
+ specification will help reduce past confusion over the relationship between HTTP/1.0 and
+ Internet mail message formats.
+<P>
+
+ The HTTP protocol has evolved considerably over the past four years. It has benefited from a
+ large and active developer community--the many people who have participated on the
+ <EM>www-talk</EM> mailing list--and it is that community which has been most responsible for the
+ success of HTTP and of the World-Wide Web in general. Marc Andreessen, Robert Cailliau,
+ Daniel W. Connolly, Bob Denny, Jean-Francois Groff, Phillip M. Hallam-Baker, H&aring;kon W. Lie,
+ Ari Luotonen, Rob McCool, Lou Montulli, Dave Raggett, Tony Sanders, and
+ Marc VanHeyningen deserve special recognition for their efforts in defining aspects of the
+ protocol for early versions of this specification.
+<P>
+
+ Paul Hoffman contributed sections regarding the informational status of this document and
+ Appendices C and D.
+<P>
+
+ This document has benefited greatly from the comments of all those participating in the
+ HTTP-WG. In addition to those already mentioned, the following individuals have contributed
+ to this specification:
+<P>
+
+<PRE>
+ Gary Adams Harald Tveit Alvestrand
+ Keith Ball Brian Behlendorf
+ Paul Burchard Maurizio Codogno
+ Mike Cowlishaw Roman Czyborra
+ Michael A. Dolan John Franks
+ Jim Gettys Marc Hedlund
+ Koen Holtman Alex Hopmann
+ Bob Jernigan Shel Kaphan
+ Martijn Koster Dave Kristol
+ Daniel LaLiberte Paul Leach
+ Albert Lunde John C. Mallery
+ Larry Masinter Mitra
+ Jeffrey Mogul Gavin Nicol
+ Bill Perry Jeffrey Perry
+ Owen Rees Luigi Rizzo
+ David Robinson Marc Salomon
+ Rich Salz Jim Seidman
+ Chuck Shotton Eric W. Sink
+ Simon E. Spero Robert S. Thau
+ Fran&ccedil;ois Yergeau Mary Ellen Zurko
+ Jean-Philippe Martin-Flatin
+</PRE>
+
+<H2>14. <A NAME="References">References</A></H2>
+
+<DL COMPACT>
+<DT>[1]
+<DD><A NAME="RefGopher">Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey, D., and B. Alberti</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1436.txt">"The Internet Gopher Protocol:
+ A distributed document search and retrieval protocol"</A>,
+ RFC 1436, University of Minnesota, March 1993.
+
+<DT>[2]
+<DD><A NAME="RefURI">Berners-Lee, T.</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1630.txt">"Universal Resource Identifiers in WWW:
+ A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the
+ World-Wide Web"</A>, RFC 1630, CERN, June 1994.
+
+<DT>[3]
+<DD><A NAME="RefHTML">Berners-Lee, T., and D. Connolly</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1866.txt">"Hypertext Markup Language - 2.0"</A>,
+ RFC 1866, MIT/W3C, November 1995.
+
+<DT>[4]
+<DD><A NAME="RefURL">Berners-Lee, T., Masinter, L., and M. McCahill</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1738.txt">"Uniform Resource Locators (URL)"</A>,
+ RFC 1738, CERN, Xerox PARC, University of Minnesota, December 1994.
+
+<DT>[5]
+<DD><A NAME="RefMIME1">Borenstein, N., and N. Freed</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1521.ps">"MIME (Multipurpose Internet Mail Extensions) Part One:
+ Mechanisms for Specifying and Describing the Format of Internet Message Bodies"</A>,
+ RFC 1521, Bellcore, Innosoft, September 1993.
+
+<DT>[6]
+<DD><A NAME="RefSTD3">Braden, R.</A>,
+ <A HREF="http://ds.internic.net/std/std3.txt">"Requirements for Internet hosts - application and support"</A>,
+ STD 3, RFC 1123, IETF, October 1989.
+
+<DT>[7]
+<DD><A NAME="RefSTD11">Crocker, D.</A>,
+ <A HREF="http://ds.internic.net/std/std11.txt">"Standard for the Format of ARPA Internet Text Messages"</A>,
+ STD 11, RFC 822, UDEL, August 1982.
+
+<DT>[8]
+<DD><A NAME="RefWAIS">F. Davis, B. Kahle, H. Morris, J. Salem, T. Shen, R. Wang, J. Sui, and M. Grinbaum</A>.
+ "WAIS Interface Protocol Prototype Functional Specification." (v1.5), Thinking
+ Machines Corporation, April 1990.
+
+<DT>[9]
+<DD><A NAME="RefRelURL">Fielding, R.</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1808.txt">"Relative Uniform Resource Locators"</A>,
+ RFC 1808, UC Irvine, June 1995.
+
+<DT>[10]
+<DD><A NAME="RefUSENET">Horton, M., and R. Adams</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1036.txt">"Standard for interchange of USENET messages"</A>,
+ RFC 1036 (Obsoletes RFC 850), AT&amp;T Bell Laboratories, Center for Seismic Studies, December 1987.
+
+<DT>[11]
+<DD><A NAME="RefNNTP">Kantor, B., and P. Lapsley</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc977.txt">"Network News Transfer Protocol:
+ A Proposed Standard for the Stream-Based Transmission of News"</A>,
+ RFC 977, UC San Diego, UC Berkeley, February 1986.
+
+<DT>[12]
+<DD><A NAME="RefSMTP">Postel, J.</A>,
+ <A HREF="http://ds.internic.net/std/std10.txt">"Simple Mail Transfer Protocol"</A>,
+ STD 10, RFC 821, USC/ISI, August 1982.
+
+<DT>[13]
+<DD><A NAME="RefMediaType">Postel, J.</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1590.txt">"Media Type Registration Procedure"</A>,
+ RFC 1590, USC/ISI, March 1994.
+
+<DT>[14]
+<DD><A NAME="RefFTP">Postel, J., and J. Reynolds</A>,
+ <A HREF="http://ds.internic.net/std/std9.txt">"File Transfer Protocol (FTP)"</A>,
+ STD 9, RFC 959, USC/ISI, October 1985.
+
+<DT>[15]
+<DD><A NAME="RefIANA">Reynolds, J., and J. Postel</A>,
+ <A HREF="http://ds.internic.net/std/std2.txt">"Assigned Numbers"</A>,
+ STD 2, RFC 1700, USC/ISI, October 1994.
+
+<DT>[16]
+<DD><A NAME="RefURN">Sollins, K., and L. Masinter</A>,
+ <A HREF="http://ds.internic.net/rfc/rfc1737.txt">"Functional Requirements for Uniform Resource Names."</A>
+ RFC 1737, MIT/LCS, Xerox Corporation, December 1994.
+
+<DT>[17]
+<DD><A NAME="RefASCII">US-ASCII</A>.
+ Coded Character Set - 7-Bit American Standard Code for Information
+ Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
+
+<DT>[18]
+<DD><A NAME="RefISO8859">ISO-8859</A>.
+ International Standard -- Information Processing --<BR>
+ 8-bit Single-Byte Coded Graphic Character Sets --<BR>
+ Part 1: Latin alphabet No. 1, ISO 8859-1:1987.<BR>
+ Part 2: Latin alphabet No. 2, ISO 8859-2, 1987.<BR>
+ Part 3: Latin alphabet No. 3, ISO 8859-3, 1988.<BR>
+ Part 4: Latin alphabet No. 4, ISO 8859-4, 1988.<BR>
+ Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988.<BR>
+ Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987.<BR>
+ Part 7: Latin/Greek alphabet, ISO 8859-7, 1987.<BR>
+ Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988.<BR>
+ Part 9: Latin alphabet No. 5, ISO 8859-9, 1990.
+</DL>
+
+<H2>15. <A NAME="Authors">Authors' Addresses</A></H2>
+
+ <STRONG>Tim Berners-Lee</STRONG><BR>
+ Director, W3 Consortium<BR>
+ MIT Laboratory for Computer Science<BR>
+ 545 Technology Square<BR>
+ Cambridge, MA 02139, U.S.A.<BR>
+<BR>
+ Fax: +1 (617) 258 8682<BR>
+<P>
+ <STRONG>Roy T. Fielding</STRONG><BR>
+ Department of Information and Computer Science<BR>
+ University of California<BR>
+ Irvine, CA 92717-3425, U.S.A.<BR>
+<BR>
+ Fax: +1 (714) 824-4056<BR>
+<P>
+ <STRONG>Henrik Frystyk Nielsen</STRONG><BR>
+ W3 Consortium<BR>
+ MIT Laboratory for Computer Science<BR>
+ 545 Technology Square<BR>
+ Cambridge, MA 02139, U.S.A.<BR>
+<BR>
+ Fax: +1 (617) 258 8682<BR>
+<P>
+
+<H2><A NAME="Appendices">Appendices</A></H2>
+
+ These appendices are provided for informational reasons only -- they do not form a part of the
+ HTTP/1.0 specification.
+<P>
+
+<H2>A. <A NAME="message_http">Internet Media Type message/http</A></H2>
+
+ In addition to defining the HTTP/1.0 protocol, this document serves as the specification for the
+ Internet media type "message/http". The following is to be registered with IANA<A HREF="#RefMediaType"> [13]</A>.
+<P>
+
+<PRE>
+ Media Type name: message
+
+ Media subtype name: http
+
+ Required parameters: none
+
+ Optional parameters: version, msgtype
+
+ version: The HTTP-Version number of the enclosed message
+ (e.g., "1.0"). If not present, the version can be
+ determined from the first line of the body.
+
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+
+ Security considerations: none
+</PRE>
+
+<H2>B. <A NAME="Tolerant">Tolerant Applications</A></H2>
+
+ Although this document specifies the requirements for the generation of HTTP/1.0 messages,
+ not all applications will be correct in their implementation. We therefore recommend that
+ operational applications be tolerant of deviations whenever those deviations can be interpreted
+ unambiguously.
+<P>
+
+ Clients should be tolerant in parsing the <CODE>Status-Line</CODE> and servers tolerant when parsing the
+ <CODE>Request-Line</CODE>. In particular, they should accept any amount of <CODE>SP</CODE> or <CODE>HT</CODE> characters between
+ fields, even though only a single <CODE>SP</CODE> is required.
+<P>
+
+ The line terminator for <CODE>HTTP-header</CODE> fields is the sequence <CODE>CRLF</CODE>. However, we recommend that
+ applications, when parsing such headers, recognize a single <CODE>LF</CODE> as a line terminator and ignore
+ the leading <CODE>CR</CODE>.
+<P>
+
+<H2>C. <A NAME="MIME">Relationship to MIME</A></H2>
+
+ HTTP/1.0 uses many of the constructs defined for Internet Mail (RFC 822<A HREF="#RefSTD11"> [7]</A>) and the
+ Multipurpose Internet Mail Extensions (MIME<A HREF="#RefMIME1"> [5]</A>) to allow entities to be transmitted in an
+ open variety of representations and with extensible mechanisms. However, RFC 1521
+ discusses mail, and HTTP has a few features that are different than those described in
+ RFC 1521. These differences were carefully chosen to optimize performance over binary
+ connections, to allow greater freedom in the use of new media types, to make date comparisons
+ easier, and to acknowledge the practice of some early HTTP servers and clients.
+<P>
+
+ At the time of this writing, it is expected that RFC 1521 will be revised. The revisions may
+ include some of the practices found in HTTP/1.0 but not in RFC 1521.
+<P>
+
+ This appendix describes specific areas where HTTP differs from RFC 1521. Proxies and
+ gateways to strict MIME environments should be aware of these differences and provide the
+ appropriate conversions where necessary. Proxies and gateways from MIME environments to
+ HTTP also need to be aware of the differences because some conversions may be required.
+<P>
+
+<H3>C.1 <A NAME="MIME-Canonical">Conversion to Canonical Form</A></H3>
+
+ RFC 1521 requires that an Internet mail entity be converted to canonical form prior to being
+ transferred, as described in Appendix G of RFC 1521<A HREF="#RefMIME1"> [5]</A>.
+ <A HREF="#TextCanonicalization">Section 3.6.1</A> of this document
+ describes the forms allowed for subtypes of the "text" media type when transmitted over HTTP.
+<P>
+
+ RFC 1521 requires that content with a Content-Type of "text" represent line breaks as CRLF
+ and forbids the use of CR or LF outside of line break sequences. HTTP allows CRLF, bare CR,
+ and bare LF to indicate a line break within text content when a message is transmitted over
+ HTTP.
+<P>
+
+ Where it is possible, a proxy or gateway from HTTP to a strict RFC 1521 environment should
+ translate all line breaks within the text media types described in <A HREF="#TextCanonicalization">Section 3.6.1</A> of this document
+ to the RFC 1521 canonical form of <CODE>CRLF</CODE>. Note, however, that this may be complicated by the
+ presence of a <CODE>Content-Encoding</CODE> and by the fact that HTTP allows the use of some character sets
+ which do not use octets 13 and 10 to represent <CODE>CR</CODE> and <CODE>LF</CODE>, as is the case for some multi-byte
+ character sets.
+<P>
+
+<H3>C.2 <A NAME="MIME-Date">Conversion of Date Formats</A></H3>
+
+ HTTP/1.0 uses a restricted set of date formats (<A HREF="#DateFormats">Section 3.3</A>) to simplify the process of date
+ comparison. Proxies and gateways from other protocols should ensure that any <CODE>Date</CODE> header
+ field present in a message conforms to one of the HTTP/1.0 formats and rewrite the date if
+ necessary.
+<P>
+
+<H3>C.3 <A NAME="MIME-CE">Introduction of Content-Encoding</A></H3>
+
+ RFC 1521 does not include any concept equivalent to HTTP/1.0's <CODE>Content-Encoding</CODE> header
+ field. Since this acts as a modifier on the media type, proxies and gateways from HTTP to
+ MIME-compliant protocols must either change the value of the <CODE>Content-Type</CODE> header field or
+ decode the <CODE>Entity-Body</CODE> before forwarding the message. (Some experimental applications of
+ <CODE>Content-Type</CODE> for Internet mail have used a media-type parameter of
+ <CODE>";conversions=&lt;content-coding&gt;"</CODE> to perform an equivalent function as
+ Content-Encoding. However, this parameter is not part of RFC 1521.)
+<P>
+
+<H3>C.4 <A NAME="MIME-CTE">No Content-Transfer-Encoding</A></H3>
+
+ HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC 1521. Proxies and
+ gateways from MIME-compliant protocols to HTTP must remove any non-identity CTE
+ ("quoted-printable" or "base64") encoding prior to delivering the response message to an
+ HTTP client.
+<P>
+
+ Proxies and gateways from HTTP to MIME-compliant protocols are responsible for ensuring
+ that the message is in the correct format and encoding for safe transport on that protocol, where
+ "safe transport" is defined by the limitations of the protocol being used. Such a proxy or
+ gateway should label the data with an appropriate Content-Transfer-Encoding if doing so will
+ improve the likelihood of safe transport over the destination protocol.
+<P>
+
+<H3>C.5 <A NAME="MIME-parts">HTTP Header Fields in Multipart Body-Parts</A></H3>
+
+ In RFC 1521, most header fields in multipart body-parts are generally ignored unless the field
+ name begins with "Content-". In HTTP/1.0, multipart body-parts may contain any HTTP
+ header fields which are significant to the meaning of that part.
+<P>
+
+<H2>D. <A NAME="Additional">Additional Features</A></H2>
+
+ This appendix documents protocol elements used by some existing HTTP implementations,
+ but not consistently and correctly across most HTTP/1.0 applications. Implementors should be
+ aware of these features, but cannot rely upon their presence in, or interoperability with, other
+ HTTP/1.0 applications.
+<P>
+
+<H3>D.1 <A NAME="Additional-Methods">Additional Request Methods</A></H3>
+
+<H4>D.1.1 <A NAME="PUT">PUT</A></H4>
+
+ The PUT method requests that the enclosed entity be stored under the supplied <CODE>Request-URI</CODE>. If
+ the <CODE>Request-URI</CODE> refers to an already existing resource, the enclosed entity should be considered
+ as a modified version of the one residing on the origin server. If the <CODE>Request-URI</CODE> does not point
+ to an existing resource, and that URI is capable of being defined as a new resource by the
+ requesting user agent, the origin server can create the resource with that URI.
+<P>
+
+ The fundamental difference between the POST and PUT requests is reflected in the different
+ meaning of the <CODE>Request-URI</CODE>. The URI in a POST request identifies the resource that will handle
+ the enclosed entity as data to be processed. That resource may be a data-accepting process, a
+ gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the
+ URI in a PUT request identifies the entity enclosed with the request -- the user agent knows
+ what URI is intended and the server should not apply the request to some other resource.
+<P>
+
+<H4>D.1.2 <A NAME="DELETE">DELETE</A></H4>
+
+ The DELETE method requests that the origin server delete the resource identified by the
+ <CODE>Request-URI</CODE>.
+<P>
+
+<H4>D.1.3 <A NAME="LINK">LINK</A></H4>
+
+ The LINK method establishes one or more Link relationships between the existing resource
+ identified by the <CODE>Request-URI</CODE> and other existing resources.
+<P>
+
+<H4>D.1.4 <A NAME="UNLINK">UNLINK</A></H4>
+
+ The UNLINK method removes one or more Link relationships from the existing resource
+ identified by the <CODE>Request-URI</CODE>.
+<P>
+
+<H3>D.2 <A NAME="Additional-Headers">Additional Header Field Definitions</A></H3>
+
+<H4>D.2.1 <A NAME="Accept">Accept</A></H4>
+
+ The Accept request-header field can be used to indicate a list of media ranges which are
+ acceptable as a response to the request. The asterisk "*" character is used to group media types
+ into ranges, with "*/*" indicating all media types and "type/*" indicating all subtypes of that
+ type. The set of ranges given by the client should represent what types are acceptable given the
+ context of the request.
+<P>
+
+<H4>D.2.2 <A NAME="Accept-Charset">Accept-Charset</A></H4>
+
+ The Accept-Charset request-header field can be used to indicate a list of preferred character sets
+ other than the default US-ASCII and ISO-8859-1. This field allows clients capable of
+ understanding more comprehensive or special-purpose character sets to signal that capability
+ to a server which is capable of representing documents in those character sets.
+<P>
+
+<H4>D.2.3 <A NAME="Accept-Encoding">Accept-Encoding</A></H4>
+
+ The Accept-Encoding request-header field is similar to Accept, but restricts the content-coding
+ values which are acceptable in the response.
+<P>
+
+<H4>D.2.4 <A NAME="Accept-Language">Accept-Language</A></H4>
+
+ The Accept-Language request-header field is similar to Accept, but restricts the set of natural
+ languages that are preferred as a response to the request.
+<P>
+
+<H4>D.2.5 <A NAME="Content-Language">Content-Language</A></H4>
+
+ The Content-Language entity-header field describes the natural language(s) of the intended
+ audience for the enclosed entity. Note that this may not be equivalent to all the languages used
+ within the entity.
+<P>
+
+<H4>D.2.6 <A NAME="Link">Link</A></H4>
+
+ The Link entity-header field provides a means for describing a relationship between the entity
+ and some other resource. An entity may include multiple Link values. Links at the
+ metainformation level typically indicate relationships like hierarchical structure and navigation
+ paths.
+<P>
+
+<H4>D.2.7 <A NAME="MIME-Version">MIME-Version</A></H4>
+
+ HTTP messages may include a single MIME-Version general-header field to indicate what
+ version of the MIME protocol was used to construct the message. Use of the MIME-Version
+ header field, as defined by RFC 1521<A HREF="#RefMIME1"> [5]</A>, should indicate that the message is
+ MIME-conformant. Unfortunately, some older HTTP/1.0 servers send it indiscriminately, and
+ thus this field should be ignored.
+<P>
+
+<H4>D.2.8 <A NAME="Retry-After">Retry-After</A></H4>
+
+ The Retry-After response-header field can be used with a 503 (service unavailable) response to
+ indicate how long the service is expected to be unavailable to the requesting client. The value
+ of this field can be either an HTTP-date or an integer number of seconds (in decimal) after the
+ time of the response.
+<P>
+
+<H4>D.2.9 <A NAME="Title">Title</A></H4>
+
+ The Title entity-header field indicates the title of the entity.
+<P>
+
+<H4>D.2.10 <A NAME="URI-header">URI</A></H4>
+
+ The URI entity-header field may contain some or all of the Uniform Resource Identifiers
+ (<A HREF="#URI">Section 3.2</A>) by which the <CODE>Request-URI</CODE> resource can be identified. There is no guarantee that
+ the resource can be accessed using the URI(s) specified.
+
+</BODY></HTML>
diff --git a/lib/inets/doc/archive/rfc2068.txt b/lib/inets/doc/archive/rfc2068.txt
new file mode 100644
index 0000000000..e16e4fdf7d
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2068.txt
@@ -0,0 +1,9075 @@
+
+
+
+
+
+
+Network Working Group R. Fielding
+Request for Comments: 2068 UC Irvine
+Category: Standards Track J. Gettys
+ J. Mogul
+ DEC
+ H. Frystyk
+ T. Berners-Lee
+ MIT/LCS
+ January 1997
+
+
+ Hypertext Transfer Protocol -- HTTP/1.1
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Abstract
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. It is a generic, stateless, object-oriented protocol which
+ can be used for many tasks, such as name servers and distributed
+ object management systems, through extension of its request methods.
+ A feature of HTTP is the typing and negotiation of data
+ representation, allowing systems to be built independently of the
+ data being transferred.
+
+ HTTP has been in use by the World-Wide Web global information
+ initiative since 1990. This specification defines the protocol
+ referred to as "HTTP/1.1".
+
+Table of Contents
+
+ 1 Introduction.............................................7
+ 1.1 Purpose ..............................................7
+ 1.2 Requirements .........................................7
+ 1.3 Terminology ..........................................8
+ 1.4 Overall Operation ...................................11
+ 2 Notational Conventions and Generic Grammar..............13
+ 2.1 Augmented BNF .......................................13
+ 2.2 Basic Rules .........................................15
+ 3 Protocol Parameters.....................................17
+ 3.1 HTTP Version ........................................17
+
+
+
+Fielding, et. al. Standards Track [Page 1]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 3.2 Uniform Resource Identifiers ........................18
+ 3.2.1 General Syntax ...................................18
+ 3.2.2 http URL .........................................19
+ 3.2.3 URI Comparison ...................................20
+ 3.3 Date/Time Formats ...................................21
+ 3.3.1 Full Date ........................................21
+ 3.3.2 Delta Seconds ....................................22
+ 3.4 Character Sets ......................................22
+ 3.5 Content Codings .....................................23
+ 3.6 Transfer Codings ....................................24
+ 3.7 Media Types .........................................25
+ 3.7.1 Canonicalization and Text Defaults ...............26
+ 3.7.2 Multipart Types ..................................27
+ 3.8 Product Tokens ......................................28
+ 3.9 Quality Values ......................................28
+ 3.10 Language Tags ......................................28
+ 3.11 Entity Tags ........................................29
+ 3.12 Range Units ........................................30
+ 4 HTTP Message............................................30
+ 4.1 Message Types .......................................30
+ 4.2 Message Headers .....................................31
+ 4.3 Message Body ........................................32
+ 4.4 Message Length ......................................32
+ 4.5 General Header Fields ...............................34
+ 5 Request.................................................34
+ 5.1 Request-Line ........................................34
+ 5.1.1 Method ...........................................35
+ 5.1.2 Request-URI ......................................35
+ 5.2 The Resource Identified by a Request ................37
+ 5.3 Request Header Fields ...............................37
+ 6 Response................................................38
+ 6.1 Status-Line .........................................38
+ 6.1.1 Status Code and Reason Phrase ....................39
+ 6.2 Response Header Fields ..............................41
+ 7 Entity..................................................41
+ 7.1 Entity Header Fields ................................41
+ 7.2 Entity Body .........................................42
+ 7.2.1 Type .............................................42
+ 7.2.2 Length ...........................................43
+ 8 Connections.............................................43
+ 8.1 Persistent Connections ..............................43
+ 8.1.1 Purpose ..........................................43
+ 8.1.2 Overall Operation ................................44
+ 8.1.3 Proxy Servers ....................................45
+ 8.1.4 Practical Considerations .........................45
+ 8.2 Message Transmission Requirements ...................46
+ 9 Method Definitions......................................48
+ 9.1 Safe and Idempotent Methods .........................48
+
+
+
+Fielding, et. al. Standards Track [Page 2]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 9.1.1 Safe Methods .....................................48
+ 9.1.2 Idempotent Methods ...............................49
+ 9.2 OPTIONS .............................................49
+ 9.3 GET .................................................50
+ 9.4 HEAD ................................................50
+ 9.5 POST ................................................51
+ 9.6 PUT .................................................52
+ 9.7 DELETE ..............................................53
+ 9.8 TRACE ...............................................53
+ 10 Status Code Definitions................................53
+ 10.1 Informational 1xx ..................................54
+ 10.1.1 100 Continue ....................................54
+ 10.1.2 101 Switching Protocols .........................54
+ 10.2 Successful 2xx .....................................54
+ 10.2.1 200 OK ..........................................54
+ 10.2.2 201 Created .....................................55
+ 10.2.3 202 Accepted ....................................55
+ 10.2.4 203 Non-Authoritative Information ...............55
+ 10.2.5 204 No Content ..................................55
+ 10.2.6 205 Reset Content ...............................56
+ 10.2.7 206 Partial Content .............................56
+ 10.3 Redirection 3xx ....................................56
+ 10.3.1 300 Multiple Choices ............................57
+ 10.3.2 301 Moved Permanently ...........................57
+ 10.3.3 302 Moved Temporarily ...........................58
+ 10.3.4 303 See Other ...................................58
+ 10.3.5 304 Not Modified ................................58
+ 10.3.6 305 Use Proxy ...................................59
+ 10.4 Client Error 4xx ...................................59
+ 10.4.1 400 Bad Request .................................60
+ 10.4.2 401 Unauthorized ................................60
+ 10.4.3 402 Payment Required ............................60
+ 10.4.4 403 Forbidden ...................................60
+ 10.4.5 404 Not Found ...................................60
+ 10.4.6 405 Method Not Allowed ..........................61
+ 10.4.7 406 Not Acceptable ..............................61
+ 10.4.8 407 Proxy Authentication Required ...............61
+ 10.4.9 408 Request Timeout .............................62
+ 10.4.10 409 Conflict ...................................62
+ 10.4.11 410 Gone .......................................62
+ 10.4.12 411 Length Required ............................63
+ 10.4.13 412 Precondition Failed ........................63
+ 10.4.14 413 Request Entity Too Large ...................63
+ 10.4.15 414 Request-URI Too Long .......................63
+ 10.4.16 415 Unsupported Media Type .....................63
+ 10.5 Server Error 5xx ...................................64
+ 10.5.1 500 Internal Server Error .......................64
+ 10.5.2 501 Not Implemented .............................64
+
+
+
+Fielding, et. al. Standards Track [Page 3]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 10.5.3 502 Bad Gateway .................................64
+ 10.5.4 503 Service Unavailable .........................64
+ 10.5.5 504 Gateway Timeout .............................64
+ 10.5.6 505 HTTP Version Not Supported ..................65
+ 11 Access Authentication..................................65
+ 11.1 Basic Authentication Scheme ........................66
+ 11.2 Digest Authentication Scheme .......................67
+ 12 Content Negotiation....................................67
+ 12.1 Server-driven Negotiation ..........................68
+ 12.2 Agent-driven Negotiation ...........................69
+ 12.3 Transparent Negotiation ............................70
+ 13 Caching in HTTP........................................70
+ 13.1.1 Cache Correctness ...............................72
+ 13.1.2 Warnings ........................................73
+ 13.1.3 Cache-control Mechanisms ........................74
+ 13.1.4 Explicit User Agent Warnings ....................74
+ 13.1.5 Exceptions to the Rules and Warnings ............75
+ 13.1.6 Client-controlled Behavior ......................75
+ 13.2 Expiration Model ...................................75
+ 13.2.1 Server-Specified Expiration .....................75
+ 13.2.2 Heuristic Expiration ............................76
+ 13.2.3 Age Calculations ................................77
+ 13.2.4 Expiration Calculations .........................79
+ 13.2.5 Disambiguating Expiration Values ................80
+ 13.2.6 Disambiguating Multiple Responses ...............80
+ 13.3 Validation Model ...................................81
+ 13.3.1 Last-modified Dates .............................82
+ 13.3.2 Entity Tag Cache Validators .....................82
+ 13.3.3 Weak and Strong Validators ......................82
+ 13.3.4 Rules for When to Use Entity Tags and Last-
+ modified Dates..........................................85
+ 13.3.5 Non-validating Conditionals .....................86
+ 13.4 Response Cachability ...............................86
+ 13.5 Constructing Responses From Caches .................87
+ 13.5.1 End-to-end and Hop-by-hop Headers ...............88
+ 13.5.2 Non-modifiable Headers ..........................88
+ 13.5.3 Combining Headers ...............................89
+ 13.5.4 Combining Byte Ranges ...........................90
+ 13.6 Caching Negotiated Responses .......................90
+ 13.7 Shared and Non-Shared Caches .......................91
+ 13.8 Errors or Incomplete Response Cache Behavior .......91
+ 13.9 Side Effects of GET and HEAD .......................92
+ 13.10 Invalidation After Updates or Deletions ...........92
+ 13.11 Write-Through Mandatory ...........................93
+ 13.12 Cache Replacement .................................93
+ 13.13 History Lists .....................................93
+ 14 Header Field Definitions...............................94
+ 14.1 Accept .............................................95
+
+
+
+Fielding, et. al. Standards Track [Page 4]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 14.2 Accept-Charset .....................................97
+ 14.3 Accept-Encoding ....................................97
+ 14.4 Accept-Language ....................................98
+ 14.5 Accept-Ranges ......................................99
+ 14.6 Age ................................................99
+ 14.7 Allow .............................................100
+ 14.8 Authorization .....................................100
+ 14.9 Cache-Control .....................................101
+ 14.9.1 What is Cachable ...............................103
+ 14.9.2 What May be Stored by Caches ...................103
+ 14.9.3 Modifications of the Basic Expiration Mechanism 104
+ 14.9.4 Cache Revalidation and Reload Controls .........105
+ 14.9.5 No-Transform Directive .........................107
+ 14.9.6 Cache Control Extensions .......................108
+ 14.10 Connection .......................................109
+ 14.11 Content-Base .....................................109
+ 14.12 Content-Encoding .................................110
+ 14.13 Content-Language .................................110
+ 14.14 Content-Length ...................................111
+ 14.15 Content-Location .................................112
+ 14.16 Content-MD5 ......................................113
+ 14.17 Content-Range ....................................114
+ 14.18 Content-Type .....................................116
+ 14.19 Date .............................................116
+ 14.20 ETag .............................................117
+ 14.21 Expires ..........................................117
+ 14.22 From .............................................118
+ 14.23 Host .............................................119
+ 14.24 If-Modified-Since ................................119
+ 14.25 If-Match .........................................121
+ 14.26 If-None-Match ....................................122
+ 14.27 If-Range .........................................123
+ 14.28 If-Unmodified-Since ..............................124
+ 14.29 Last-Modified ....................................124
+ 14.30 Location .........................................125
+ 14.31 Max-Forwards .....................................125
+ 14.32 Pragma ...........................................126
+ 14.33 Proxy-Authenticate ...............................127
+ 14.34 Proxy-Authorization ..............................127
+ 14.35 Public ...........................................127
+ 14.36 Range ............................................128
+ 14.36.1 Byte Ranges ...................................128
+ 14.36.2 Range Retrieval Requests ......................130
+ 14.37 Referer ..........................................131
+ 14.38 Retry-After ......................................131
+ 14.39 Server ...........................................132
+ 14.40 Transfer-Encoding ................................132
+ 14.41 Upgrade ..........................................132
+
+
+
+Fielding, et. al. Standards Track [Page 5]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 14.42 User-Agent .......................................134
+ 14.43 Vary .............................................134
+ 14.44 Via ..............................................135
+ 14.45 Warning ..........................................137
+ 14.46 WWW-Authenticate .................................139
+ 15 Security Considerations...............................139
+ 15.1 Authentication of Clients .........................139
+ 15.2 Offering a Choice of Authentication Schemes .......140
+ 15.3 Abuse of Server Log Information ...................141
+ 15.4 Transfer of Sensitive Information .................141
+ 15.5 Attacks Based On File and Path Names ..............142
+ 15.6 Personal Information ..............................143
+ 15.7 Privacy Issues Connected to Accept Headers ........143
+ 15.8 DNS Spoofing ......................................144
+ 15.9 Location Headers and Spoofing .....................144
+ 16 Acknowledgments.......................................144
+ 17 References............................................146
+ 18 Authors' Addresses....................................149
+ 19 Appendices............................................150
+ 19.1 Internet Media Type message/http ..................150
+ 19.2 Internet Media Type multipart/byteranges ..........150
+ 19.3 Tolerant Applications .............................151
+ 19.4 Differences Between HTTP Entities and
+ MIME Entities...........................................152
+ 19.4.1 Conversion to Canonical Form ...................152
+ 19.4.2 Conversion of Date Formats .....................153
+ 19.4.3 Introduction of Content-Encoding ...............153
+ 19.4.4 No Content-Transfer-Encoding ...................153
+ 19.4.5 HTTP Header Fields in Multipart Body-Parts .....153
+ 19.4.6 Introduction of Transfer-Encoding ..............154
+ 19.4.7 MIME-Version ...................................154
+ 19.5 Changes from HTTP/1.0 .............................154
+ 19.5.1 Changes to Simplify Multi-homed Web Servers and
+ Conserve IP Addresses .................................155
+ 19.6 Additional Features ...............................156
+ 19.6.1 Additional Request Methods .....................156
+ 19.6.2 Additional Header Field Definitions ............156
+ 19.7 Compatibility with Previous Versions ..............160
+ 19.7.1 Compatibility with HTTP/1.0 Persistent
+ Connections............................................161
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 6]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+1 Introduction
+
+1.1 Purpose
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. HTTP has been in use by the World-Wide Web global
+ information initiative since 1990. The first version of HTTP,
+ referred to as HTTP/0.9, was a simple protocol for raw data transfer
+ across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved
+ the protocol by allowing messages to be in the format of MIME-like
+ messages, containing metainformation about the data transferred and
+ modifiers on the request/response semantics. However, HTTP/1.0 does
+ not sufficiently take into consideration the effects of hierarchical
+ proxies, caching, the need for persistent connections, and virtual
+ hosts. In addition, the proliferation of incompletely-implemented
+ applications calling themselves "HTTP/1.0" has necessitated a
+ protocol version change in order for two communicating applications
+ to determine each other's true capabilities.
+
+ This specification defines the protocol referred to as "HTTP/1.1".
+ This protocol includes more stringent requirements than HTTP/1.0 in
+ order to ensure reliable implementation of its features.
+
+ Practical information systems require more functionality than simple
+ retrieval, including search, front-end update, and annotation. HTTP
+ allows an open-ended set of methods that indicate the purpose of a
+ request. It builds on the discipline of reference provided by the
+ Uniform Resource Identifier (URI) [3][20], as a location (URL) [4] or
+ name (URN) , for indicating the resource to which a method is to be
+ applied. Messages are passed in a format similar to that used by
+ Internet mail as defined by the Multipurpose Internet Mail Extensions
+ (MIME).
+
+ HTTP is also used as a generic protocol for communication between
+ user agents and proxies/gateways to other Internet systems, including
+ those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2],
+ and WAIS [10] protocols. In this way, HTTP allows basic hypermedia
+ access to resources available from diverse applications.
+
+1.2 Requirements
+
+ This specification uses the same words as RFC 1123 [8] for defining
+ the significance of each particular requirement. These words are:
+
+ MUST
+ This word or the adjective "required" means that the item is an
+ absolute requirement of the specification.
+
+
+
+Fielding, et. al. Standards Track [Page 7]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ SHOULD
+ This word or the adjective "recommended" means that there may
+ exist valid reasons in particular circumstances to ignore this
+ item, but the full implications should be understood and the case
+ carefully weighed before choosing a different course.
+
+ MAY
+ This word or the adjective "optional" means that this item is
+ truly optional. One vendor may choose to include the item because
+ a particular marketplace requires it or because it enhances the
+ product, for example; another vendor may omit the same item.
+
+ An implementation is not compliant if it fails to satisfy one or more
+ of the MUST requirements for the protocols it implements. An
+ implementation that satisfies all the MUST and all the SHOULD
+ requirements for its protocols is said to be "unconditionally
+ compliant"; one that satisfies all the MUST requirements but not all
+ the SHOULD requirements for its protocols is said to be
+ "conditionally compliant."
+
+1.3 Terminology
+
+ This specification uses a number of terms to refer to the roles
+ played by participants in, and objects of, the HTTP communication.
+
+ connection
+ A transport layer virtual circuit established between two programs
+ for the purpose of communication.
+
+ message
+ The basic unit of HTTP communication, consisting of a structured
+ sequence of octets matching the syntax defined in section 4 and
+ transmitted via the connection.
+
+ request
+ An HTTP request message, as defined in section 5.
+
+ response
+ An HTTP response message, as defined in section 6.
+
+ resource
+ A network data object or service that can be identified by a URI,
+ as defined in section 3.2. Resources may be available in multiple
+ representations (e.g. multiple languages, data formats, size,
+ resolutions) or vary in other ways.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 8]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ entity
+ The information transferred as the payload of a request or
+ response. An entity consists of metainformation in the form of
+ entity-header fields and content in the form of an entity-body, as
+ described in section 7.
+
+ representation
+ An entity included with a response that is subject to content
+ negotiation, as described in section 12. There may exist multiple
+ representations associated with a particular response status.
+
+ content negotiation
+ The mechanism for selecting the appropriate representation when
+ servicing a request, as described in section 12. The
+ representation of entities in any response can be negotiated
+ (including error responses).
+
+ variant
+ A resource may have one, or more than one, representation(s)
+ associated with it at any given instant. Each of these
+ representations is termed a `variant.' Use of the term `variant'
+ does not necessarily imply that the resource is subject to content
+ negotiation.
+
+ client
+ A program that establishes connections for the purpose of sending
+ requests.
+
+ user agent
+ The client which initiates a request. These are often browsers,
+ editors, spiders (web-traversing robots), or other end user tools.
+
+ server
+ An application program that accepts connections in order to
+ service requests by sending back responses. Any given program may
+ be capable of being both a client and a server; our use of these
+ terms refers only to the role being performed by the program for a
+ particular connection, rather than to the program's capabilities
+ in general. Likewise, any server may act as an origin server,
+ proxy, gateway, or tunnel, switching behavior based on the nature
+ of each request.
+
+ origin server
+ The server on which a given resource resides or is to be created.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 9]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ proxy
+ An intermediary program which acts as both a server and a client
+ for the purpose of making requests on behalf of other clients.
+ Requests are serviced internally or by passing them on, with
+ possible translation, to other servers. A proxy must implement
+ both the client and server requirements of this specification.
+
+ gateway
+ A server which acts as an intermediary for some other server.
+ Unlike a proxy, a gateway receives requests as if it were the
+ origin server for the requested resource; the requesting client
+ may not be aware that it is communicating with a gateway.
+
+ tunnel
+ An intermediary program which is acting as a blind relay between
+ two connections. Once active, a tunnel is not considered a party
+ to the HTTP communication, though the tunnel may have been
+ initiated by an HTTP request. The tunnel ceases to exist when both
+ ends of the relayed connections are closed.
+
+ cache
+ A program's local store of response messages and the subsystem
+ that controls its message storage, retrieval, and deletion. A
+ cache stores cachable responses in order to reduce the response
+ time and network bandwidth consumption on future, equivalent
+ requests. Any client or server may include a cache, though a cache
+ cannot be used by a server that is acting as a tunnel.
+
+ cachable
+ A response is cachable if a cache is allowed to store a copy of
+ the response message for use in answering subsequent requests. The
+ rules for determining the cachability of HTTP responses are
+ defined in section 13. Even if a resource is cachable, there may
+ be additional constraints on whether a cache can use the cached
+ copy for a particular request.
+
+ first-hand
+ A response is first-hand if it comes directly and without
+ unnecessary delay from the origin server, perhaps via one or more
+ proxies. A response is also first-hand if its validity has just
+ been checked directly with the origin server.
+
+ explicit expiration time
+ The time at which the origin server intends that an entity should
+ no longer be returned by a cache without further validation.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 10]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ heuristic expiration time
+ An expiration time assigned by a cache when no explicit expiration
+ time is available.
+
+ age
+ The age of a response is the time since it was sent by, or
+ successfully validated with, the origin server.
+
+ freshness lifetime
+ The length of time between the generation of a response and its
+ expiration time.
+
+ fresh
+ A response is fresh if its age has not yet exceeded its freshness
+ lifetime.
+
+ stale
+ A response is stale if its age has passed its freshness lifetime.
+
+ semantically transparent
+ A cache behaves in a "semantically transparent" manner, with
+ respect to a particular response, when its use affects neither the
+ requesting client nor the origin server, except to improve
+ performance. When a cache is semantically transparent, the client
+ receives exactly the same response (except for hop-by-hop headers)
+ that it would have received had its request been handled directly
+ by the origin server.
+
+ validator
+ A protocol element (e.g., an entity tag or a Last-Modified time)
+ that is used to find out whether a cache entry is an equivalent
+ copy of an entity.
+
+1.4 Overall Operation
+
+ The HTTP protocol is a request/response protocol. A client sends a
+ request to the server in the form of a request method, URI, and
+ protocol version, followed by a MIME-like message containing request
+ modifiers, client information, and possible body content over a
+ connection with a server. The server responds with a status line,
+ including the message's protocol version and a success or error code,
+ followed by a MIME-like message containing server information, entity
+ metainformation, and possible entity-body content. The relationship
+ between HTTP and MIME is described in appendix 19.4.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 11]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Most HTTP communication is initiated by a user agent and consists of
+ a request to be applied to a resource on some origin server. In the
+ simplest case, this may be accomplished via a single connection (v)
+ between the user agent (UA) and the origin server (O).
+
+ request chain ------------------------>
+ UA -------------------v------------------- O
+ <----------------------- response chain
+
+ A more complicated situation occurs when one or more intermediaries
+ are present in the request/response chain. There are three common
+ forms of intermediary: proxy, gateway, and tunnel. A proxy is a
+ forwarding agent, receiving requests for a URI in its absolute form,
+ rewriting all or part of the message, and forwarding the reformatted
+ request toward the server identified by the URI. A gateway is a
+ receiving agent, acting as a layer above some other server(s) and, if
+ necessary, translating the requests to the underlying server's
+ protocol. A tunnel acts as a relay point between two connections
+ without changing the messages; tunnels are used when the
+ communication needs to pass through an intermediary (such as a
+ firewall) even when the intermediary cannot understand the contents
+ of the messages.
+
+ request chain -------------------------------------->
+ UA -----v----- A -----v----- B -----v----- C -----v----- O
+ <------------------------------------- response chain
+
+ The figure above shows three intermediaries (A, B, and C) between the
+ user agent and origin server. A request or response message that
+ travels the whole chain will pass through four separate connections.
+ This distinction is important because some HTTP communication options
+ may apply only to the connection with the nearest, non-tunnel
+ neighbor, only to the end-points of the chain, or to all connections
+ along the chain. Although the diagram is linear, each participant
+ may be engaged in multiple, simultaneous communications. For example,
+ B may be receiving requests from many clients other than A, and/or
+ forwarding requests to servers other than C, at the same time that it
+ is handling A's request.
+
+ Any party to the communication which is not acting as a tunnel may
+ employ an internal cache for handling requests. The effect of a cache
+ is that the request/response chain is shortened if one of the
+ participants along the chain has a cached response applicable to that
+ request. The following illustrates the resulting chain if B has a
+ cached copy of an earlier response from O (via C) for a request which
+ has not been cached by UA or A.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 12]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ request chain ---------->
+ UA -----v----- A -----v----- B - - - - - - C - - - - - - O
+ <--------- response chain
+
+ Not all responses are usefully cachable, and some requests may
+ contain modifiers which place special requirements on cache behavior.
+ HTTP requirements for cache behavior and cachable responses are
+ defined in section 13.
+
+ In fact, there are a wide variety of architectures and configurations
+ of caches and proxies currently being experimented with or deployed
+ across the World Wide Web; these systems include national hierarchies
+ of proxy caches to save transoceanic bandwidth, systems that
+ broadcast or multicast cache entries, organizations that distribute
+ subsets of cached data via CD-ROM, and so on. HTTP systems are used
+ in corporate intranets over high-bandwidth links, and for access via
+ PDAs with low-power radio links and intermittent connectivity. The
+ goal of HTTP/1.1 is to support the wide diversity of configurations
+ already deployed while introducing protocol constructs that meet the
+ needs of those who build web applications that require high
+ reliability and, failing that, at least reliable indications of
+ failure.
+
+ HTTP communication usually takes place over TCP/IP connections. The
+ default port is TCP 80, but other ports can be used. This does not
+ preclude HTTP from being implemented on top of any other protocol on
+ the Internet, or on other networks. HTTP only presumes a reliable
+ transport; any protocol that provides such guarantees can be used;
+ the mapping of the HTTP/1.1 request and response structures onto the
+ transport data units of the protocol in question is outside the scope
+ of this specification.
+
+ In HTTP/1.0, most implementations used a new connection for each
+ request/response exchange. In HTTP/1.1, a connection may be used for
+ one or more request/response exchanges, although connections may be
+ closed for a variety of reasons (see section 8.1).
+
+2 Notational Conventions and Generic Grammar
+
+2.1 Augmented BNF
+
+ All of the mechanisms specified in this document are described in
+ both prose and an augmented Backus-Naur Form (BNF) similar to that
+ used by RFC 822 [9]. Implementers will need to be familiar with the
+ notation in order to understand this specification. The augmented BNF
+ includes the following constructs:
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 13]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+name = definition
+ The name of a rule is simply the name itself (without any enclosing
+ "<" and ">") and is separated from its definition by the equal "="
+ character. Whitespace is only significant in that indentation of
+ continuation lines is used to indicate a rule definition that spans
+ more than one line. Certain basic rules are in uppercase, such as
+ SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used
+ within definitions whenever their presence will facilitate
+ discerning the use of rule names.
+
+"literal"
+ Quotation marks surround literal text. Unless stated otherwise, the
+ text is case-insensitive.
+
+rule1 | rule2
+ Elements separated by a bar ("|") are alternatives, e.g., "yes |
+ no" will accept yes or no.
+
+(rule1 rule2)
+ Elements enclosed in parentheses are treated as a single element.
+ Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
+ foo elem" and "elem bar elem".
+
+*rule
+ The character "*" preceding an element indicates repetition. The
+ full form is "<n>*<m>element" indicating at least <n> and at most
+ <m> occurrences of element. Default values are 0 and infinity so
+ that "*(element)" allows any number, including zero; "1*element"
+ requires at least one; and "1*2element" allows one or two.
+
+[rule]
+ Square brackets enclose optional elements; "[foo bar]" is
+ equivalent to "*1(foo bar)".
+
+N rule
+ Specific repetition: "<n>(element)" is equivalent to
+ "<n>*<n>(element)"; that is, exactly <n> occurrences of (element).
+ Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three
+ alphabetic characters.
+
+#rule
+ A construct "#" is defined, similar to "*", for defining lists of
+ elements. The full form is "<n>#<m>element " indicating at least
+ <n> and at most <m> elements, each separated by one or more commas
+ (",") and optional linear whitespace (LWS). This makes the usual
+ form of lists very easy; a rule such as "( *LWS element *( *LWS ","
+ *LWS element )) " can be shown as "1#element". Wherever this
+ construct is used, null elements are allowed, but do not contribute
+
+
+
+Fielding, et. al. Standards Track [Page 14]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ to the count of elements present. That is, "(element), , (element)
+ " is permitted, but counts as only two elements. Therefore, where
+ at least one element is required, at least one non-null element
+ must be present. Default values are 0 and infinity so that
+ "#element" allows any number, including zero; "1#element" requires
+ at least one; and "1#2element" allows one or two.
+
+; comment
+ A semi-colon, set off some distance to the right of rule text,
+ starts a comment that continues to the end of line. This is a
+ simple way of including useful notes in parallel with the
+ specifications.
+
+implied *LWS
+ The grammar described by this specification is word-based. Except
+ where noted otherwise, linear whitespace (LWS) can be included
+ between any two adjacent words (token or quoted-string), and
+ between adjacent tokens and delimiters (tspecials), without
+ changing the interpretation of a field. At least one delimiter
+ (tspecials) must exist between any two tokens, since they would
+ otherwise be interpreted as a single token.
+
+2.2 Basic Rules
+
+ The following rules are used throughout this specification to
+ describe basic parsing constructs. The US-ASCII coded character set
+ is defined by ANSI X3.4-1986 [21].
+
+ OCTET = <any 8-bit sequence of data>
+ CHAR = <any US-ASCII character (octets 0 - 127)>
+ UPALPHA = <any US-ASCII uppercase letter "A".."Z">
+ LOALPHA = <any US-ASCII lowercase letter "a".."z">
+ ALPHA = UPALPHA | LOALPHA
+ DIGIT = <any US-ASCII digit "0".."9">
+ CTL = <any US-ASCII control character
+ (octets 0 - 31) and DEL (127)>
+ CR = <US-ASCII CR, carriage return (13)>
+ LF = <US-ASCII LF, linefeed (10)>
+ SP = <US-ASCII SP, space (32)>
+ HT = <US-ASCII HT, horizontal-tab (9)>
+ <"> = <US-ASCII double-quote mark (34)>
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 15]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
+ protocol elements except the entity-body (see appendix 19.3 for
+ tolerant applications). The end-of-line marker within an entity-body
+ is defined by its associated media type, as described in section 3.7.
+
+ CRLF = CR LF
+
+ HTTP/1.1 headers can be folded onto multiple lines if the
+ continuation line begins with a space or horizontal tab. All linear
+ white space, including folding, has the same semantics as SP.
+
+ LWS = [CRLF] 1*( SP | HT )
+
+ The TEXT rule is only used for descriptive field contents and values
+ that are not intended to be interpreted by the message parser. Words
+ of *TEXT may contain characters from character sets other than ISO
+ 8859-1 [22] only when encoded according to the rules of RFC 1522
+ [14].
+
+ TEXT = <any OCTET except CTLs,
+ but including LWS>
+
+ Hexadecimal numeric characters are used in several protocol elements.
+
+ HEX = "A" | "B" | "C" | "D" | "E" | "F"
+ | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
+
+ Many HTTP/1.1 header field values consist of words separated by LWS
+ or special characters. These special characters MUST be in a quoted
+ string to be used within a parameter value.
+
+ token = 1*<any CHAR except CTLs or tspecials>
+
+ tspecials = "(" | ")" | "<" | ">" | "@"
+ | "," | ";" | ":" | "\" | <">
+ | "/" | "[" | "]" | "?" | "="
+ | "{" | "}" | SP | HT
+
+ Comments can be included in some HTTP header fields by surrounding
+ the comment text with parentheses. Comments are only allowed in
+ fields containing "comment" as part of their field value definition.
+ In all other fields, parentheses are considered part of the field
+ value.
+
+ comment = "(" *( ctext | comment ) ")"
+ ctext = <any TEXT excluding "(" and ")">
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 16]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ A string of text is parsed as a single word if it is quoted using
+ double-quote marks.
+
+ quoted-string = ( <"> *(qdtext) <"> )
+
+ qdtext = <any TEXT except <">>
+
+ The backslash character ("\") may be used as a single-character quoting
+ mechanism only within quoted-string and comment constructs.
+
+ quoted-pair = "\" CHAR
+
+3 Protocol Parameters
+
+3.1 HTTP Version
+
+ HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
+ of the protocol. The protocol versioning policy is intended to allow
+ the sender to indicate the format of a message and its capacity for
+ understanding further HTTP communication, rather than the features
+ obtained via that communication. No change is made to the version
+ number for the addition of message components which do not affect
+ communication behavior or which only add to extensible field values.
+ The <minor> number is incremented when the changes made to the
+ protocol add features which do not change the general message parsing
+ algorithm, but which may add to the message semantics and imply
+ additional capabilities of the sender. The <major> number is
+ incremented when the format of a message within the protocol is
+ changed.
+
+ The version of an HTTP message is indicated by an HTTP-Version field
+ in the first line of the message.
+
+ HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
+
+ Note that the major and minor numbers MUST be treated as separate
+ integers and that each may be incremented higher than a single digit.
+ Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is
+ lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and
+ MUST NOT be sent.
+
+ Applications sending Request or Response messages, as defined by this
+ specification, MUST include an HTTP-Version of "HTTP/1.1". Use of
+ this version number indicates that the sending application is at
+ least conditionally compliant with this specification.
+
+ The HTTP version of an application is the highest HTTP version for
+ which the application is at least conditionally compliant.
+
+
+
+Fielding, et. al. Standards Track [Page 17]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Proxy and gateway applications must be careful when forwarding
+ messages in protocol versions different from that of the application.
+ Since the protocol version indicates the protocol capability of the
+ sender, a proxy/gateway MUST never send a message with a version
+ indicator which is greater than its actual version; if a higher
+ version request is received, the proxy/gateway MUST either downgrade
+ the request version, respond with an error, or switch to tunnel
+ behavior. Requests with a version lower than that of the
+ proxy/gateway's version MAY be upgraded before being forwarded; the
+ proxy/gateway's response to that request MUST be in the same major
+ version as the request.
+
+ Note: Converting between versions of HTTP may involve modification
+ of header fields required or forbidden by the versions involved.
+
+3.2 Uniform Resource Identifiers
+
+ URIs have been known by many names: WWW addresses, Universal Document
+ Identifiers, Universal Resource Identifiers , and finally the
+ combination of Uniform Resource Locators (URL) and Names (URN). As
+ far as HTTP is concerned, Uniform Resource Identifiers are simply
+ formatted strings which identify--via name, location, or any other
+ characteristic--a resource.
+
+3.2.1 General Syntax
+
+ URIs in HTTP can be represented in absolute form or relative to some
+ known base URI, depending upon the context of their use. The two
+ forms are differentiated by the fact that absolute URIs always begin
+ with a scheme name followed by a colon.
+
+ URI = ( absoluteURI | relativeURI ) [ "#" fragment ]
+
+ absoluteURI = scheme ":" *( uchar | reserved )
+
+ relativeURI = net_path | abs_path | rel_path
+
+ net_path = "//" net_loc [ abs_path ]
+ abs_path = "/" rel_path
+ rel_path = [ path ] [ ";" params ] [ "?" query ]
+
+ path = fsegment *( "/" segment )
+ fsegment = 1*pchar
+ segment = *pchar
+
+ params = param *( ";" param )
+ param = *( pchar | "/" )
+
+
+
+
+Fielding, et. al. Standards Track [Page 18]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." )
+ net_loc = *( pchar | ";" | "?" )
+
+ query = *( uchar | reserved )
+ fragment = *( uchar | reserved )
+
+ pchar = uchar | ":" | "@" | "&" | "=" | "+"
+ uchar = unreserved | escape
+ unreserved = ALPHA | DIGIT | safe | extra | national
+
+ escape = "%" HEX HEX
+ reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+"
+ extra = "!" | "*" | "'" | "(" | ")" | ","
+ safe = "$" | "-" | "_" | "."
+ unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">"
+ national = <any OCTET excluding ALPHA, DIGIT,
+ reserved, extra, safe, and unsafe>
+
+ For definitive information on URL syntax and semantics, see RFC 1738
+ [4] and RFC 1808 [11]. The BNF above includes national characters not
+ allowed in valid URLs as specified by RFC 1738, since HTTP servers
+ are not restricted in the set of unreserved characters allowed to
+ represent the rel_path part of addresses, and HTTP proxies may
+ receive requests for URIs not defined by RFC 1738.
+
+ The HTTP protocol does not place any a priori limit on the length of
+ a URI. Servers MUST be able to handle the URI of any resource they
+ serve, and SHOULD be able to handle URIs of unbounded length if they
+ provide GET-based forms that could generate such URIs. A server
+ SHOULD return 414 (Request-URI Too Long) status if a URI is longer
+ than the server can handle (see section 10.4.15).
+
+ Note: Servers should be cautious about depending on URI lengths
+ above 255 bytes, because some older client or proxy implementations
+ may not properly support these lengths.
+
+3.2.2 http URL
+
+ The "http" scheme is used to locate network resources via the HTTP
+ protocol. This section defines the scheme-specific syntax and
+ semantics for http URLs.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 19]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ http_URL = "http:" "//" host [ ":" port ] [ abs_path ]
+
+ host = <A legal Internet host domain name
+ or IP address (in dotted-decimal form),
+ as defined by Section 2.1 of RFC 1123>
+
+ port = *DIGIT
+
+ If the port is empty or not given, port 80 is assumed. The semantics
+ are that the identified resource is located at the server listening
+ for TCP connections on that port of that host, and the Request-URI
+ for the resource is abs_path. The use of IP addresses in URL's SHOULD
+ be avoided whenever possible (see RFC 1900 [24]). If the abs_path is
+ not present in the URL, it MUST be given as "/" when used as a
+ Request-URI for a resource (section 5.1.2).
+
+3.2.3 URI Comparison
+
+ When comparing two URIs to decide if they match or not, a client
+ SHOULD use a case-sensitive octet-by-octet comparison of the entire
+ URIs, with these exceptions:
+
+ o A port that is empty or not given is equivalent to the default
+ port for that URI;
+
+ o Comparisons of host names MUST be case-insensitive;
+
+ o Comparisons of scheme names MUST be case-insensitive;
+
+ o An empty abs_path is equivalent to an abs_path of "/".
+
+ Characters other than those in the "reserved" and "unsafe" sets (see
+ section 3.2) are equivalent to their ""%" HEX HEX" encodings.
+
+ For example, the following three URIs are equivalent:
+
+ http://abc.com:80/~smith/home.html
+ http://ABC.com/%7Esmith/home.html
+ http://ABC.com:/%7esmith/home.html
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 20]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+3.3 Date/Time Formats
+
+3.3.1 Full Date
+
+ HTTP applications have historically allowed three different formats
+ for the representation of date/time stamps:
+
+ Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
+ Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
+ Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
+
+ The first format is preferred as an Internet standard and represents
+ a fixed-length subset of that defined by RFC 1123 (an update to RFC
+ 822). The second format is in common use, but is based on the
+ obsolete RFC 850 [12] date format and lacks a four-digit year.
+ HTTP/1.1 clients and servers that parse the date value MUST accept
+ all three formats (for compatibility with HTTP/1.0), though they MUST
+ only generate the RFC 1123 format for representing HTTP-date values
+ in header fields.
+
+ Note: Recipients of date values are encouraged to be robust in
+ accepting date values that may have been sent by non-HTTP
+ applications, as is sometimes the case when retrieving or posting
+ messages via proxies/gateways to SMTP or NNTP.
+
+ All HTTP date/time stamps MUST be represented in Greenwich Mean Time
+ (GMT), without exception. This is indicated in the first two formats
+ by the inclusion of "GMT" as the three-letter abbreviation for time
+ zone, and MUST be assumed when reading the asctime format.
+
+ HTTP-date = rfc1123-date | rfc850-date | asctime-date
+
+ rfc1123-date = wkday "," SP date1 SP time SP "GMT"
+ rfc850-date = weekday "," SP date2 SP time SP "GMT"
+ asctime-date = wkday SP date3 SP time SP 4DIGIT
+
+ date1 = 2DIGIT SP month SP 4DIGIT
+ ; day month year (e.g., 02 Jun 1982)
+ date2 = 2DIGIT "-" month "-" 2DIGIT
+ ; day-month-year (e.g., 02-Jun-82)
+ date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
+ ; month day (e.g., Jun 2)
+
+ time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+ ; 00:00:00 - 23:59:59
+
+ wkday = "Mon" | "Tue" | "Wed"
+ | "Thu" | "Fri" | "Sat" | "Sun"
+
+
+
+Fielding, et. al. Standards Track [Page 21]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ weekday = "Monday" | "Tuesday" | "Wednesday"
+ | "Thursday" | "Friday" | "Saturday" | "Sunday"
+
+ month = "Jan" | "Feb" | "Mar" | "Apr"
+ | "May" | "Jun" | "Jul" | "Aug"
+ | "Sep" | "Oct" | "Nov" | "Dec"
+
+ Note: HTTP requirements for the date/time stamp format apply only
+ to their usage within the protocol stream. Clients and servers are
+ not required to use these formats for user presentation, request
+ logging, etc.
+
+3.3.2 Delta Seconds
+
+ Some HTTP header fields allow a time value to be specified as an
+ integer number of seconds, represented in decimal, after the time
+ that the message was received.
+
+ delta-seconds = 1*DIGIT
+
+3.4 Character Sets
+
+ HTTP uses the same definition of the term "character set" as that
+ described for MIME:
+
+ The term "character set" is used in this document to refer to a
+ method used with one or more tables to convert a sequence of octets
+ into a sequence of characters. Note that unconditional conversion
+ in the other direction is not required, in that not all characters
+ may be available in a given character set and a character set may
+ provide more than one sequence of octets to represent a particular
+ character. This definition is intended to allow various kinds of
+ character encodings, from simple single-table mappings such as US-
+ ASCII to complex table switching methods such as those that use ISO
+ 2022's techniques. However, the definition associated with a MIME
+ character set name MUST fully specify the mapping to be performed
+ from octets to characters. In particular, use of external profiling
+ information to determine the exact mapping is not permitted.
+
+ Note: This use of the term "character set" is more commonly
+ referred to as a "character encoding." However, since HTTP and MIME
+ share the same registry, it is important that the terminology also
+ be shared.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 22]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ HTTP character sets are identified by case-insensitive tokens. The
+ complete set of tokens is defined by the IANA Character Set registry
+ [19].
+
+ charset = token
+
+ Although HTTP allows an arbitrary token to be used as a charset
+ value, any token that has a predefined value within the IANA
+ Character Set registry MUST represent the character set defined by
+ that registry. Applications SHOULD limit their use of character sets
+ to those defined by the IANA registry.
+
+3.5 Content Codings
+
+ Content coding values indicate an encoding transformation that has
+ been or can be applied to an entity. Content codings are primarily
+ used to allow a document to be compressed or otherwise usefully
+ transformed without losing the identity of its underlying media type
+ and without loss of information. Frequently, the entity is stored in
+ coded form, transmitted directly, and only decoded by the recipient.
+
+ content-coding = token
+
+ All content-coding values are case-insensitive. HTTP/1.1 uses
+ content-coding values in the Accept-Encoding (section 14.3) and
+ Content-Encoding (section 14.12) header fields. Although the value
+ describes the content-coding, what is more important is that it
+ indicates what decoding mechanism will be required to remove the
+ encoding.
+
+ The Internet Assigned Numbers Authority (IANA) acts as a registry for
+ content-coding value tokens. Initially, the registry contains the
+ following tokens:
+
+ gzip An encoding format produced by the file compression program "gzip"
+ (GNU zip) as described in RFC 1952 [25]. This format is a Lempel-
+ Ziv coding (LZ77) with a 32 bit CRC.
+
+ compress
+ The encoding format produced by the common UNIX file compression
+ program "compress". This format is an adaptive Lempel-Ziv-Welch
+ coding (LZW).
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 23]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Note: Use of program names for the identification of encoding
+ formats is not desirable and should be discouraged for future
+ encodings. Their use here is representative of historical practice,
+ not good design. For compatibility with previous implementations of
+ HTTP, applications should consider "x-gzip" and "x-compress" to be
+ equivalent to "gzip" and "compress" respectively.
+
+ deflate The "zlib" format defined in RFC 1950[31] in combination with
+ the "deflate" compression mechanism described in RFC 1951[29].
+
+ New content-coding value tokens should be registered; to allow
+ interoperability between clients and servers, specifications of the
+ content coding algorithms needed to implement a new value should be
+ publicly available and adequate for independent implementation, and
+ conform to the purpose of content coding defined in this section.
+
+3.6 Transfer Codings
+
+ Transfer coding values are used to indicate an encoding
+ transformation that has been, can be, or may need to be applied to an
+ entity-body in order to ensure "safe transport" through the network.
+ This differs from a content coding in that the transfer coding is a
+ property of the message, not of the original entity.
+
+ transfer-coding = "chunked" | transfer-extension
+
+ transfer-extension = token
+
+ All transfer-coding values are case-insensitive. HTTP/1.1 uses
+ transfer coding values in the Transfer-Encoding header field (section
+ 14.40).
+
+ Transfer codings are analogous to the Content-Transfer-Encoding
+ values of MIME , which were designed to enable safe transport of
+ binary data over a 7-bit transport service. However, safe transport
+ has a different focus for an 8bit-clean transfer protocol. In HTTP,
+ the only unsafe characteristic of message-bodies is the difficulty in
+ determining the exact body length (section 7.2.2), or the desire to
+ encrypt data over a shared transport.
+
+ The chunked encoding modifies the body of a message in order to
+ transfer it as a series of chunks, each with its own size indicator,
+ followed by an optional footer containing entity-header fields. This
+ allows dynamically-produced content to be transferred along with the
+ information necessary for the recipient to verify that it has
+ received the full message.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 24]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Chunked-Body = *chunk
+ "0" CRLF
+ footer
+ CRLF
+
+ chunk = chunk-size [ chunk-ext ] CRLF
+ chunk-data CRLF
+
+ hex-no-zero = <HEX excluding "0">
+
+ chunk-size = hex-no-zero *HEX
+ chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-value ] )
+ chunk-ext-name = token
+ chunk-ext-val = token | quoted-string
+ chunk-data = chunk-size(OCTET)
+
+ footer = *entity-header
+
+ The chunked encoding is ended by a zero-sized chunk followed by the
+ footer, which is terminated by an empty line. The purpose of the
+ footer is to provide an efficient way to supply information about an
+ entity that is generated dynamically; applications MUST NOT send
+ header fields in the footer which are not explicitly defined as being
+ appropriate for the footer, such as Content-MD5 or future extensions
+ to HTTP for digital signatures or other facilities.
+
+ An example process for decoding a Chunked-Body is presented in
+ appendix 19.4.6.
+
+ All HTTP/1.1 applications MUST be able to receive and decode the
+ "chunked" transfer coding, and MUST ignore transfer coding extensions
+ they do not understand. A server which receives an entity-body with a
+ transfer-coding it does not understand SHOULD return 501
+ (Unimplemented), and close the connection. A server MUST NOT send
+ transfer-codings to an HTTP/1.0 client.
+
+3.7 Media Types
+
+ HTTP uses Internet Media Types in the Content-Type (section 14.18)
+ and Accept (section 14.1) header fields in order to provide open and
+ extensible data typing and type negotiation.
+
+ media-type = type "/" subtype *( ";" parameter )
+ type = token
+ subtype = token
+
+ Parameters may follow the type/subtype in the form of attribute/value
+ pairs.
+
+
+
+Fielding, et. al. Standards Track [Page 25]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ parameter = attribute "=" value
+ attribute = token
+ value = token | quoted-string
+
+ The type, subtype, and parameter attribute names are case-
+ insensitive. Parameter values may or may not be case-sensitive,
+ depending on the semantics of the parameter name. Linear white space
+ (LWS) MUST NOT be used between the type and subtype, nor between an
+ attribute and its value. User agents that recognize the media-type
+ MUST process (or arrange to be processed by any external applications
+ used to process that type/subtype by the user agent) the parameters
+ for that MIME type as described by that type/subtype definition to
+ the and inform the user of any problems discovered.
+
+ Note: some older HTTP applications do not recognize media type
+ parameters. When sending data to older HTTP applications,
+ implementations should only use media type parameters when they are
+ required by that type/subtype definition.
+
+ Media-type values are registered with the Internet Assigned Number
+ Authority (IANA). The media type registration process is outlined in
+ RFC 2048 [17]. Use of non-registered media types is discouraged.
+
+3.7.1 Canonicalization and Text Defaults
+
+ Internet media types are registered with a canonical form. In
+ general, an entity-body transferred via HTTP messages MUST be
+ represented in the appropriate canonical form prior to its
+ transmission; the exception is "text" types, as defined in the next
+ paragraph.
+
+ When in canonical form, media subtypes of the "text" type use CRLF as
+ the text line break. HTTP relaxes this requirement and allows the
+ transport of text media with plain CR or LF alone representing a line
+ break when it is done consistently for an entire entity-body. HTTP
+ applications MUST accept CRLF, bare CR, and bare LF as being
+ representative of a line break in text media received via HTTP. In
+ addition, if the text is represented in a character set that does not
+ use octets 13 and 10 for CR and LF respectively, as is the case for
+ some multi-byte character sets, HTTP allows the use of whatever octet
+ sequences are defined by that character set to represent the
+ equivalent of CR and LF for line breaks. This flexibility regarding
+ line breaks applies only to text media in the entity-body; a bare CR
+ or LF MUST NOT be substituted for CRLF within any of the HTTP control
+ structures (such as header fields and multipart boundaries).
+
+ If an entity-body is encoded with a Content-Encoding, the underlying
+ data MUST be in a form defined above prior to being encoded.
+
+
+
+Fielding, et. al. Standards Track [Page 26]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The "charset" parameter is used with some media types to define the
+ character set (section 3.4) of the data. When no explicit charset
+ parameter is provided by the sender, media subtypes of the "text"
+ type are defined to have a default charset value of "ISO-8859-1" when
+ received via HTTP. Data in character sets other than "ISO-8859-1" or
+ its subsets MUST be labeled with an appropriate charset value.
+
+ Some HTTP/1.0 software has interpreted a Content-Type header without
+ charset parameter incorrectly to mean "recipient should guess."
+ Senders wishing to defeat this behavior MAY include a charset
+ parameter even when the charset is ISO-8859-1 and SHOULD do so when
+ it is known that it will not confuse the recipient.
+
+ Unfortunately, some older HTTP/1.0 clients did not deal properly with
+ an explicit charset parameter. HTTP/1.1 recipients MUST respect the
+ charset label provided by the sender; and those user agents that have
+ a provision to "guess" a charset MUST use the charset from the
+ content-type field if they support that charset, rather than the
+ recipient's preference, when initially displaying a document.
+
+3.7.2 Multipart Types
+
+ MIME provides for a number of "multipart" types -- encapsulations of
+ one or more entities within a single message-body. All multipart
+ types share a common syntax, as defined in MIME [7], and MUST
+ include a boundary parameter as part of the media type value. The
+ message body is itself a protocol element and MUST therefore use only
+ CRLF to represent line breaks between body-parts. Unlike in MIME, the
+ epilogue of any multipart message MUST be empty; HTTP applications
+ MUST NOT transmit the epilogue (even if the original multipart
+ contains an epilogue).
+
+ In HTTP, multipart body-parts MAY contain header fields which are
+ significant to the meaning of that part. A Content-Location header
+ field (section 14.15) SHOULD be included in the body-part of each
+ enclosed entity that can be identified by a URL.
+
+ In general, an HTTP user agent SHOULD follow the same or similar
+ behavior as a MIME user agent would upon receipt of a multipart type.
+ If an application receives an unrecognized multipart subtype, the
+ application MUST treat it as being equivalent to "multipart/mixed".
+
+ Note: The "multipart/form-data" type has been specifically defined
+ for carrying form data suitable for processing via the POST request
+ method, as described in RFC 1867 [15].
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 27]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+3.8 Product Tokens
+
+ Product tokens are used to allow communicating applications to
+ identify themselves by software name and version. Most fields using
+ product tokens also allow sub-products which form a significant part
+ of the application to be listed, separated by whitespace. By
+ convention, the products are listed in order of their significance
+ for identifying the application.
+
+ product = token ["/" product-version]
+ product-version = token
+
+ Examples:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+ Server: Apache/0.8.4
+
+ Product tokens should be short and to the point -- use of them for
+ advertising or other non-essential information is explicitly
+ forbidden. Although any token character may appear in a product-
+ version, this token SHOULD only be used for a version identifier
+ (i.e., successive versions of the same product SHOULD only differ in
+ the product-version portion of the product value).
+
+3.9 Quality Values
+
+ HTTP content negotiation (section 12) uses short "floating point"
+ numbers to indicate the relative importance ("weight") of various
+ negotiable parameters. A weight is normalized to a real number in the
+ range 0 through 1, where 0 is the minimum and 1 the maximum value.
+ HTTP/1.1 applications MUST NOT generate more than three digits after
+ the decimal point. User configuration of these values SHOULD also be
+ limited in this fashion.
+
+ qvalue = ( "0" [ "." 0*3DIGIT ] )
+ | ( "1" [ "." 0*3("0") ] )
+
+ "Quality values" is a misnomer, since these values merely represent
+ relative degradation in desired quality.
+
+3.10 Language Tags
+
+ A language tag identifies a natural language spoken, written, or
+ otherwise conveyed by human beings for communication of information
+ to other human beings. Computer languages are explicitly excluded.
+ HTTP uses language tags within the Accept-Language and Content-
+ Language fields.
+
+
+
+
+Fielding, et. al. Standards Track [Page 28]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The syntax and registry of HTTP language tags is the same as that
+ defined by RFC 1766 [1]. In summary, a language tag is composed of 1
+ or more parts: A primary language tag and a possibly empty series of
+ subtags:
+
+ language-tag = primary-tag *( "-" subtag )
+
+ primary-tag = 1*8ALPHA
+ subtag = 1*8ALPHA
+
+ Whitespace is not allowed within the tag and all tags are case-
+ insensitive. The name space of language tags is administered by the
+ IANA. Example tags include:
+
+ en, en-US, en-cockney, i-cherokee, x-pig-latin
+
+ where any two-letter primary-tag is an ISO 639 language abbreviation
+ and any two-letter initial subtag is an ISO 3166 country code. (The
+ last three tags above are not registered tags; all but the last are
+ examples of tags which could be registered in future.)
+
+3.11 Entity Tags
+
+ Entity tags are used for comparing two or more entities from the same
+ requested resource. HTTP/1.1 uses entity tags in the ETag (section
+ 14.20), If-Match (section 14.25), If-None-Match (section 14.26), and
+ If-Range (section 14.27) header fields. The definition of how they
+ are used and compared as cache validators is in section 13.3.3. An
+ entity tag consists of an opaque quoted string, possibly prefixed by
+ a weakness indicator.
+
+ entity-tag = [ weak ] opaque-tag
+
+ weak = "W/"
+ opaque-tag = quoted-string
+
+ A "strong entity tag" may be shared by two entities of a resource
+ only if they are equivalent by octet equality.
+
+ A "weak entity tag," indicated by the "W/" prefix, may be shared by
+ two entities of a resource only if the entities are equivalent and
+ could be substituted for each other with no significant change in
+ semantics. A weak entity tag can only be used for weak comparison.
+
+ An entity tag MUST be unique across all versions of all entities
+ associated with a particular resource. A given entity tag value may
+ be used for entities obtained by requests on different URIs without
+ implying anything about the equivalence of those entities.
+
+
+
+Fielding, et. al. Standards Track [Page 29]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+3.12 Range Units
+
+ HTTP/1.1 allows a client to request that only part (a range of) the
+ response entity be included within the response. HTTP/1.1 uses range
+ units in the Range (section 14.36) and Content-Range (section 14.17)
+ header fields. An entity may be broken down into subranges according
+ to various structural units.
+
+ range-unit = bytes-unit | other-range-unit
+
+ bytes-unit = "bytes"
+ other-range-unit = token
+
+The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
+ implementations may ignore ranges specified using other units.
+ HTTP/1.1 has been designed to allow implementations of applications
+ that do not depend on knowledge of ranges.
+
+4 HTTP Message
+
+4.1 Message Types
+
+ HTTP messages consist of requests from client to server and responses
+ from server to client.
+
+ HTTP-message = Request | Response ; HTTP/1.1 messages
+
+ Request (section 5) and Response (section 6) messages use the generic
+ message format of RFC 822 [9] for transferring entities (the payload
+ of the message). Both types of message consist of a start-line, one
+ or more header fields (also known as "headers"), an empty line (i.e.,
+ a line with nothing preceding the CRLF) indicating the end of the
+ header fields, and an optional message-body.
+
+ generic-message = start-line
+ *message-header
+ CRLF
+ [ message-body ]
+
+ start-line = Request-Line | Status-Line
+
+ In the interest of robustness, servers SHOULD ignore any empty
+ line(s) received where a Request-Line is expected. In other words, if
+ the server is reading the protocol stream at the beginning of a
+ message and receives a CRLF first, it should ignore the CRLF.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 30]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Note: certain buggy HTTP/1.0 client implementations generate an
+ extra CRLF's after a POST request. To restate what is explicitly
+ forbidden by the BNF, an HTTP/1.1 client must not preface or follow
+ a request with an extra CRLF.
+
+4.2 Message Headers
+
+ HTTP header fields, which include general-header (section 4.5),
+ request-header (section 5.3), response-header (section 6.2), and
+ entity-header (section 7.1) fields, follow the same generic format as
+ that given in Section 3.1 of RFC 822 [9]. Each header field consists
+ of a name followed by a colon (":") and the field value. Field names
+ are case-insensitive. The field value may be preceded by any amount
+ of LWS, though a single SP is preferred. Header fields can be
+ extended over multiple lines by preceding each extra line with at
+ least one SP or HT. Applications SHOULD follow "common form" when
+ generating HTTP constructs, since there might exist some
+ implementations that fail to accept anything beyond the common forms.
+
+ message-header = field-name ":" [ field-value ] CRLF
+
+ field-name = token
+ field-value = *( field-content | LWS )
+
+ field-content = <the OCTETs making up the field-value
+ and consisting of either *TEXT or combinations
+ of token, tspecials, and quoted-string>
+
+ The order in which header fields with differing field names are
+ received is not significant. However, it is "good practice" to send
+ general-header fields first, followed by request-header or response-
+ header fields, and ending with the entity-header fields.
+
+ Multiple message-header fields with the same field-name may be
+ present in a message if and only if the entire field-value for that
+ header field is defined as a comma-separated list [i.e., #(values)].
+ It MUST be possible to combine the multiple header fields into one
+ "field-name: field-value" pair, without changing the semantics of the
+ message, by appending each subsequent field-value to the first, each
+ separated by a comma. The order in which header fields with the same
+ field-name are received is therefore significant to the
+ interpretation of the combined field value, and thus a proxy MUST NOT
+ change the order of these field values when a message is forwarded.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 31]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+4.3 Message Body
+
+ The message-body (if any) of an HTTP message is used to carry the
+ entity-body associated with the request or response. The message-body
+ differs from the entity-body only when a transfer coding has been
+ applied, as indicated by the Transfer-Encoding header field (section
+ 14.40).
+
+ message-body = entity-body
+ | <entity-body encoded as per Transfer-Encoding>
+
+ Transfer-Encoding MUST be used to indicate any transfer codings
+ applied by an application to ensure safe and proper transfer of the
+ message. Transfer-Encoding is a property of the message, not of the
+ entity, and thus can be added or removed by any application along the
+ request/response chain.
+
+ The rules for when a message-body is allowed in a message differ for
+ requests and responses.
+
+ The presence of a message-body in a request is signaled by the
+ inclusion of a Content-Length or Transfer-Encoding header field in
+ the request's message-headers. A message-body MAY be included in a
+ request only when the request method (section 5.1.1) allows an
+ entity-body.
+
+ For response messages, whether or not a message-body is included with
+ a message is dependent on both the request method and the response
+ status code (section 6.1.1). All responses to the HEAD request method
+ MUST NOT include a message-body, even though the presence of entity-
+ header fields might lead one to believe they do. All 1xx
+ (informational), 204 (no content), and 304 (not modified) responses
+ MUST NOT include a message-body. All other responses do include a
+ message-body, although it may be of zero length.
+
+4.4 Message Length
+
+ When a message-body is included with a message, the length of that
+ body is determined by one of the following (in order of precedence):
+
+ 1. Any response message which MUST NOT include a message-body
+ (such as the 1xx, 204, and 304 responses and any response to a HEAD
+ request) is always terminated by the first empty line after the
+ header fields, regardless of the entity-header fields present in the
+ message.
+
+ 2. If a Transfer-Encoding header field (section 14.40) is present and
+ indicates that the "chunked" transfer coding has been applied, then
+
+
+
+Fielding, et. al. Standards Track [Page 32]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ the length is defined by the chunked encoding (section 3.6).
+
+ 3. If a Content-Length header field (section 14.14) is present, its
+ value in bytes represents the length of the message-body.
+
+ 4. If the message uses the media type "multipart/byteranges", which is
+ self-delimiting, then that defines the length. This media type MUST
+ NOT be used unless the sender knows that the recipient can parse it;
+ the presence in a request of a Range header with multiple byte-range
+ specifiers implies that the client can parse multipart/byteranges
+ responses.
+
+ 5. By the server closing the connection. (Closing the connection
+ cannot be used to indicate the end of a request body, since that
+ would leave no possibility for the server to send back a response.)
+
+ For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
+ containing a message-body MUST include a valid Content-Length header
+ field unless the server is known to be HTTP/1.1 compliant. If a
+ request contains a message-body and a Content-Length is not given,
+ the server SHOULD respond with 400 (bad request) if it cannot
+ determine the length of the message, or with 411 (length required) if
+ it wishes to insist on receiving a valid Content-Length.
+
+ All HTTP/1.1 applications that receive entities MUST accept the
+ "chunked" transfer coding (section 3.6), thus allowing this mechanism
+ to be used for messages when the message length cannot be determined
+ in advance.
+
+ Messages MUST NOT include both a Content-Length header field and the
+ "chunked" transfer coding. If both are received, the Content-Length
+ MUST be ignored.
+
+ When a Content-Length is given in a message where a message-body is
+ allowed, its field value MUST exactly match the number of OCTETs in
+ the message-body. HTTP/1.1 user agents MUST notify the user when an
+ invalid length is received and detected.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 33]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+4.5 General Header Fields
+
+ There are a few header fields which have general applicability for
+ both request and response messages, but which do not apply to the
+ entity being transferred. These header fields apply only to the
+ message being transmitted.
+
+ general-header = Cache-Control ; Section 14.9
+ | Connection ; Section 14.10
+ | Date ; Section 14.19
+ | Pragma ; Section 14.32
+ | Transfer-Encoding ; Section 14.40
+ | Upgrade ; Section 14.41
+ | Via ; Section 14.44
+
+ General-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields may be given the semantics of general
+ header fields if all parties in the communication recognize them to
+ be general-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+5 Request
+
+ A request message from a client to a server includes, within the
+ first line of that message, the method to be applied to the resource,
+ the identifier of the resource, and the protocol version in use.
+
+ Request = Request-Line ; Section 5.1
+ *( general-header ; Section 4.5
+ | request-header ; Section 5.3
+ | entity-header ) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 7.2
+
+5.1 Request-Line
+
+ The Request-Line begins with a method token, followed by the
+ Request-URI and the protocol version, and ending with CRLF. The
+ elements are separated by SP characters. No CR or LF are allowed
+ except in the final CRLF sequence.
+
+ Request-Line = Method SP Request-URI SP HTTP-Version CRLF
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 34]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+5.1.1 Method
+
+ The Method token indicates the method to be performed on the resource
+ identified by the Request-URI. The method is case-sensitive.
+
+ Method = "OPTIONS" ; Section 9.2
+ | "GET" ; Section 9.3
+ | "HEAD" ; Section 9.4
+ | "POST" ; Section 9.5
+ | "PUT" ; Section 9.6
+ | "DELETE" ; Section 9.7
+ | "TRACE" ; Section 9.8
+ | extension-method
+
+ extension-method = token
+
+ The list of methods allowed by a resource can be specified in an
+ Allow header field (section 14.7). The return code of the response
+ always notifies the client whether a method is currently allowed on a
+ resource, since the set of allowed methods can change dynamically.
+ Servers SHOULD return the status code 405 (Method Not Allowed) if the
+ method is known by the server but not allowed for the requested
+ resource, and 501 (Not Implemented) if the method is unrecognized or
+ not implemented by the server. The list of methods known by a server
+ can be listed in a Public response-header field (section 14.35).
+
+ The methods GET and HEAD MUST be supported by all general-purpose
+ servers. All other methods are optional; however, if the above
+ methods are implemented, they MUST be implemented with the same
+ semantics as those specified in section 9.
+
+5.1.2 Request-URI
+
+ The Request-URI is a Uniform Resource Identifier (section 3.2) and
+ identifies the resource upon which to apply the request.
+
+ Request-URI = "*" | absoluteURI | abs_path
+
+ The three options for Request-URI are dependent on the nature of the
+ request. The asterisk "*" means that the request does not apply to a
+ particular resource, but to the server itself, and is only allowed
+ when the method used does not necessarily apply to a resource. One
+ example would be
+
+ OPTIONS * HTTP/1.1
+
+ The absoluteURI form is required when the request is being made to a
+ proxy. The proxy is requested to forward the request or service it
+
+
+
+Fielding, et. al. Standards Track [Page 35]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ from a valid cache, and return the response. Note that the proxy MAY
+ forward the request on to another proxy or directly to the server
+ specified by the absoluteURI. In order to avoid request loops, a
+ proxy MUST be able to recognize all of its server names, including
+ any aliases, local variations, and the numeric IP address. An example
+ Request-Line would be:
+
+ GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1
+
+ To allow for transition to absoluteURIs in all requests in future
+ versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI
+ form in requests, even though HTTP/1.1 clients will only generate
+ them in requests to proxies.
+
+ The most common form of Request-URI is that used to identify a
+ resource on an origin server or gateway. In this case the absolute
+ path of the URI MUST be transmitted (see section 3.2.1, abs_path) as
+ the Request-URI, and the network location of the URI (net_loc) MUST
+ be transmitted in a Host header field. For example, a client wishing
+ to retrieve the resource above directly from the origin server would
+ create a TCP connection to port 80 of the host "www.w3.org" and send
+ the lines:
+
+ GET /pub/WWW/TheProject.html HTTP/1.1
+ Host: www.w3.org
+
+ followed by the remainder of the Request. Note that the absolute path
+ cannot be empty; if none is present in the original URI, it MUST be
+ given as "/" (the server root).
+
+ If a proxy receives a request without any path in the Request-URI and
+ the method specified is capable of supporting the asterisk form of
+ request, then the last proxy on the request chain MUST forward the
+ request with "*" as the final Request-URI. For example, the request
+
+ OPTIONS http://www.ics.uci.edu:8001 HTTP/1.1
+
+ would be forwarded by the proxy as
+
+ OPTIONS * HTTP/1.1
+ Host: www.ics.uci.edu:8001
+
+ after connecting to port 8001 of host "www.ics.uci.edu".
+
+ The Request-URI is transmitted in the format specified in section
+ 3.2.1. The origin server MUST decode the Request-URI in order to
+ properly interpret the request. Servers SHOULD respond to invalid
+ Request-URIs with an appropriate status code.
+
+
+
+Fielding, et. al. Standards Track [Page 36]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ In requests that they forward, proxies MUST NOT rewrite the
+ "abs_path" part of a Request-URI in any way except as noted above to
+ replace a null abs_path with "*", no matter what the proxy does in
+ its internal implementation.
+
+ Note: The "no rewrite" rule prevents the proxy from changing the
+ meaning of the request when the origin server is improperly using a
+ non-reserved URL character for a reserved purpose. Implementers
+ should be aware that some pre-HTTP/1.1 proxies have been known to
+ rewrite the Request-URI.
+
+5.2 The Resource Identified by a Request
+
+ HTTP/1.1 origin servers SHOULD be aware that the exact resource
+ identified by an Internet request is determined by examining both the
+ Request-URI and the Host header field.
+
+ An origin server that does not allow resources to differ by the
+ requested host MAY ignore the Host header field value. (But see
+ section 19.5.1 for other requirements on Host support in HTTP/1.1.)
+
+ An origin server that does differentiate resources based on the host
+ requested (sometimes referred to as virtual hosts or vanity
+ hostnames) MUST use the following rules for determining the requested
+ resource on an HTTP/1.1 request:
+
+ 1. If Request-URI is an absoluteURI, the host is part of the
+ Request-URI. Any Host header field value in the request MUST be
+ ignored.
+
+ 2. If the Request-URI is not an absoluteURI, and the request
+ includes a Host header field, the host is determined by the Host
+ header field value.
+
+ 3. If the host as determined by rule 1 or 2 is not a valid host on
+ the server, the response MUST be a 400 (Bad Request) error
+ message.
+
+ Recipients of an HTTP/1.0 request that lacks a Host header field MAY
+ attempt to use heuristics (e.g., examination of the URI path for
+ something unique to a particular host) in order to determine what
+ exact resource is being requested.
+
+5.3 Request Header Fields
+
+ The request-header fields allow the client to pass additional
+ information about the request, and about the client itself, to the
+ server. These fields act as request modifiers, with semantics
+
+
+
+Fielding, et. al. Standards Track [Page 37]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ equivalent to the parameters on a programming language method
+ invocation.
+
+ request-header = Accept ; Section 14.1
+ | Accept-Charset ; Section 14.2
+ | Accept-Encoding ; Section 14.3
+ | Accept-Language ; Section 14.4
+ | Authorization ; Section 14.8
+ | From ; Section 14.22
+ | Host ; Section 14.23
+ | If-Modified-Since ; Section 14.24
+ | If-Match ; Section 14.25
+ | If-None-Match ; Section 14.26
+ | If-Range ; Section 14.27
+ | If-Unmodified-Since ; Section 14.28
+ | Max-Forwards ; Section 14.31
+ | Proxy-Authorization ; Section 14.34
+ | Range ; Section 14.36
+ | Referer ; Section 14.37
+ | User-Agent ; Section 14.42
+
+ Request-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of request-
+ header fields if all parties in the communication recognize them to
+ be request-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+6 Response
+
+ After receiving and interpreting a request message, a server responds
+ with an HTTP response message.
+
+ Response = Status-Line ; Section 6.1
+ *( general-header ; Section 4.5
+ | response-header ; Section 6.2
+ | entity-header ) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 7.2
+
+6.1 Status-Line
+
+ The first line of a Response message is the Status-Line, consisting
+ of the protocol version followed by a numeric status code and its
+ associated textual phrase, with each element separated by SP
+ characters. No CR or LF is allowed except in the final CRLF
+ sequence.
+
+
+
+
+Fielding, et. al. Standards Track [Page 38]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
+
+6.1.1 Status Code and Reason Phrase
+
+ The Status-Code element is a 3-digit integer result code of the
+ attempt to understand and satisfy the request. These codes are fully
+ defined in section 10. The Reason-Phrase is intended to give a short
+ textual description of the Status-Code. The Status-Code is intended
+ for use by automata and the Reason-Phrase is intended for the human
+ user. The client is not required to examine or display the Reason-
+ Phrase.
+
+ The first digit of the Status-Code defines the class of response. The
+ last two digits do not have any categorization role. There are 5
+ values for the first digit:
+
+ o 1xx: Informational - Request received, continuing process
+
+ o 2xx: Success - The action was successfully received, understood,
+ and accepted
+
+ o 3xx: Redirection - Further action must be taken in order to
+ complete the request
+
+ o 4xx: Client Error - The request contains bad syntax or cannot be
+ fulfilled
+
+ o 5xx: Server Error - The server failed to fulfill an apparently
+ valid request
+
+ The individual values of the numeric status codes defined for
+ HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
+ presented below. The reason phrases listed here are only recommended
+ -- they may be replaced by local equivalents without affecting the
+ protocol.
+
+ Status-Code = "100" ; Continue
+ | "101" ; Switching Protocols
+ | "200" ; OK
+ | "201" ; Created
+ | "202" ; Accepted
+ | "203" ; Non-Authoritative Information
+ | "204" ; No Content
+ | "205" ; Reset Content
+ | "206" ; Partial Content
+ | "300" ; Multiple Choices
+ | "301" ; Moved Permanently
+ | "302" ; Moved Temporarily
+
+
+
+Fielding, et. al. Standards Track [Page 39]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ | "303" ; See Other
+ | "304" ; Not Modified
+ | "305" ; Use Proxy
+ | "400" ; Bad Request
+ | "401" ; Unauthorized
+ | "402" ; Payment Required
+ | "403" ; Forbidden
+ | "404" ; Not Found
+ | "405" ; Method Not Allowed
+ | "406" ; Not Acceptable
+ | "407" ; Proxy Authentication Required
+ | "408" ; Request Time-out
+ | "409" ; Conflict
+ | "410" ; Gone
+ | "411" ; Length Required
+ | "412" ; Precondition Failed
+ | "413" ; Request Entity Too Large
+ | "414" ; Request-URI Too Large
+ | "415" ; Unsupported Media Type
+ | "500" ; Internal Server Error
+ | "501" ; Not Implemented
+ | "502" ; Bad Gateway
+ | "503" ; Service Unavailable
+ | "504" ; Gateway Time-out
+ | "505" ; HTTP Version not supported
+ | extension-code
+
+ extension-code = 3DIGIT
+
+ Reason-Phrase = *<TEXT, excluding CR, LF>
+
+ HTTP status codes are extensible. HTTP applications are not required
+ to understand the meaning of all registered status codes, though such
+ understanding is obviously desirable. However, applications MUST
+ understand the class of any status code, as indicated by the first
+ digit, and treat any unrecognized response as being equivalent to the
+ x00 status code of that class, with the exception that an
+ unrecognized response MUST NOT be cached. For example, if an
+ unrecognized status code of 431 is received by the client, it can
+ safely assume that there was something wrong with its request and
+ treat the response as if it had received a 400 status code. In such
+ cases, user agents SHOULD present to the user the entity returned
+ with the response, since that entity is likely to include human-
+ readable information which will explain the unusual status.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 40]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+6.2 Response Header Fields
+
+ The response-header fields allow the server to pass additional
+ information about the response which cannot be placed in the Status-
+ Line. These header fields give information about the server and about
+ further access to the resource identified by the Request-URI.
+
+ response-header = Age ; Section 14.6
+ | Location ; Section 14.30
+ | Proxy-Authenticate ; Section 14.33
+ | Public ; Section 14.35
+ | Retry-After ; Section 14.38
+ | Server ; Section 14.39
+ | Vary ; Section 14.43
+ | Warning ; Section 14.45
+ | WWW-Authenticate ; Section 14.46
+
+ Response-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of response-
+ header fields if all parties in the communication recognize them to
+ be response-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+7 Entity
+
+ Request and Response messages MAY transfer an entity if not otherwise
+ restricted by the request method or response status code. An entity
+ consists of entity-header fields and an entity-body, although some
+ responses will only include the entity-headers.
+
+ In this section, both sender and recipient refer to either the client
+ or the server, depending on who sends and who receives the entity.
+
+7.1 Entity Header Fields
+
+ Entity-header fields define optional metainformation about the
+ entity-body or, if no body is present, about the resource identified
+ by the request.
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 41]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ entity-header = Allow ; Section 14.7
+ | Content-Base ; Section 14.11
+ | Content-Encoding ; Section 14.12
+ | Content-Language ; Section 14.13
+ | Content-Length ; Section 14.14
+ | Content-Location ; Section 14.15
+ | Content-MD5 ; Section 14.16
+ | Content-Range ; Section 14.17
+ | Content-Type ; Section 14.18
+ | ETag ; Section 14.20
+ | Expires ; Section 14.21
+ | Last-Modified ; Section 14.29
+ | extension-header
+
+ extension-header = message-header
+
+ The extension-header mechanism allows additional entity-header fields
+ to be defined without changing the protocol, but these fields cannot
+ be assumed to be recognizable by the recipient. Unrecognized header
+ fields SHOULD be ignored by the recipient and forwarded by proxies.
+
+7.2 Entity Body
+
+ The entity-body (if any) sent with an HTTP request or response is in
+ a format and encoding defined by the entity-header fields.
+
+ entity-body = *OCTET
+
+ An entity-body is only present in a message when a message-body is
+ present, as described in section 4.3. The entity-body is obtained
+ from the message-body by decoding any Transfer-Encoding that may have
+ been applied to ensure safe and proper transfer of the message.
+
+7.2.1 Type
+
+ When an entity-body is included with a message, the data type of that
+ body is determined via the header fields Content-Type and Content-
+ Encoding. These define a two-layer, ordered encoding model:
+
+ entity-body := Content-Encoding( Content-Type( data ) )
+
+ Content-Type specifies the media type of the underlying data.
+ Content-Encoding may be used to indicate any additional content
+ codings applied to the data, usually for the purpose of data
+ compression, that are a property of the requested resource. There is
+ no default encoding.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 42]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Any HTTP/1.1 message containing an entity-body SHOULD include a
+ Content-Type header field defining the media type of that body. If
+ and only if the media type is not given by a Content-Type field, the
+ recipient MAY attempt to guess the media type via inspection of its
+ content and/or the name extension(s) of the URL used to identify the
+ resource. If the media type remains unknown, the recipient SHOULD
+ treat it as type "application/octet-stream".
+
+7.2.2 Length
+
+ The length of an entity-body is the length of the message-body after
+ any transfer codings have been removed. Section 4.4 defines how the
+ length of a message-body is determined.
+
+8 Connections
+
+8.1 Persistent Connections
+
+8.1.1 Purpose
+
+ Prior to persistent connections, a separate TCP connection was
+ established to fetch each URL, increasing the load on HTTP servers
+ and causing congestion on the Internet. The use of inline images and
+ other associated data often requires a client to make multiple
+ requests of the same server in a short amount of time. Analyses of
+ these performance problems are available [30][27]; analysis and
+ results from a prototype implementation are in [26].
+
+ Persistent HTTP connections have a number of advantages:
+
+ o By opening and closing fewer TCP connections, CPU time is saved,
+ and memory used for TCP protocol control blocks is also saved.
+ o HTTP requests and responses can be pipelined on a connection.
+ Pipelining allows a client to make multiple requests without
+ waiting for each response, allowing a single TCP connection to be
+ used much more efficiently, with much lower elapsed time.
+ o Network congestion is reduced by reducing the number of packets
+ caused by TCP opens, and by allowing TCP sufficient time to
+ determine the congestion state of the network.
+ o HTTP can evolve more gracefully; since errors can be reported
+ without the penalty of closing the TCP connection. Clients using
+ future versions of HTTP might optimistically try a new feature, but
+ if communicating with an older server, retry with old semantics
+ after an error is reported.
+
+ HTTP implementations SHOULD implement persistent connections.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 43]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+8.1.2 Overall Operation
+
+ A significant difference between HTTP/1.1 and earlier versions of
+ HTTP is that persistent connections are the default behavior of any
+ HTTP connection. That is, unless otherwise indicated, the client may
+ assume that the server will maintain a persistent connection.
+
+ Persistent connections provide a mechanism by which a client and a
+ server can signal the close of a TCP connection. This signaling takes
+ place using the Connection header field. Once a close has been
+ signaled, the client MUST not send any more requests on that
+ connection.
+
+8.1.2.1 Negotiation
+
+ An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to
+ maintain a persistent connection unless a Connection header including
+ the connection-token "close" was sent in the request. If the server
+ chooses to close the connection immediately after sending the
+ response, it SHOULD send a Connection header including the
+ connection-token close.
+
+ An HTTP/1.1 client MAY expect a connection to remain open, but would
+ decide to keep it open based on whether the response from a server
+ contains a Connection header with the connection-token close. In case
+ the client does not want to maintain a connection for more than that
+ request, it SHOULD send a Connection header including the
+ connection-token close.
+
+ If either the client or the server sends the close token in the
+ Connection header, that request becomes the last one for the
+ connection.
+
+ Clients and servers SHOULD NOT assume that a persistent connection is
+ maintained for HTTP versions less than 1.1 unless it is explicitly
+ signaled. See section 19.7.1 for more information on backwards
+ compatibility with HTTP/1.0 clients.
+
+ In order to remain persistent, all messages on the connection must
+ have a self-defined message length (i.e., one not defined by closure
+ of the connection), as described in section 4.4.
+
+8.1.2.2 Pipelining
+
+ A client that supports persistent connections MAY "pipeline" its
+ requests (i.e., send multiple requests without waiting for each
+ response). A server MUST send its responses to those requests in the
+ same order that the requests were received.
+
+
+
+Fielding, et. al. Standards Track [Page 44]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Clients which assume persistent connections and pipeline immediately
+ after connection establishment SHOULD be prepared to retry their
+ connection if the first pipelined attempt fails. If a client does
+ such a retry, it MUST NOT pipeline before it knows the connection is
+ persistent. Clients MUST also be prepared to resend their requests if
+ the server closes the connection before sending all of the
+ corresponding responses.
+
+8.1.3 Proxy Servers
+
+ It is especially important that proxies correctly implement the
+ properties of the Connection header field as specified in 14.2.1.
+
+ The proxy server MUST signal persistent connections separately with
+ its clients and the origin servers (or other proxy servers) that it
+ connects to. Each persistent connection applies to only one transport
+ link.
+
+ A proxy server MUST NOT establish a persistent connection with an
+ HTTP/1.0 client.
+
+8.1.4 Practical Considerations
+
+ Servers will usually have some time-out value beyond which they will
+ no longer maintain an inactive connection. Proxy servers might make
+ this a higher value since it is likely that the client will be making
+ more connections through the same server. The use of persistent
+ connections places no requirements on the length of this time-out for
+ either the client or the server.
+
+ When a client or server wishes to time-out it SHOULD issue a graceful
+ close on the transport connection. Clients and servers SHOULD both
+ constantly watch for the other side of the transport close, and
+ respond to it as appropriate. If a client or server does not detect
+ the other side's close promptly it could cause unnecessary resource
+ drain on the network.
+
+ A client, server, or proxy MAY close the transport connection at any
+ time. For example, a client MAY have started to send a new request at
+ the same time that the server has decided to close the "idle"
+ connection. From the server's point of view, the connection is being
+ closed while it was idle, but from the client's point of view, a
+ request is in progress.
+
+ This means that clients, servers, and proxies MUST be able to recover
+ from asynchronous close events. Client software SHOULD reopen the
+ transport connection and retransmit the aborted request without user
+ interaction so long as the request method is idempotent (see section
+
+
+
+Fielding, et. al. Standards Track [Page 45]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 9.1.2); other methods MUST NOT be automatically retried, although
+ user agents MAY offer a human operator the choice of retrying the
+ request.
+
+ However, this automatic retry SHOULD NOT be repeated if the second
+ request fails.
+
+ Servers SHOULD always respond to at least one request per connection,
+ if at all possible. Servers SHOULD NOT close a connection in the
+ middle of transmitting a response, unless a network or client failure
+ is suspected.
+
+ Clients that use persistent connections SHOULD limit the number of
+ simultaneous connections that they maintain to a given server. A
+ single-user client SHOULD maintain AT MOST 2 connections with any
+ server or proxy. A proxy SHOULD use up to 2*N connections to another
+ server or proxy, where N is the number of simultaneously active
+ users. These guidelines are intended to improve HTTP response times
+ and avoid congestion of the Internet or other networks.
+
+8.2 Message Transmission Requirements
+
+General requirements:
+
+o HTTP/1.1 servers SHOULD maintain persistent connections and use
+ TCP's flow control mechanisms to resolve temporary overloads,
+ rather than terminating connections with the expectation that
+ clients will retry. The latter technique can exacerbate network
+ congestion.
+
+o An HTTP/1.1 (or later) client sending a message-body SHOULD monitor
+ the network connection for an error status while it is transmitting
+ the request. If the client sees an error status, it SHOULD
+ immediately cease transmitting the body. If the body is being sent
+ using a "chunked" encoding (section 3.6), a zero length chunk and
+ empty footer MAY be used to prematurely mark the end of the
+ message. If the body was preceded by a Content-Length header, the
+ client MUST close the connection.
+
+o An HTTP/1.1 (or later) client MUST be prepared to accept a 100
+ (Continue) status followed by a regular response.
+
+o An HTTP/1.1 (or later) server that receives a request from a
+ HTTP/1.0 (or earlier) client MUST NOT transmit the 100 (continue)
+ response; it SHOULD either wait for the request to be completed
+ normally (thus avoiding an interrupted request) or close the
+ connection prematurely.
+
+
+
+
+Fielding, et. al. Standards Track [Page 46]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Upon receiving a method subject to these requirements from an
+ HTTP/1.1 (or later) client, an HTTP/1.1 (or later) server MUST either
+ respond with 100 (Continue) status and continue to read from the
+ input stream, or respond with an error status. If it responds with an
+ error status, it MAY close the transport (TCP) connection or it MAY
+ continue to read and discard the rest of the request. It MUST NOT
+ perform the requested method if it returns an error status.
+
+ Clients SHOULD remember the version number of at least the most
+ recently used server; if an HTTP/1.1 client has seen an HTTP/1.1 or
+ later response from the server, and it sees the connection close
+ before receiving any status from the server, the client SHOULD retry
+ the request without user interaction so long as the request method is
+ idempotent (see section 9.1.2); other methods MUST NOT be
+ automatically retried, although user agents MAY offer a human
+ operator the choice of retrying the request.. If the client does
+ retry the request, the client
+
+ o MUST first send the request header fields, and then
+
+ o MUST wait for the server to respond with either a 100 (Continue)
+ response, in which case the client should continue, or with an
+ error status.
+
+ If an HTTP/1.1 client has not seen an HTTP/1.1 or later response from
+ the server, it should assume that the server implements HTTP/1.0 or
+ older and will not use the 100 (Continue) response. If in this case
+ the client sees the connection close before receiving any status from
+ the server, the client SHOULD retry the request. If the client does
+ retry the request to this HTTP/1.0 server, it should use the
+ following "binary exponential backoff" algorithm to be assured of
+ obtaining a reliable response:
+
+ 1. Initiate a new connection to the server
+
+ 2. Transmit the request-headers
+
+ 3. Initialize a variable R to the estimated round-trip time to the
+ server (e.g., based on the time it took to establish the
+ connection), or to a constant value of 5 seconds if the round-trip
+ time is not available.
+
+ 4. Compute T = R * (2**N), where N is the number of previous retries
+ of this request.
+
+ 5. Wait either for an error response from the server, or for T seconds
+ (whichever comes first)
+
+
+
+
+Fielding, et. al. Standards Track [Page 47]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ 6. If no error response is received, after T seconds transmit the body
+ of the request.
+
+ 7. If client sees that the connection is closed prematurely, repeat
+ from step 1 until the request is accepted, an error response is
+ received, or the user becomes impatient and terminates the retry
+ process.
+
+ No matter what the server version, if an error status is received,
+ the client
+
+ o MUST NOT continue and
+
+ o MUST close the connection if it has not completed sending the
+ message.
+
+ An HTTP/1.1 (or later) client that sees the connection close after
+ receiving a 100 (Continue) but before receiving any other status
+ SHOULD retry the request, and need not wait for 100 (Continue)
+ response (but MAY do so if this simplifies the implementation).
+
+9 Method Definitions
+
+ The set of common methods for HTTP/1.1 is defined below. Although
+ this set can be expanded, additional methods cannot be assumed to
+ share the same semantics for separately extended clients and servers.
+
+ The Host request-header field (section 14.23) MUST accompany all
+ HTTP/1.1 requests.
+
+9.1 Safe and Idempotent Methods
+
+9.1.1 Safe Methods
+
+ Implementers should be aware that the software represents the user in
+ their interactions over the Internet, and should be careful to allow
+ the user to be aware of any actions they may take which may have an
+ unexpected significance to themselves or others.
+
+ In particular, the convention has been established that the GET and
+ HEAD methods should never have the significance of taking an action
+ other than retrieval. These methods should be considered "safe." This
+ allows user agents to represent other methods, such as POST, PUT and
+ DELETE, in a special way, so that the user is made aware of the fact
+ that a possibly unsafe action is being requested.
+
+ Naturally, it is not possible to ensure that the server does not
+ generate side-effects as a result of performing a GET request; in
+
+
+
+Fielding, et. al. Standards Track [Page 48]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ fact, some dynamic resources consider that a feature. The important
+ distinction here is that the user did not request the side-effects,
+ so therefore cannot be held accountable for them.
+
+9.1.2 Idempotent Methods
+
+ Methods may also have the property of "idempotence" in that (aside
+ from error or expiration issues) the side-effects of N > 0 identical
+ requests is the same as for a single request. The methods GET, HEAD,
+ PUT and DELETE share this property.
+
+9.2 OPTIONS
+
+ The OPTIONS method represents a request for information about the
+ communication options available on the request/response chain
+ identified by the Request-URI. This method allows the client to
+ determine the options and/or requirements associated with a resource,
+ or the capabilities of a server, without implying a resource action
+ or initiating a resource retrieval.
+
+ Unless the server's response is an error, the response MUST NOT
+ include entity information other than what can be considered as
+ communication options (e.g., Allow is appropriate, but Content-Type
+ is not). Responses to this method are not cachable.
+
+ If the Request-URI is an asterisk ("*"), the OPTIONS request is
+ intended to apply to the server as a whole. A 200 response SHOULD
+ include any header fields which indicate optional features
+ implemented by the server (e.g., Public), including any extensions
+ not defined by this specification, in addition to any applicable
+ general or response-header fields. As described in section 5.1.2, an
+ "OPTIONS *" request can be applied through a proxy by specifying the
+ destination server in the Request-URI without any path information.
+
+ If the Request-URI is not an asterisk, the OPTIONS request applies
+ only to the options that are available when communicating with that
+ resource. A 200 response SHOULD include any header fields which
+ indicate optional features implemented by the server and applicable
+ to that resource (e.g., Allow), including any extensions not defined
+ by this specification, in addition to any applicable general or
+ response-header fields. If the OPTIONS request passes through a
+ proxy, the proxy MUST edit the response to exclude those options
+ which apply to a proxy's capabilities and which are known to be
+ unavailable through that proxy.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 49]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+9.3 GET
+
+ The GET method means retrieve whatever information (in the form of an
+ entity) is identified by the Request-URI. If the Request-URI refers
+ to a data-producing process, it is the produced data which shall be
+ returned as the entity in the response and not the source text of the
+ process, unless that text happens to be the output of the process.
+
+ The semantics of the GET method change to a "conditional GET" if the
+ request message includes an If-Modified-Since, If-Unmodified-Since,
+ If-Match, If-None-Match, or If-Range header field. A conditional GET
+ method requests that the entity be transferred only under the
+ circumstances described by the conditional header field(s). The
+ conditional GET method is intended to reduce unnecessary network
+ usage by allowing cached entities to be refreshed without requiring
+ multiple requests or transferring data already held by the client.
+
+ The semantics of the GET method change to a "partial GET" if the
+ request message includes a Range header field. A partial GET requests
+ that only part of the entity be transferred, as described in section
+ 14.36. The partial GET method is intended to reduce unnecessary
+ network usage by allowing partially-retrieved entities to be
+ completed without transferring data already held by the client.
+
+ The response to a GET request is cachable if and only if it meets the
+ requirements for HTTP caching described in section 13.
+
+9.4 HEAD
+
+ The HEAD method is identical to GET except that the server MUST NOT
+ return a message-body in the response. The metainformation contained
+ in the HTTP headers in response to a HEAD request SHOULD be identical
+ to the information sent in response to a GET request. This method can
+ be used for obtaining metainformation about the entity implied by the
+ request without transferring the entity-body itself. This method is
+ often used for testing hypertext links for validity, accessibility,
+ and recent modification.
+
+ The response to a HEAD request may be cachable in the sense that the
+ information contained in the response may be used to update a
+ previously cached entity from that resource. If the new field values
+ indicate that the cached entity differs from the current entity (as
+ would be indicated by a change in Content-Length, Content-MD5, ETag
+ or Last-Modified), then the cache MUST treat the cache entry as
+ stale.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 50]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+9.5 POST
+
+ The POST method is used to request that the destination server accept
+ the entity enclosed in the request as a new subordinate of the
+ resource identified by the Request-URI in the Request-Line. POST is
+ designed to allow a uniform method to cover the following functions:
+
+ o Annotation of existing resources;
+
+ o Posting a message to a bulletin board, newsgroup, mailing list,
+ or similar group of articles;
+
+ o Providing a block of data, such as the result of submitting a
+ form, to a data-handling process;
+
+ o Extending a database through an append operation.
+
+ The actual function performed by the POST method is determined by the
+ server and is usually dependent on the Request-URI. The posted entity
+ is subordinate to that URI in the same way that a file is subordinate
+ to a directory containing it, a news article is subordinate to a
+ newsgroup to which it is posted, or a record is subordinate to a
+ database.
+
+ The action performed by the POST method might not result in a
+ resource that can be identified by a URI. In this case, either 200
+ (OK) or 204 (No Content) is the appropriate response status,
+ depending on whether or not the response includes an entity that
+ describes the result.
+
+ If a resource has been created on the origin server, the response
+ SHOULD be 201 (Created) and contain an entity which describes the
+ status of the request and refers to the new resource, and a Location
+ header (see section 14.30).
+
+ Responses to this method are not cachable, unless the response
+ includes appropriate Cache-Control or Expires header fields. However,
+ the 303 (See Other) response can be used to direct the user agent to
+ retrieve a cachable resource.
+
+ POST requests must obey the message transmission requirements set out
+ in section 8.2.
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 51]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+9.6 PUT
+
+ The PUT method requests that the enclosed entity be stored under the
+ supplied Request-URI. If the Request-URI refers to an already
+ existing resource, the enclosed entity SHOULD be considered as a
+ modified version of the one residing on the origin server. If the
+ Request-URI does not point to an existing resource, and that URI is
+ capable of being defined as a new resource by the requesting user
+ agent, the origin server can create the resource with that URI. If a
+ new resource is created, the origin server MUST inform the user agent
+ via the 201 (Created) response. If an existing resource is modified,
+ either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
+ to indicate successful completion of the request. If the resource
+ could not be created or modified with the Request-URI, an appropriate
+ error response SHOULD be given that reflects the nature of the
+ problem. The recipient of the entity MUST NOT ignore any Content-*
+ (e.g. Content-Range) headers that it does not understand or implement
+ and MUST return a 501 (Not Implemented) response in such cases.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries should be
+ treated as stale. Responses to this method are not cachable.
+
+ The fundamental difference between the POST and PUT requests is
+ reflected in the different meaning of the Request-URI. The URI in a
+ POST request identifies the resource that will handle the enclosed
+ entity. That resource may be a data-accepting process, a gateway to
+ some other protocol, or a separate entity that accepts annotations.
+ In contrast, the URI in a PUT request identifies the entity enclosed
+ with the request -- the user agent knows what URI is intended and the
+ server MUST NOT attempt to apply the request to some other resource.
+ If the server desires that the request be applied to a different URI,
+ it MUST send a 301 (Moved Permanently) response; the user agent MAY
+ then make its own decision regarding whether or not to redirect the
+ request.
+
+ A single resource MAY be identified by many different URIs. For
+ example, an article may have a URI for identifying "the current
+ version" which is separate from the URI identifying each particular
+ version. In this case, a PUT request on a general URI may result in
+ several other URIs being defined by the origin server.
+
+ HTTP/1.1 does not define how a PUT method affects the state of an
+ origin server.
+
+ PUT requests must obey the message transmission requirements set out
+ in section 8.2.
+
+
+
+
+Fielding, et. al. Standards Track [Page 52]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+9.7 DELETE
+
+ The DELETE method requests that the origin server delete the resource
+ identified by the Request-URI. This method MAY be overridden by human
+ intervention (or other means) on the origin server. The client cannot
+ be guaranteed that the operation has been carried out, even if the
+ status code returned from the origin server indicates that the action
+ has been completed successfully. However, the server SHOULD not
+ indicate success unless, at the time the response is given, it
+ intends to delete the resource or move it to an inaccessible
+ location.
+
+ A successful response SHOULD be 200 (OK) if the response includes an
+ entity describing the status, 202 (Accepted) if the action has not
+ yet been enacted, or 204 (No Content) if the response is OK but does
+ not include an entity.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries should be
+ treated as stale. Responses to this method are not cachable.
+
+9.8 TRACE
+
+ The TRACE method is used to invoke a remote, application-layer loop-
+ back of the request message. The final recipient of the request
+ SHOULD reflect the message received back to the client as the
+ entity-body of a 200 (OK) response. The final recipient is either the
+ origin server or the first proxy or gateway to receive a Max-Forwards
+ value of zero (0) in the request (see section 14.31). A TRACE request
+ MUST NOT include an entity.
+
+ TRACE allows the client to see what is being received at the other
+ end of the request chain and use that data for testing or diagnostic
+ information. The value of the Via header field (section 14.44) is of
+ particular interest, since it acts as a trace of the request chain.
+ Use of the Max-Forwards header field allows the client to limit the
+ length of the request chain, which is useful for testing a chain of
+ proxies forwarding messages in an infinite loop.
+
+ If successful, the response SHOULD contain the entire request message
+ in the entity-body, with a Content-Type of "message/http". Responses
+ to this method MUST NOT be cached.
+
+10 Status Code Definitions
+
+ Each Status-Code is described below, including a description of which
+ method(s) it can follow and any metainformation required in the
+ response.
+
+
+
+Fielding, et. al. Standards Track [Page 53]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.1 Informational 1xx
+
+ This class of status code indicates a provisional response,
+ consisting only of the Status-Line and optional headers, and is
+ terminated by an empty line. Since HTTP/1.0 did not define any 1xx
+ status codes, servers MUST NOT send a 1xx response to an HTTP/1.0
+ client except under experimental conditions.
+
+10.1.1 100 Continue
+
+ The client may continue with its request. This interim response is
+ used to inform the client that the initial part of the request has
+ been received and has not yet been rejected by the server. The client
+ SHOULD continue by sending the remainder of the request or, if the
+ request has already been completed, ignore this response. The server
+ MUST send a final response after the request has been completed.
+
+10.1.2 101 Switching Protocols
+
+ The server understands and is willing to comply with the client's
+ request, via the Upgrade message header field (section 14.41), for a
+ change in the application protocol being used on this connection. The
+ server will switch protocols to those defined by the response's
+ Upgrade header field immediately after the empty line which
+ terminates the 101 response.
+
+ The protocol should only be switched when it is advantageous to do
+ so. For example, switching to a newer version of HTTP is
+ advantageous over older versions, and switching to a real-time,
+ synchronous protocol may be advantageous when delivering resources
+ that use such features.
+
+10.2 Successful 2xx
+
+ This class of status code indicates that the client's request was
+ successfully received, understood, and accepted.
+
+10.2.1 200 OK
+
+ The request has succeeded. The information returned with the response
+ is dependent on the method used in the request, for example:
+
+ GET an entity corresponding to the requested resource is sent in the
+ response;
+
+ HEAD the entity-header fields corresponding to the requested resource
+ are sent in the response without any message-body;
+
+
+
+
+Fielding, et. al. Standards Track [Page 54]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ POST an entity describing or containing the result of the action;
+
+ TRACE an entity containing the request message as received by the end
+ server.
+
+10.2.2 201 Created
+
+ The request has been fulfilled and resulted in a new resource being
+ created. The newly created resource can be referenced by the URI(s)
+ returned in the entity of the response, with the most specific URL
+ for the resource given by a Location header field. The origin server
+ MUST create the resource before returning the 201 status code. If the
+ action cannot be carried out immediately, the server should respond
+ with 202 (Accepted) response instead.
+
+10.2.3 202 Accepted
+
+ The request has been accepted for processing, but the processing has
+ not been completed. The request MAY or MAY NOT eventually be acted
+ upon, as it MAY be disallowed when processing actually takes place.
+ There is no facility for re-sending a status code from an
+ asynchronous operation such as this.
+
+ The 202 response is intentionally non-committal. Its purpose is to
+ allow a server to accept a request for some other process (perhaps a
+ batch-oriented process that is only run once per day) without
+ requiring that the user agent's connection to the server persist
+ until the process is completed. The entity returned with this
+ response SHOULD include an indication of the request's current status
+ and either a pointer to a status monitor or some estimate of when the
+ user can expect the request to be fulfilled.
+
+10.2.4 203 Non-Authoritative Information
+
+ The returned metainformation in the entity-header is not the
+ definitive set as available from the origin server, but is gathered
+ from a local or a third-party copy. The set presented MAY be a subset
+ or superset of the original version. For example, including local
+ annotation information about the resource MAY result in a superset of
+ the metainformation known by the origin server. Use of this response
+ code is not required and is only appropriate when the response would
+ otherwise be 200 (OK).
+
+10.2.5 204 No Content
+
+ The server has fulfilled the request but there is no new information
+ to send back. If the client is a user agent, it SHOULD NOT change its
+ document view from that which caused the request to be sent. This
+
+
+
+Fielding, et. al. Standards Track [Page 55]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ response is primarily intended to allow input for actions to take
+ place without causing a change to the user agent's active document
+ view. The response MAY include new metainformation in the form of
+ entity-headers, which SHOULD apply to the document currently in the
+ user agent's active view.
+
+ The 204 response MUST NOT include a message-body, and thus is always
+ terminated by the first empty line after the header fields.
+
+10.2.6 205 Reset Content
+
+ The server has fulfilled the request and the user agent SHOULD reset
+ the document view which caused the request to be sent. This response
+ is primarily intended to allow input for actions to take place via
+ user input, followed by a clearing of the form in which the input is
+ given so that the user can easily initiate another input action. The
+ response MUST NOT include an entity.
+
+10.2.7 206 Partial Content
+
+ The server has fulfilled the partial GET request for the resource.
+ The request must have included a Range header field (section 14.36)
+ indicating the desired range. The response MUST include either a
+ Content-Range header field (section 14.17) indicating the range
+ included with this response, or a multipart/byteranges Content-Type
+ including Content-Range fields for each part. If multipart/byteranges
+ is not used, the Content-Length header field in the response MUST
+ match the actual number of OCTETs transmitted in the message-body.
+
+ A cache that does not support the Range and Content-Range headers
+ MUST NOT cache 206 (Partial) responses.
+
+10.3 Redirection 3xx
+
+ This class of status code indicates that further action needs to be
+ taken by the user agent in order to fulfill the request. The action
+ required MAY be carried out by the user agent without interaction
+ with the user if and only if the method used in the second request is
+ GET or HEAD. A user agent SHOULD NOT automatically redirect a request
+ more than 5 times, since such redirections usually indicate an
+ infinite loop.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 56]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.3.1 300 Multiple Choices
+
+ The requested resource corresponds to any one of a set of
+ representations, each with its own specific location, and agent-
+ driven negotiation information (section 12) is being provided so that
+ the user (or user agent) can select a preferred representation and
+ redirect its request to that location.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of resource characteristics and location(s) from
+ which the user or user agent can choose the one most appropriate. The
+ entity format is specified by the media type given in the Content-
+ Type header field. Depending upon the format and the capabilities of
+ the user agent, selection of the most appropriate choice may be
+ performed automatically. However, this specification does not define
+ any standard for such automatic selection.
+
+ If the server has a preferred choice of representation, it SHOULD
+ include the specific URL for that representation in the Location
+ field; user agents MAY use the Location field value for automatic
+ redirection. This response is cachable unless indicated otherwise.
+
+10.3.2 301 Moved Permanently
+
+ The requested resource has been assigned a new permanent URI and any
+ future references to this resource SHOULD be done using one of the
+ returned URIs. Clients with link editing capabilities SHOULD
+ automatically re-link references to the Request-URI to one or more of
+ the new references returned by the server, where possible. This
+ response is cachable unless indicated otherwise.
+
+ If the new URI is a location, its URL SHOULD be given by the Location
+ field in the response. Unless the request method was HEAD, the entity
+ of the response SHOULD contain a short hypertext note with a
+ hyperlink to the new URI(s).
+
+ If the 301 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: When automatically redirecting a POST request after receiving
+ a 301 status code, some existing HTTP/1.0 user agents will
+ erroneously change it into a GET request.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 57]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.3.3 302 Moved Temporarily
+
+ The requested resource resides temporarily under a different URI.
+ Since the redirection may be altered on occasion, the client SHOULD
+ continue to use the Request-URI for future requests. This response is
+ only cachable if indicated by a Cache-Control or Expires header
+ field.
+
+ If the new URI is a location, its URL SHOULD be given by the Location
+ field in the response. Unless the request method was HEAD, the entity
+ of the response SHOULD contain a short hypertext note with a
+ hyperlink to the new URI(s).
+
+ If the 302 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: When automatically redirecting a POST request after receiving
+ a 302 status code, some existing HTTP/1.0 user agents will
+ erroneously change it into a GET request.
+
+10.3.4 303 See Other
+
+ The response to the request can be found under a different URI and
+ SHOULD be retrieved using a GET method on that resource. This method
+ exists primarily to allow the output of a POST-activated script to
+ redirect the user agent to a selected resource. The new URI is not a
+ substitute reference for the originally requested resource. The 303
+ response is not cachable, but the response to the second (redirected)
+ request MAY be cachable.
+
+ If the new URI is a location, its URL SHOULD be given by the Location
+ field in the response. Unless the request method was HEAD, the entity
+ of the response SHOULD contain a short hypertext note with a
+ hyperlink to the new URI(s).
+
+10.3.5 304 Not Modified
+
+ If the client has performed a conditional GET request and access is
+ allowed, but the document has not been modified, the server SHOULD
+ respond with this status code. The response MUST NOT contain a
+ message-body.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 58]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The response MUST include the following header fields:
+
+ o Date
+
+ o ETag and/or Content-Location, if the header would have been sent in
+ a 200 response to the same request
+
+ o Expires, Cache-Control, and/or Vary, if the field-value might
+ differ from that sent in any previous response for the same variant
+
+ If the conditional GET used a strong cache validator (see section
+ 13.3.3), the response SHOULD NOT include other entity-headers.
+ Otherwise (i.e., the conditional GET used a weak validator), the
+ response MUST NOT include other entity-headers; this prevents
+ inconsistencies between cached entity-bodies and updated headers.
+
+ If a 304 response indicates an entity not currently cached, then the
+ cache MUST disregard the response and repeat the request without the
+ conditional.
+
+ If a cache uses a received 304 response to update a cache entry, the
+ cache MUST update the entry to reflect any new field values given in
+ the response.
+
+ The 304 response MUST NOT include a message-body, and thus is always
+ terminated by the first empty line after the header fields.
+
+10.3.6 305 Use Proxy
+
+ The requested resource MUST be accessed through the proxy given by
+ the Location field. The Location field gives the URL of the proxy.
+ The recipient is expected to repeat the request via the proxy.
+
+10.4 Client Error 4xx
+
+ The 4xx class of status code is intended for cases in which the
+ client seems to have erred. Except when responding to a HEAD request,
+ the server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. These status codes are applicable to any request method.
+ User agents SHOULD display any included entity to the user.
+
+ Note: If the client is sending data, a server implementation using
+ TCP should be careful to ensure that the client acknowledges
+ receipt of the packet(s) containing the response, before the server
+ closes the input connection. If the client continues sending data
+ to the server after the close, the server's TCP stack will send a
+ reset packet to the client, which may erase the client's
+
+
+
+Fielding, et. al. Standards Track [Page 59]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ unacknowledged input buffers before they can be read and
+ interpreted by the HTTP application.
+
+10.4.1 400 Bad Request
+
+ The request could not be understood by the server due to malformed
+ syntax. The client SHOULD NOT repeat the request without
+ modifications.
+
+10.4.2 401 Unauthorized
+
+ The request requires user authentication. The response MUST include a
+ WWW-Authenticate header field (section 14.46) containing a challenge
+ applicable to the requested resource. The client MAY repeat the
+ request with a suitable Authorization header field (section 14.8). If
+ the request already included Authorization credentials, then the 401
+ response indicates that authorization has been refused for those
+ credentials. If the 401 response contains the same challenge as the
+ prior response, and the user agent has already attempted
+ authentication at least once, then the user SHOULD be presented the
+ entity that was given in the response, since that entity MAY include
+ relevant diagnostic information. HTTP access authentication is
+ explained in section 11.
+
+10.4.3 402 Payment Required
+
+ This code is reserved for future use.
+
+10.4.4 403 Forbidden
+
+ The server understood the request, but is refusing to fulfill it.
+ Authorization will not help and the request SHOULD NOT be repeated.
+ If the request method was not HEAD and the server wishes to make
+ public why the request has not been fulfilled, it SHOULD describe the
+ reason for the refusal in the entity. This status code is commonly
+ used when the server does not wish to reveal exactly why the request
+ has been refused, or when no other response is applicable.
+
+10.4.5 404 Not Found
+
+ The server has not found anything matching the Request-URI. No
+ indication is given of whether the condition is temporary or
+ permanent.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 60]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If the server does not wish to make this information available to the
+ client, the status code 403 (Forbidden) can be used instead. The 410
+ (Gone) status code SHOULD be used if the server knows, through some
+ internally configurable mechanism, that an old resource is
+ permanently unavailable and has no forwarding address.
+
+10.4.6 405 Method Not Allowed
+
+ The method specified in the Request-Line is not allowed for the
+ resource identified by the Request-URI. The response MUST include an
+ Allow header containing a list of valid methods for the requested
+ resource.
+
+10.4.7 406 Not Acceptable
+
+ The resource identified by the request is only capable of generating
+ response entities which have content characteristics not acceptable
+ according to the accept headers sent in the request.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of available entity characteristics and location(s)
+ from which the user or user agent can choose the one most
+ appropriate. The entity format is specified by the media type given
+ in the Content-Type header field. Depending upon the format and the
+ capabilities of the user agent, selection of the most appropriate
+ choice may be performed automatically. However, this specification
+ does not define any standard for such automatic selection.
+
+ Note: HTTP/1.1 servers are allowed to return responses which are
+ not acceptable according to the accept headers sent in the request.
+ In some cases, this may even be preferable to sending a 406
+ response. User agents are encouraged to inspect the headers of an
+ incoming response to determine if it is acceptable. If the response
+ could be unacceptable, a user agent SHOULD temporarily stop receipt
+ of more data and query the user for a decision on further actions.
+
+10.4.8 407 Proxy Authentication Required
+
+ This code is similar to 401 (Unauthorized), but indicates that the
+ client MUST first authenticate itself with the proxy. The proxy MUST
+ return a Proxy-Authenticate header field (section 14.33) containing a
+ challenge applicable to the proxy for the requested resource. The
+ client MAY repeat the request with a suitable Proxy-Authorization
+ header field (section 14.34). HTTP access authentication is explained
+ in section 11.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 61]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.4.9 408 Request Timeout
+
+ The client did not produce a request within the time that the server
+ was prepared to wait. The client MAY repeat the request without
+ modifications at any later time.
+
+10.4.10 409 Conflict
+
+ The request could not be completed due to a conflict with the current
+ state of the resource. This code is only allowed in situations where
+ it is expected that the user might be able to resolve the conflict
+ and resubmit the request. The response body SHOULD include enough
+ information for the user to recognize the source of the conflict.
+ Ideally, the response entity would include enough information for the
+ user or user agent to fix the problem; however, that may not be
+ possible and is not required.
+
+ Conflicts are most likely to occur in response to a PUT request. If
+ versioning is being used and the entity being PUT includes changes to
+ a resource which conflict with those made by an earlier (third-party)
+ request, the server MAY use the 409 response to indicate that it
+ can't complete the request. In this case, the response entity SHOULD
+ contain a list of the differences between the two versions in a
+ format defined by the response Content-Type.
+
+10.4.11 410 Gone
+
+ The requested resource is no longer available at the server and no
+ forwarding address is known. This condition SHOULD be considered
+ permanent. Clients with link editing capabilities SHOULD delete
+ references to the Request-URI after user approval. If the server does
+ not know, or has no facility to determine, whether or not the
+ condition is permanent, the status code 404 (Not Found) SHOULD be
+ used instead. This response is cachable unless indicated otherwise.
+
+ The 410 response is primarily intended to assist the task of web
+ maintenance by notifying the recipient that the resource is
+ intentionally unavailable and that the server owners desire that
+ remote links to that resource be removed. Such an event is common for
+ limited-time, promotional services and for resources belonging to
+ individuals no longer working at the server's site. It is not
+ necessary to mark all permanently unavailable resources as "gone" or
+ to keep the mark for any length of time -- that is left to the
+ discretion of the server owner.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 62]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.4.12 411 Length Required
+
+ The server refuses to accept the request without a defined Content-
+ Length. The client MAY repeat the request if it adds a valid
+ Content-Length header field containing the length of the message-body
+ in the request message.
+
+10.4.13 412 Precondition Failed
+
+ The precondition given in one or more of the request-header fields
+ evaluated to false when it was tested on the server. This response
+ code allows the client to place preconditions on the current resource
+ metainformation (header field data) and thus prevent the requested
+ method from being applied to a resource other than the one intended.
+
+10.4.14 413 Request Entity Too Large
+
+ The server is refusing to process a request because the request
+ entity is larger than the server is willing or able to process. The
+ server may close the connection to prevent the client from continuing
+ the request.
+
+ If the condition is temporary, the server SHOULD include a Retry-
+ After header field to indicate that it is temporary and after what
+ time the client may try again.
+
+10.4.15 414 Request-URI Too Long
+
+ The server is refusing to service the request because the Request-URI
+ is longer than the server is willing to interpret. This rare
+ condition is only likely to occur when a client has improperly
+ converted a POST request to a GET request with long query
+ information, when the client has descended into a URL "black hole" of
+ redirection (e.g., a redirected URL prefix that points to a suffix of
+ itself), or when the server is under attack by a client attempting to
+ exploit security holes present in some servers using fixed-length
+ buffers for reading or manipulating the Request-URI.
+
+10.4.16 415 Unsupported Media Type
+
+ The server is refusing to service the request because the entity of
+ the request is in a format not supported by the requested resource
+ for the requested method.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 63]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.5 Server Error 5xx
+
+ Response status codes beginning with the digit "5" indicate cases in
+ which the server is aware that it has erred or is incapable of
+ performing the request. Except when responding to a HEAD request, the
+ server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. User agents SHOULD display any included entity to the
+ user. These response codes are applicable to any request method.
+
+10.5.1 500 Internal Server Error
+
+ The server encountered an unexpected condition which prevented it
+ from fulfilling the request.
+
+10.5.2 501 Not Implemented
+
+ The server does not support the functionality required to fulfill the
+ request. This is the appropriate response when the server does not
+ recognize the request method and is not capable of supporting it for
+ any resource.
+
+10.5.3 502 Bad Gateway
+
+ The server, while acting as a gateway or proxy, received an invalid
+ response from the upstream server it accessed in attempting to
+ fulfill the request.
+
+10.5.4 503 Service Unavailable
+
+ The server is currently unable to handle the request due to a
+ temporary overloading or maintenance of the server. The implication
+ is that this is a temporary condition which will be alleviated after
+ some delay. If known, the length of the delay may be indicated in a
+ Retry-After header. If no Retry-After is given, the client SHOULD
+ handle the response as it would for a 500 response.
+
+ Note: The existence of the 503 status code does not imply that a
+ server must use it when becoming overloaded. Some servers may wish
+ to simply refuse the connection.
+
+10.5.5 504 Gateway Timeout
+
+ The server, while acting as a gateway or proxy, did not receive a
+ timely response from the upstream server it accessed in attempting to
+ complete the request.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 64]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+10.5.6 505 HTTP Version Not Supported
+
+ The server does not support, or refuses to support, the HTTP protocol
+ version that was used in the request message. The server is
+ indicating that it is unable or unwilling to complete the request
+ using the same major version as the client, as described in section
+ 3.1, other than with this error message. The response SHOULD contain
+ an entity describing why that version is not supported and what other
+ protocols are supported by that server.
+
+11 Access Authentication
+
+ HTTP provides a simple challenge-response authentication mechanism
+ which MAY be used by a server to challenge a client request and by a
+ client to provide authentication information. It uses an extensible,
+ case-insensitive token to identify the authentication scheme,
+ followed by a comma-separated list of attribute-value pairs which
+ carry the parameters necessary for achieving authentication via that
+ scheme.
+
+ auth-scheme = token
+
+ auth-param = token "=" quoted-string
+
+ The 401 (Unauthorized) response message is used by an origin server
+ to challenge the authorization of a user agent. This response MUST
+ include a WWW-Authenticate header field containing at least one
+ challenge applicable to the requested resource.
+
+ challenge = auth-scheme 1*SP realm *( "," auth-param )
+
+ realm = "realm" "=" realm-value
+ realm-value = quoted-string
+
+ The realm attribute (case-insensitive) is required for all
+ authentication schemes which issue a challenge. The realm value
+ (case-sensitive), in combination with the canonical root URL (see
+ section 5.1.2) of the server being accessed, defines the protection
+ space. These realms allow the protected resources on a server to be
+ partitioned into a set of protection spaces, each with its own
+ authentication scheme and/or authorization database. The realm value
+ is a string, generally assigned by the origin server, which may have
+ additional semantics specific to the authentication scheme.
+
+ A user agent that wishes to authenticate itself with a server--
+ usually, but not necessarily, after receiving a 401 or 411 response-
+ -MAY do so by including an Authorization header field with the
+ request. The Authorization field value consists of credentials
+
+
+
+Fielding, et. al. Standards Track [Page 65]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ containing the authentication information of the user agent for the
+ realm of the resource being requested.
+
+ credentials = basic-credentials
+ | auth-scheme #auth-param
+
+ The domain over which credentials can be automatically applied by a
+ user agent is determined by the protection space. If a prior request
+ has been authorized, the same credentials MAY be reused for all other
+ requests within that protection space for a period of time determined
+ by the authentication scheme, parameters, and/or user preference.
+ Unless otherwise defined by the authentication scheme, a single
+ protection space cannot extend outside the scope of its server.
+
+ If the server does not wish to accept the credentials sent with a
+ request, it SHOULD return a 401 (Unauthorized) response. The response
+ MUST include a WWW-Authenticate header field containing the (possibly
+ new) challenge applicable to the requested resource and an entity
+ explaining the refusal.
+
+ The HTTP protocol does not restrict applications to this simple
+ challenge-response mechanism for access authentication. Additional
+ mechanisms MAY be used, such as encryption at the transport level or
+ via message encapsulation, and with additional header fields
+ specifying authentication information. However, these additional
+ mechanisms are not defined by this specification.
+
+ Proxies MUST be completely transparent regarding user agent
+ authentication. That is, they MUST forward the WWW-Authenticate and
+ Authorization headers untouched, and follow the rules found in
+ section 14.8.
+
+ HTTP/1.1 allows a client to pass authentication information to and
+ from a proxy via the Proxy-Authenticate and Proxy-Authorization
+ headers.
+
+11.1 Basic Authentication Scheme
+
+ The "basic" authentication scheme is based on the model that the user
+ agent must authenticate itself with a user-ID and a password for each
+ realm. The realm value should be considered an opaque string which
+ can only be compared for equality with other realms on that server.
+ The server will service the request only if it can validate the
+ user-ID and password for the protection space of the Request-URI.
+ There are no optional authentication parameters.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 66]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Upon receipt of an unauthorized request for a URI within the
+ protection space, the server MAY respond with a challenge like the
+ following:
+
+ WWW-Authenticate: Basic realm="WallyWorld"
+
+ where "WallyWorld" is the string assigned by the server to identify
+ the protection space of the Request-URI.
+
+ To receive authorization, the client sends the userid and password,
+ separated by a single colon (":") character, within a base64 encoded
+ string in the credentials.
+
+ basic-credentials = "Basic" SP basic-cookie
+
+ basic-cookie = <base64 [7] encoding of user-pass,
+ except not limited to 76 char/line>
+
+ user-pass = userid ":" password
+
+ userid = *<TEXT excluding ":">
+
+ password = *TEXT
+
+ Userids might be case sensitive.
+
+ If the user agent wishes to send the userid "Aladdin" and password
+ "open sesame", it would use the following header field:
+
+ Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+
+ See section 15 for security considerations associated with Basic
+ authentication.
+
+11.2 Digest Authentication Scheme
+
+ A digest authentication for HTTP is specified in RFC 2069 [32].
+
+12 Content Negotiation
+
+ Most HTTP responses include an entity which contains information for
+ interpretation by a human user. Naturally, it is desirable to supply
+ the user with the "best available" entity corresponding to the
+ request. Unfortunately for servers and caches, not all users have
+ the same preferences for what is "best," and not all user agents are
+ equally capable of rendering all entity types. For that reason, HTTP
+ has provisions for several mechanisms for "content negotiation" --
+ the process of selecting the best representation for a given response
+
+
+
+Fielding, et. al. Standards Track [Page 67]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ when there are multiple representations available.
+
+ Note: This is not called "format negotiation" because the alternate
+ representations may be of the same media type, but use different
+ capabilities of that type, be in different languages, etc.
+
+ Any response containing an entity-body MAY be subject to negotiation,
+ including error responses.
+
+ There are two kinds of content negotiation which are possible in
+ HTTP: server-driven and agent-driven negotiation. These two kinds of
+ negotiation are orthogonal and thus may be used separately or in
+ combination. One method of combination, referred to as transparent
+ negotiation, occurs when a cache uses the agent-driven negotiation
+ information provided by the origin server in order to provide
+ server-driven negotiation for subsequent requests.
+
+12.1 Server-driven Negotiation
+
+ If the selection of the best representation for a response is made by
+ an algorithm located at the server, it is called server-driven
+ negotiation. Selection is based on the available representations of
+ the response (the dimensions over which it can vary; e.g. language,
+ content-coding, etc.) and the contents of particular header fields in
+ the request message or on other information pertaining to the request
+ (such as the network address of the client).
+
+ Server-driven negotiation is advantageous when the algorithm for
+ selecting from among the available representations is difficult to
+ describe to the user agent, or when the server desires to send its
+ "best guess" to the client along with the first response (hoping to
+ avoid the round-trip delay of a subsequent request if the "best
+ guess" is good enough for the user). In order to improve the server's
+ guess, the user agent MAY include request header fields (Accept,
+ Accept-Language, Accept-Encoding, etc.) which describe its
+ preferences for such a response.
+
+ Server-driven negotiation has disadvantages:
+
+1. It is impossible for the server to accurately determine what might be
+ "best" for any given user, since that would require complete
+ knowledge of both the capabilities of the user agent and the intended
+ use for the response (e.g., does the user want to view it on screen
+ or print it on paper?).
+
+2. Having the user agent describe its capabilities in every request can
+ be both very inefficient (given that only a small percentage of
+ responses have multiple representations) and a potential violation of
+
+
+
+Fielding, et. al. Standards Track [Page 68]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ the user's privacy.
+
+3. It complicates the implementation of an origin server and the
+ algorithms for generating responses to a request.
+
+4. It may limit a public cache's ability to use the same response for
+ multiple user's requests.
+
+ HTTP/1.1 includes the following request-header fields for enabling
+ server-driven negotiation through description of user agent
+ capabilities and user preferences: Accept (section 14.1), Accept-
+ Charset (section 14.2), Accept-Encoding (section 14.3), Accept-
+ Language (section 14.4), and User-Agent (section 14.42). However, an
+ origin server is not limited to these dimensions and MAY vary the
+ response based on any aspect of the request, including information
+ outside the request-header fields or within extension header fields
+ not defined by this specification.
+
+ HTTP/1.1 origin servers MUST include an appropriate Vary header field
+ (section 14.43) in any cachable response based on server-driven
+ negotiation. The Vary header field describes the dimensions over
+ which the response might vary (i.e. the dimensions over which the
+ origin server picks its "best guess" response from multiple
+ representations).
+
+ HTTP/1.1 public caches MUST recognize the Vary header field when it
+ is included in a response and obey the requirements described in
+ section 13.6 that describes the interactions between caching and
+ content negotiation.
+
+12.2 Agent-driven Negotiation
+
+ With agent-driven negotiation, selection of the best representation
+ for a response is performed by the user agent after receiving an
+ initial response from the origin server. Selection is based on a list
+ of the available representations of the response included within the
+ header fields (this specification reserves the field-name Alternates,
+ as described in appendix 19.6.2.1) or entity-body of the initial
+ response, with each representation identified by its own URI.
+ Selection from among the representations may be performed
+ automatically (if the user agent is capable of doing so) or manually
+ by the user selecting from a generated (possibly hypertext) menu.
+
+ Agent-driven negotiation is advantageous when the response would vary
+ over commonly-used dimensions (such as type, language, or encoding),
+ when the origin server is unable to determine a user agent's
+ capabilities from examining the request, and generally when public
+ caches are used to distribute server load and reduce network usage.
+
+
+
+Fielding, et. al. Standards Track [Page 69]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Agent-driven negotiation suffers from the disadvantage of needing a
+ second request to obtain the best alternate representation. This
+ second request is only efficient when caching is used. In addition,
+ this specification does not define any mechanism for supporting
+ automatic selection, though it also does not prevent any such
+ mechanism from being developed as an extension and used within
+ HTTP/1.1.
+
+ HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable)
+ status codes for enabling agent-driven negotiation when the server is
+ unwilling or unable to provide a varying response using server-driven
+ negotiation.
+
+12.3 Transparent Negotiation
+
+ Transparent negotiation is a combination of both server-driven and
+ agent-driven negotiation. When a cache is supplied with a form of the
+ list of available representations of the response (as in agent-driven
+ negotiation) and the dimensions of variance are completely understood
+ by the cache, then the cache becomes capable of performing server-
+ driven negotiation on behalf of the origin server for subsequent
+ requests on that resource.
+
+ Transparent negotiation has the advantage of distributing the
+ negotiation work that would otherwise be required of the origin
+ server and also removing the second request delay of agent-driven
+ negotiation when the cache is able to correctly guess the right
+ response.
+
+ This specification does not define any mechanism for transparent
+ negotiation, though it also does not prevent any such mechanism from
+ being developed as an extension and used within HTTP/1.1. An HTTP/1.1
+ cache performing transparent negotiation MUST include a Vary header
+ field in the response (defining the dimensions of its variance) if it
+ is cachable to ensure correct interoperation with all HTTP/1.1
+ clients. The agent-driven negotiation information supplied by the
+ origin server SHOULD be included with the transparently negotiated
+ response.
+
+13 Caching in HTTP
+
+ HTTP is typically used for distributed information systems, where
+ performance can be improved by the use of response caches. The
+ HTTP/1.1 protocol includes a number of elements intended to make
+ caching work as well as possible. Because these elements are
+ inextricable from other aspects of the protocol, and because they
+ interact with each other, it is useful to describe the basic caching
+ design of HTTP separately from the detailed descriptions of methods,
+
+
+
+Fielding, et. al. Standards Track [Page 70]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ headers, response codes, etc.
+
+ Caching would be useless if it did not significantly improve
+ performance. The goal of caching in HTTP/1.1 is to eliminate the need
+ to send requests in many cases, and to eliminate the need to send
+ full responses in many other cases. The former reduces the number of
+ network round-trips required for many operations; we use an
+ "expiration" mechanism for this purpose (see section 13.2). The
+ latter reduces network bandwidth requirements; we use a "validation"
+ mechanism for this purpose (see section 13.3).
+
+ Requirements for performance, availability, and disconnected
+ operation require us to be able to relax the goal of semantic
+ transparency. The HTTP/1.1 protocol allows origin servers, caches,
+ and clients to explicitly reduce transparency when necessary.
+ However, because non-transparent operation may confuse non-expert
+ users, and may be incompatible with certain server applications (such
+ as those for ordering merchandise), the protocol requires that
+ transparency be relaxed
+
+ o only by an explicit protocol-level request when relaxed by client
+ or origin server
+
+ o only with an explicit warning to the end user when relaxed by cache
+ or client
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 71]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Therefore, the HTTP/1.1 protocol provides these important elements:
+
+ 1. Protocol features that provide full semantic transparency when this
+ is required by all parties.
+
+ 2. Protocol features that allow an origin server or user agent to
+ explicitly request and control non-transparent operation.
+
+ 3. Protocol features that allow a cache to attach warnings to
+ responses that do not preserve the requested approximation of
+ semantic transparency.
+
+ A basic principle is that it must be possible for the clients to
+ detect any potential relaxation of semantic transparency.
+
+ Note: The server, cache, or client implementer may be faced with
+ design decisions not explicitly discussed in this specification. If
+ a decision may affect semantic transparency, the implementer ought
+ to err on the side of maintaining transparency unless a careful and
+ complete analysis shows significant benefits in breaking
+ transparency.
+
+13.1.1 Cache Correctness
+
+ A correct cache MUST respond to a request with the most up-to-date
+ response held by the cache that is appropriate to the request (see
+ sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
+ conditions:
+
+ 1. It has been checked for equivalence with what the origin server
+ would have returned by revalidating the response with the origin
+ server (section 13.3);
+
+ 2. It is "fresh enough" (see section 13.2). In the default case, this
+ means it meets the least restrictive freshness requirement of the
+ client, server, and cache (see section 14.9); if the origin server
+ so specifies, it is the freshness requirement of the origin server
+ alone.
+
+ 3. It includes a warning if the freshness demand of the client or the
+ origin server is violated (see section 13.1.5 and 14.45).
+
+ 4. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or
+ error (4xx or 5xx) response message.
+
+ If the cache can not communicate with the origin server, then a
+ correct cache SHOULD respond as above if the response can be
+ correctly served from the cache; if not it MUST return an error or
+
+
+
+Fielding, et. al. Standards Track [Page 72]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ warning indicating that there was a communication failure.
+
+ If a cache receives a response (either an entire response, or a 304
+ (Not Modified) response) that it would normally forward to the
+ requesting client, and the received response is no longer fresh, the
+ cache SHOULD forward it to the requesting client without adding a new
+ Warning (but without removing any existing Warning headers). A cache
+ SHOULD NOT attempt to revalidate a response simply because that
+ response became stale in transit; this might lead to an infinite
+ loop. An user agent that receives a stale response without a Warning
+ MAY display a warning indication to the user.
+
+13.1.2 Warnings
+
+ Whenever a cache returns a response that is neither first-hand nor
+ "fresh enough" (in the sense of condition 2 in section 13.1.1), it
+ must attach a warning to that effect, using a Warning response-
+ header. This warning allows clients to take appropriate action.
+
+ Warnings may be used for other purposes, both cache-related and
+ otherwise. The use of a warning, rather than an error status code,
+ distinguish these responses from true failures.
+
+ Warnings are always cachable, because they never weaken the
+ transparency of a response. This means that warnings can be passed to
+ HTTP/1.0 caches without danger; such caches will simply pass the
+ warning along as an entity-header in the response.
+
+ Warnings are assigned numbers between 0 and 99. This specification
+ defines the code numbers and meanings of each currently assigned
+ warnings, allowing a client or cache to take automated action in some
+ (but not all) cases.
+
+ Warnings also carry a warning text. The text may be in any
+ appropriate natural language (perhaps based on the client's Accept
+ headers), and include an optional indication of what character set is
+ used.
+
+ Multiple warnings may be attached to a response (either by the origin
+ server or by a cache), including multiple warnings with the same code
+ number. For example, a server may provide the same warning with texts
+ in both English and Basque.
+
+ When multiple warnings are attached to a response, it may not be
+ practical or reasonable to display all of them to the user. This
+ version of HTTP does not specify strict priority rules for deciding
+ which warnings to display and in what order, but does suggest some
+ heuristics.
+
+
+
+Fielding, et. al. Standards Track [Page 73]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The Warning header and the currently defined warnings are described
+ in section 14.45.
+
+13.1.3 Cache-control Mechanisms
+
+ The basic cache mechanisms in HTTP/1.1 (server-specified expiration
+ times and validators) are implicit directives to caches. In some
+ cases, a server or client may need to provide explicit directives to
+ the HTTP caches. We use the Cache-Control header for this purpose.
+
+ The Cache-Control header allows a client or server to transmit a
+ variety of directives in either requests or responses. These
+ directives typically override the default caching algorithms. As a
+ general rule, if there is any apparent conflict between header
+ values, the most restrictive interpretation should be applied (that
+ is, the one that is most likely to preserve semantic transparency).
+ However, in some cases, Cache-Control directives are explicitly
+ specified as weakening the approximation of semantic transparency
+ (for example, "max-stale" or "public").
+
+ The Cache-Control directives are described in detail in section 14.9.
+
+13.1.4 Explicit User Agent Warnings
+
+ Many user agents make it possible for users to override the basic
+ caching mechanisms. For example, the user agent may allow the user to
+ specify that cached entities (even explicitly stale ones) are never
+ validated. Or the user agent might habitually add "Cache-Control:
+ max-stale=3600" to every request. The user should have to explicitly
+ request either non-transparent behavior, or behavior that results in
+ abnormally ineffective caching.
+
+ If the user has overridden the basic caching mechanisms, the user
+ agent should explicitly indicate to the user whenever this results in
+ the display of information that might not meet the server's
+ transparency requirements (in particular, if the displayed entity is
+ known to be stale). Since the protocol normally allows the user agent
+ to determine if responses are stale or not, this indication need only
+ be displayed when this actually happens. The indication need not be a
+ dialog box; it could be an icon (for example, a picture of a rotting
+ fish) or some other visual indicator.
+
+ If the user has overridden the caching mechanisms in a way that would
+ abnormally reduce the effectiveness of caches, the user agent should
+ continually display an indication (for example, a picture of currency
+ in flames) so that the user does not inadvertently consume excess
+ resources or suffer from excessive latency.
+
+
+
+
+Fielding, et. al. Standards Track [Page 74]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+13.1.5 Exceptions to the Rules and Warnings
+
+ In some cases, the operator of a cache may choose to configure it to
+ return stale responses even when not requested by clients. This
+ decision should not be made lightly, but may be necessary for reasons
+ of availability or performance, especially when the cache is poorly
+ connected to the origin server. Whenever a cache returns a stale
+ response, it MUST mark it as such (using a Warning header). This
+ allows the client software to alert the user that there may be a
+ potential problem.
+
+ It also allows the user agent to take steps to obtain a first-hand or
+ fresh response. For this reason, a cache SHOULD NOT return a stale
+ response if the client explicitly requests a first-hand or fresh one,
+ unless it is impossible to comply for technical or policy reasons.
+
+13.1.6 Client-controlled Behavior
+
+ While the origin server (and to a lesser extent, intermediate caches,
+ by their contribution to the age of a response) are the primary
+ source of expiration information, in some cases the client may need
+ to control a cache's decision about whether to return a cached
+ response without validating it. Clients do this using several
+ directives of the Cache-Control header.
+
+ A client's request may specify the maximum age it is willing to
+ accept of an unvalidated response; specifying a value of zero forces
+ the cache(s) to revalidate all responses. A client may also specify
+ the minimum time remaining before a response expires. Both of these
+ options increase constraints on the behavior of caches, and so cannot
+ further relax the cache's approximation of semantic transparency.
+
+ A client may also specify that it will accept stale responses, up to
+ some maximum amount of staleness. This loosens the constraints on the
+ caches, and so may violate the origin server's specified constraints
+ on semantic transparency, but may be necessary to support
+ disconnected operation, or high availability in the face of poor
+ connectivity.
+
+13.2 Expiration Model
+
+13.2.1 Server-Specified Expiration
+
+ HTTP caching works best when caches can entirely avoid making
+ requests to the origin server. The primary mechanism for avoiding
+ requests is for an origin server to provide an explicit expiration
+ time in the future, indicating that a response may be used to satisfy
+ subsequent requests. In other words, a cache can return a fresh
+
+
+
+Fielding, et. al. Standards Track [Page 75]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ response without first contacting the server.
+
+ Our expectation is that servers will assign future explicit
+ expiration times to responses in the belief that the entity is not
+ likely to change, in a semantically significant way, before the
+ expiration time is reached. This normally preserves semantic
+ transparency, as long as the server's expiration times are carefully
+ chosen.
+
+ The expiration mechanism applies only to responses taken from a cache
+ and not to first-hand responses forwarded immediately to the
+ requesting client.
+
+ If an origin server wishes to force a semantically transparent cache
+ to validate every request, it may assign an explicit expiration time
+ in the past. This means that the response is always stale, and so the
+ cache SHOULD validate it before using it for subsequent requests. See
+ section 14.9.4 for a more restrictive way to force revalidation.
+
+ If an origin server wishes to force any HTTP/1.1 cache, no matter how
+ it is configured, to validate every request, it should use the
+ "must-revalidate" Cache-Control directive (see section 14.9).
+
+ Servers specify explicit expiration times using either the Expires
+ header, or the max-age directive of the Cache-Control header.
+
+ An expiration time cannot be used to force a user agent to refresh
+ its display or reload a resource; its semantics apply only to caching
+ mechanisms, and such mechanisms need only check a resource's
+ expiration status when a new request for that resource is initiated.
+ See section 13.13 for explanation of the difference between caches
+ and history mechanisms.
+
+13.2.2 Heuristic Expiration
+
+ Since origin servers do not always provide explicit expiration times,
+ HTTP caches typically assign heuristic expiration times, employing
+ algorithms that use other header values (such as the Last-Modified
+ time) to estimate a plausible expiration time. The HTTP/1.1
+ specification does not provide specific algorithms, but does impose
+ worst-case constraints on their results. Since heuristic expiration
+ times may compromise semantic transparency, they should be used
+ cautiously, and we encourage origin servers to provide explicit
+ expiration times as much as possible.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 76]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+13.2.3 Age Calculations
+
+ In order to know if a cached entry is fresh, a cache needs to know if
+ its age exceeds its freshness lifetime. We discuss how to calculate
+ the latter in section 13.2.4; this section describes how to calculate
+ the age of a response or cache entry.
+
+ In this discussion, we use the term "now" to mean "the current value
+ of the clock at the host performing the calculation." Hosts that use
+ HTTP, but especially hosts running origin servers and caches, should
+ use NTP [28] or some similar protocol to synchronize their clocks to
+ a globally accurate time standard.
+
+ Also note that HTTP/1.1 requires origin servers to send a Date header
+ with every response, giving the time at which the response was
+ generated. We use the term "date_value" to denote the value of the
+ Date header, in a form appropriate for arithmetic operations.
+
+ HTTP/1.1 uses the Age response-header to help convey age information
+ between caches. The Age header value is the sender's estimate of the
+ amount of time since the response was generated at the origin server.
+ In the case of a cached response that has been revalidated with the
+ origin server, the Age value is based on the time of revalidation,
+ not of the original response.
+
+ In essence, the Age value is the sum of the time that the response
+ has been resident in each of the caches along the path from the
+ origin server, plus the amount of time it has been in transit along
+ network paths.
+
+ We use the term "age_value" to denote the value of the Age header, in
+ a form appropriate for arithmetic operations.
+
+ A response's age can be calculated in two entirely independent ways:
+
+ 1. now minus date_value, if the local clock is reasonably well
+ synchronized to the origin server's clock. If the result is
+ negative, the result is replaced by zero.
+
+ 2. age_value, if all of the caches along the response path
+ implement HTTP/1.1.
+
+ Given that we have two independent ways to compute the age of a
+ response when it is received, we can combine these as
+
+ corrected_received_age = max(now - date_value, age_value)
+
+ and as long as we have either nearly synchronized clocks or all-
+
+
+
+Fielding, et. al. Standards Track [Page 77]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ HTTP/1.1 paths, one gets a reliable (conservative) result.
+
+ Note that this correction is applied at each HTTP/1.1 cache along the
+ path, so that if there is an HTTP/1.0 cache in the path, the correct
+ received age is computed as long as the receiving cache's clock is
+ nearly in sync. We don't need end-to-end clock synchronization
+ (although it is good to have), and there is no explicit clock
+ synchronization step.
+
+ Because of network-imposed delays, some significant interval may pass
+ from the time that a server generates a response and the time it is
+ received at the next outbound cache or client. If uncorrected, this
+ delay could result in improperly low ages.
+
+ Because the request that resulted in the returned Age value must have
+ been initiated prior to that Age value's generation, we can correct
+ for delays imposed by the network by recording the time at which the
+ request was initiated. Then, when an Age value is received, it MUST
+ be interpreted relative to the time the request was initiated, not
+ the time that the response was received. This algorithm results in
+ conservative behavior no matter how much delay is experienced. So, we
+ compute:
+
+ corrected_initial_age = corrected_received_age
+ + (now - request_time)
+
+ where "request_time" is the time (according to the local clock) when
+ the request that elicited this response was sent.
+
+ Summary of age calculation algorithm, when a cache receives a
+ response:
+
+ /*
+ * age_value
+ * is the value of Age: header received by the cache with
+ * this response.
+ * date_value
+ * is the value of the origin server's Date: header
+ * request_time
+ * is the (local) time when the cache made the request
+ * that resulted in this cached response
+ * response_time
+ * is the (local) time when the cache received the
+ * response
+ * now
+ * is the current (local) time
+ */
+ apparent_age = max(0, response_time - date_value);
+
+
+
+Fielding, et. al. Standards Track [Page 78]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ corrected_received_age = max(apparent_age, age_value);
+ response_delay = response_time - request_time;
+ corrected_initial_age = corrected_received_age + response_delay;
+ resident_time = now - response_time;
+ current_age = corrected_initial_age + resident_time;
+
+ When a cache sends a response, it must add to the
+ corrected_initial_age the amount of time that the response was
+ resident locally. It must then transmit this total age, using the Age
+ header, to the next recipient cache.
+
+ Note that a client cannot reliably tell that a response is first-
+ hand, but the presence of an Age header indicates that a response
+ is definitely not first-hand. Also, if the Date in a response is
+ earlier than the client's local request time, the response is
+ probably not first-hand (in the absence of serious clock skew).
+
+13.2.4 Expiration Calculations
+
+ In order to decide whether a response is fresh or stale, we need to
+ compare its freshness lifetime to its age. The age is calculated as
+ described in section 13.2.3; this section describes how to calculate
+ the freshness lifetime, and to determine if a response has expired.
+ In the discussion below, the values can be represented in any form
+ appropriate for arithmetic operations.
+
+ We use the term "expires_value" to denote the value of the Expires
+ header. We use the term "max_age_value" to denote an appropriate
+ value of the number of seconds carried by the max-age directive of
+ the Cache-Control header in a response (see section 14.10.
+
+ The max-age directive takes priority over Expires, so if max-age is
+ present in a response, the calculation is simply:
+
+ freshness_lifetime = max_age_value
+
+ Otherwise, if Expires is present in the response, the calculation is:
+
+ freshness_lifetime = expires_value - date_value
+
+ Note that neither of these calculations is vulnerable to clock skew,
+ since all of the information comes from the origin server.
+
+ If neither Expires nor Cache-Control: max-age appears in the
+ response, and the response does not include other restrictions on
+ caching, the cache MAY compute a freshness lifetime using a
+ heuristic. If the value is greater than 24 hours, the cache must
+ attach Warning 13 to any response whose age is more than 24 hours if
+
+
+
+Fielding, et. al. Standards Track [Page 79]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ such warning has not already been added.
+
+ Also, if the response does have a Last-Modified time, the heuristic
+ expiration value SHOULD be no more than some fraction of the interval
+ since that time. A typical setting of this fraction might be 10%.
+
+ The calculation to determine if a response has expired is quite
+ simple:
+
+ response_is_fresh = (freshness_lifetime > current_age)
+
+13.2.5 Disambiguating Expiration Values
+
+ Because expiration values are assigned optimistically, it is possible
+ for two caches to contain fresh values for the same resource that are
+ different.
+
+ If a client performing a retrieval receives a non-first-hand response
+ for a request that was already fresh in its own cache, and the Date
+ header in its existing cache entry is newer than the Date on the new
+ response, then the client MAY ignore the response. If so, it MAY
+ retry the request with a "Cache-Control: max-age=0" directive (see
+ section 14.9), to force a check with the origin server.
+
+ If a cache has two fresh responses for the same representation with
+ different validators, it MUST use the one with the more recent Date
+ header. This situation may arise because the cache is pooling
+ responses from other caches, or because a client has asked for a
+ reload or a revalidation of an apparently fresh cache entry.
+
+13.2.6 Disambiguating Multiple Responses
+
+ Because a client may be receiving responses via multiple paths, so
+ that some responses flow through one set of caches and other
+ responses flow through a different set of caches, a client may
+ receive responses in an order different from that in which the origin
+ server sent them. We would like the client to use the most recently
+ generated response, even if older responses are still apparently
+ fresh.
+
+ Neither the entity tag nor the expiration value can impose an
+ ordering on responses, since it is possible that a later response
+ intentionally carries an earlier expiration time. However, the
+ HTTP/1.1 specification requires the transmission of Date headers on
+ every response, and the Date values are ordered to a granularity of
+ one second.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 80]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ When a client tries to revalidate a cache entry, and the response it
+ receives contains a Date header that appears to be older than the one
+ for the existing entry, then the client SHOULD repeat the request
+ unconditionally, and include
+
+ Cache-Control: max-age=0
+
+ to force any intermediate caches to validate their copies directly
+ with the origin server, or
+
+ Cache-Control: no-cache
+
+ to force any intermediate caches to obtain a new copy from the origin
+ server.
+
+ If the Date values are equal, then the client may use either response
+ (or may, if it is being extremely prudent, request a new response).
+ Servers MUST NOT depend on clients being able to choose
+ deterministically between responses generated during the same second,
+ if their expiration times overlap.
+
+13.3 Validation Model
+
+ When a cache has a stale entry that it would like to use as a
+ response to a client's request, it first has to check with the origin
+ server (or possibly an intermediate cache with a fresh response) to
+ see if its cached entry is still usable. We call this "validating"
+ the cache entry. Since we do not want to have to pay the overhead of
+ retransmitting the full response if the cached entry is good, and we
+ do not want to pay the overhead of an extra round trip if the cached
+ entry is invalid, the HTTP/1.1 protocol supports the use of
+ conditional methods.
+
+ The key protocol features for supporting conditional methods are
+ those concerned with "cache validators." When an origin server
+ generates a full response, it attaches some sort of validator to it,
+ which is kept with the cache entry. When a client (user agent or
+ proxy cache) makes a conditional request for a resource for which it
+ has a cache entry, it includes the associated validator in the
+ request.
+
+ The server then checks that validator against the current validator
+ for the entity, and, if they match, it responds with a special status
+ code (usually, 304 (Not Modified)) and no entity-body. Otherwise, it
+ returns a full response (including entity-body). Thus, we avoid
+ transmitting the full response if the validator matches, and we avoid
+ an extra round trip if it does not match.
+
+
+
+
+Fielding, et. al. Standards Track [Page 81]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Note: the comparison functions used to decide if validators match
+ are defined in section 13.3.3.
+
+ In HTTP/1.1, a conditional request looks exactly the same as a normal
+ request for the same resource, except that it carries a special
+ header (which includes the validator) that implicitly turns the
+ method (usually, GET) into a conditional.
+
+ The protocol includes both positive and negative senses of cache-
+ validating conditions. That is, it is possible to request either that
+ a method be performed if and only if a validator matches or if and
+ only if no validators match.
+
+ Note: a response that lacks a validator may still be cached, and
+ served from cache until it expires, unless this is explicitly
+ prohibited by a Cache-Control directive. However, a cache cannot do
+ a conditional retrieval if it does not have a validator for the
+ entity, which means it will not be refreshable after it expires.
+
+13.3.1 Last-modified Dates
+
+ The Last-Modified entity-header field value is often used as a cache
+ validator. In simple terms, a cache entry is considered to be valid
+ if the entity has not been modified since the Last-Modified value.
+
+13.3.2 Entity Tag Cache Validators
+
+ The ETag entity-header field value, an entity tag, provides for an
+ "opaque" cache validator. This may allow more reliable validation in
+ situations where it is inconvenient to store modification dates,
+ where the one-second resolution of HTTP date values is not
+ sufficient, or where the origin server wishes to avoid certain
+ paradoxes that may arise from the use of modification dates.
+
+ Entity Tags are described in section 3.11. The headers used with
+ entity tags are described in sections 14.20, 14.25, 14.26 and 14.43.
+
+13.3.3 Weak and Strong Validators
+
+ Since both origin servers and caches will compare two validators to
+ decide if they represent the same or different entities, one normally
+ would expect that if the entity (the entity-body or any entity-
+ headers) changes in any way, then the associated validator would
+ change as well. If this is true, then we call this validator a
+ "strong validator."
+
+ However, there may be cases when a server prefers to change the
+ validator only on semantically significant changes, and not when
+
+
+
+Fielding, et. al. Standards Track [Page 82]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ insignificant aspects of the entity change. A validator that does not
+ always change when the resource changes is a "weak validator."
+
+ Entity tags are normally "strong validators," but the protocol
+ provides a mechanism to tag an entity tag as "weak." One can think of
+ a strong validator as one that changes whenever the bits of an entity
+ changes, while a weak value changes whenever the meaning of an entity
+ changes. Alternatively, one can think of a strong validator as part
+ of an identifier for a specific entity, while a weak validator is
+ part of an identifier for a set of semantically equivalent entities.
+
+ Note: One example of a strong validator is an integer that is
+ incremented in stable storage every time an entity is changed.
+
+ An entity's modification time, if represented with one-second
+ resolution, could be a weak validator, since it is possible that
+ the resource may be modified twice during a single second.
+
+ Support for weak validators is optional; however, weak validators
+ allow for more efficient caching of equivalent objects; for
+ example, a hit counter on a site is probably good enough if it is
+ updated every few days or weeks, and any value during that period
+ is likely "good enough" to be equivalent.
+
+ A "use" of a validator is either when a client generates a request
+ and includes the validator in a validating header field, or when a
+ server compares two validators.
+
+ Strong validators are usable in any context. Weak validators are only
+ usable in contexts that do not depend on exact equality of an entity.
+ For example, either kind is usable for a conditional GET of a full
+ entity. However, only a strong validator is usable for a sub-range
+ retrieval, since otherwise the client may end up with an internally
+ inconsistent entity.
+
+ The only function that the HTTP/1.1 protocol defines on validators is
+ comparison. There are two validator comparison functions, depending
+ on whether the comparison context allows the use of weak validators
+ or not:
+
+ o The strong comparison function: in order to be considered equal,
+ both validators must be identical in every way, and neither may be
+ weak.
+ o The weak comparison function: in order to be considered equal, both
+ validators must be identical in every way, but either or both of
+ them may be tagged as "weak" without affecting the result.
+
+ The weak comparison function MAY be used for simple (non-subrange)
+
+
+
+Fielding, et. al. Standards Track [Page 83]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ GET requests. The strong comparison function MUST be used in all
+ other cases.
+
+ An entity tag is strong unless it is explicitly tagged as weak.
+ Section 3.11 gives the syntax for entity tags.
+
+ A Last-Modified time, when used as a validator in a request, is
+ implicitly weak unless it is possible to deduce that it is strong,
+ using the following rules:
+
+ o The validator is being compared by an origin server to the actual
+ current validator for the entity and,
+ o That origin server reliably knows that the associated entity did
+ not change twice during the second covered by the presented
+ validator.
+or
+
+ o The validator is about to be used by a client in an If-Modified-
+ Since or If-Unmodified-Since header, because the client has a cache
+ entry for the associated entity, and
+ o That cache entry includes a Date value, which gives the time when
+ the origin server sent the original response, and
+ o The presented Last-Modified time is at least 60 seconds before the
+ Date value.
+or
+
+ o The validator is being compared by an intermediate cache to the
+ validator stored in its cache entry for the entity, and
+ o That cache entry includes a Date value, which gives the time when
+ the origin server sent the original response, and
+ o The presented Last-Modified time is at least 60 seconds before the
+ Date value.
+
+ This method relies on the fact that if two different responses were
+ sent by the origin server during the same second, but both had the
+ same Last-Modified time, then at least one of those responses would
+ have a Date value equal to its Last-Modified time. The arbitrary 60-
+ second limit guards against the possibility that the Date and Last-
+ Modified values are generated from different clocks, or at somewhat
+ different times during the preparation of the response. An
+ implementation may use a value larger than 60 seconds, if it is
+ believed that 60 seconds is too short.
+
+ If a client wishes to perform a sub-range retrieval on a value for
+ which it has only a Last-Modified time and no opaque validator, it
+ may do this only if the Last-Modified time is strong in the sense
+ described here.
+
+
+
+
+Fielding, et. al. Standards Track [Page 84]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ A cache or origin server receiving a cache-conditional request, other
+ than a full-body GET request, MUST use the strong comparison function
+ to evaluate the condition.
+
+ These rules allow HTTP/1.1 caches and clients to safely perform sub-
+ range retrievals on values that have been obtained from HTTP/1.0
+ servers.
+
+13.3.4 Rules for When to Use Entity Tags and Last-modified Dates
+
+ We adopt a set of rules and recommendations for origin servers,
+ clients, and caches regarding when various validator types should be
+ used, and for what purposes.
+
+ HTTP/1.1 origin servers:
+
+ o SHOULD send an entity tag validator unless it is not feasible to
+ generate one.
+ o MAY send a weak entity tag instead of a strong entity tag, if
+ performance considerations support the use of weak entity tags, or
+ if it is unfeasible to send a strong entity tag.
+ o SHOULD send a Last-Modified value if it is feasible to send one,
+ unless the risk of a breakdown in semantic transparency that could
+ result from using this date in an If-Modified-Since header would
+ lead to serious problems.
+
+ In other words, the preferred behavior for an HTTP/1.1 origin server
+ is to send both a strong entity tag and a Last-Modified value.
+
+ In order to be legal, a strong entity tag MUST change whenever the
+ associated entity value changes in any way. A weak entity tag SHOULD
+ change whenever the associated entity changes in a semantically
+ significant way.
+
+ Note: in order to provide semantically transparent caching, an
+ origin server must avoid reusing a specific strong entity tag value
+ for two different entities, or reusing a specific weak entity tag
+ value for two semantically different entities. Cache entries may
+ persist for arbitrarily long periods, regardless of expiration
+ times, so it may be inappropriate to expect that a cache will never
+ again attempt to validate an entry using a validator that it
+ obtained at some point in the past.
+
+ HTTP/1.1 clients:
+
+ o If an entity tag has been provided by the origin server, MUST
+ use that entity tag in any cache-conditional request (using
+ If-Match or If-None-Match).
+
+
+
+Fielding, et. al. Standards Track [Page 85]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ o If only a Last-Modified value has been provided by the origin
+ server, SHOULD use that value in non-subrange cache-conditional
+ requests (using If-Modified-Since).
+ o If only a Last-Modified value has been provided by an HTTP/1.0
+ origin server, MAY use that value in subrange cache-conditional
+ requests (using If-Unmodified-Since:). The user agent should
+ provide a way to disable this, in case of difficulty.
+ o If both an entity tag and a Last-Modified value have been
+ provided by the origin server, SHOULD use both validators in
+ cache-conditional requests. This allows both HTTP/1.0 and
+ HTTP/1.1 caches to respond appropriately.
+
+ An HTTP/1.1 cache, upon receiving a request, MUST use the most
+ restrictive validator when deciding whether the client's cache entry
+ matches the cache's own cache entry. This is only an issue when the
+ request contains both an entity tag and a last-modified-date
+ validator (If-Modified-Since or If-Unmodified-Since).
+
+ A note on rationale: The general principle behind these rules is
+ that HTTP/1.1 servers and clients should transmit as much non-
+ redundant information as is available in their responses and
+ requests. HTTP/1.1 systems receiving this information will make the
+ most conservative assumptions about the validators they receive.
+
+ HTTP/1.0 clients and caches will ignore entity tags. Generally,
+ last-modified values received or used by these systems will support
+ transparent and efficient caching, and so HTTP/1.1 origin servers
+ should provide Last-Modified values. In those rare cases where the
+ use of a Last-Modified value as a validator by an HTTP/1.0 system
+ could result in a serious problem, then HTTP/1.1 origin servers
+ should not provide one.
+
+13.3.5 Non-validating Conditionals
+
+ The principle behind entity tags is that only the service author
+ knows the semantics of a resource well enough to select an
+ appropriate cache validation mechanism, and the specification of any
+ validator comparison function more complex than byte-equality would
+ open up a can of worms. Thus, comparisons of any other headers
+ (except Last-Modified, for compatibility with HTTP/1.0) are never
+ used for purposes of validating a cache entry.
+
+13.4 Response Cachability
+
+ Unless specifically constrained by a Cache-Control (section 14.9)
+ directive, a caching system may always store a successful response
+ (see section 13.8) as a cache entry, may return it without validation
+ if it is fresh, and may return it after successful validation. If
+
+
+
+Fielding, et. al. Standards Track [Page 86]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ there is neither a cache validator nor an explicit expiration time
+ associated with a response, we do not expect it to be cached, but
+ certain caches may violate this expectation (for example, when little
+ or no network connectivity is available). A client can usually detect
+ that such a response was taken from a cache by comparing the Date
+ header to the current time.
+
+ Note that some HTTP/1.0 caches are known to violate this
+ expectation without providing any Warning.
+
+ However, in some cases it may be inappropriate for a cache to retain
+ an entity, or to return it in response to a subsequent request. This
+ may be because absolute semantic transparency is deemed necessary by
+ the service author, or because of security or privacy considerations.
+ Certain Cache-Control directives are therefore provided so that the
+ server can indicate that certain resource entities, or portions
+ thereof, may not be cached regardless of other considerations.
+
+ Note that section 14.8 normally prevents a shared cache from saving
+ and returning a response to a previous request if that request
+ included an Authorization header.
+
+ A response received with a status code of 200, 203, 206, 300, 301 or
+ 410 may be stored by a cache and used in reply to a subsequent
+ request, subject to the expiration mechanism, unless a Cache-Control
+ directive prohibits caching. However, a cache that does not support
+ the Range and Content-Range headers MUST NOT cache 206 (Partial
+ Content) responses.
+
+ A response received with any other status code MUST NOT be returned
+ in a reply to a subsequent request unless there are Cache-Control
+ directives or another header(s) that explicitly allow it. For
+ example, these include the following: an Expires header (section
+ 14.21); a "max-age", "must-revalidate", "proxy-revalidate", "public"
+ or "private" Cache-Control directive (section 14.9).
+
+13.5 Constructing Responses From Caches
+
+ The purpose of an HTTP cache is to store information received in
+ response to requests, for use in responding to future requests. In
+ many cases, a cache simply returns the appropriate parts of a
+ response to the requester. However, if the cache holds a cache entry
+ based on a previous response, it may have to combine parts of a new
+ response with what is held in the cache entry.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 87]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+13.5.1 End-to-end and Hop-by-hop Headers
+
+ For the purpose of defining the behavior of caches and non-caching
+ proxies, we divide HTTP headers into two categories:
+
+ o End-to-end headers, which must be transmitted to the
+ ultimate recipient of a request or response. End-to-end
+ headers in responses must be stored as part of a cache entry
+ and transmitted in any response formed from a cache entry.
+ o Hop-by-hop headers, which are meaningful only for a single
+ transport-level connection, and are not stored by caches or
+ forwarded by proxies.
+
+ The following HTTP/1.1 headers are hop-by-hop headers:
+
+ o Connection
+ o Keep-Alive
+ o Public
+ o Proxy-Authenticate
+ o Transfer-Encoding
+ o Upgrade
+
+ All other headers defined by HTTP/1.1 are end-to-end headers.
+
+ Hop-by-hop headers introduced in future versions of HTTP MUST be
+ listed in a Connection header, as described in section 14.10.
+
+13.5.2 Non-modifiable Headers
+
+ Some features of the HTTP/1.1 protocol, such as Digest
+ Authentication, depend on the value of certain end-to-end headers. A
+ cache or non-caching proxy SHOULD NOT modify an end-to-end header
+ unless the definition of that header requires or specifically allows
+ that.
+
+ A cache or non-caching proxy MUST NOT modify any of the following
+ fields in a request or response, nor may it add any of these fields
+ if not already present:
+
+ o Content-Location
+ o ETag
+ o Expires
+ o Last-Modified
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 88]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ A cache or non-caching proxy MUST NOT modify or add any of the
+ following fields in a response that contains the no-transform Cache-
+ Control directive, or in any request:
+
+ o Content-Encoding
+ o Content-Length
+ o Content-Range
+ o Content-Type
+
+ A cache or non-caching proxy MAY modify or add these fields in a
+ response that does not include no-transform, but if it does so, it
+ MUST add a Warning 14 (Transformation applied) if one does not
+ already appear in the response.
+
+ Warning: unnecessary modification of end-to-end headers may cause
+ authentication failures if stronger authentication mechanisms are
+ introduced in later versions of HTTP. Such authentication
+ mechanisms may rely on the values of header fields not listed here.
+
+13.5.3 Combining Headers
+
+ When a cache makes a validating request to a server, and the server
+ provides a 304 (Not Modified) response, the cache must construct a
+ response to send to the requesting client. The cache uses the
+ entity-body stored in the cache entry as the entity-body of this
+ outgoing response. The end-to-end headers stored in the cache entry
+ are used for the constructed response, except that any end-to-end
+ headers provided in the 304 response MUST replace the corresponding
+ headers from the cache entry. Unless the cache decides to remove the
+ cache entry, it MUST also replace the end-to-end headers stored with
+ the cache entry with corresponding headers received in the incoming
+ response.
+
+ In other words, the set of end-to-end headers received in the
+ incoming response overrides all corresponding end-to-end headers
+ stored with the cache entry. The cache may add Warning headers (see
+ section 14.45) to this set.
+
+ If a header field-name in the incoming response matches more than one
+ header in the cache entry, all such old headers are replaced.
+
+ Note: this rule allows an origin server to use a 304 (Not Modified)
+ response to update any header associated with a previous response
+ for the same entity, although it might not always be meaningful or
+ correct to do so. This rule does not allow an origin server to use
+ a 304 (not Modified) response to entirely delete a header that it
+ had provided with a previous response.
+
+
+
+
+Fielding, et. al. Standards Track [Page 89]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+13.5.4 Combining Byte Ranges
+
+ A response may transfer only a subrange of the bytes of an entity-
+ body, either because the request included one or more Range
+ specifications, or because a connection was broken prematurely. After
+ several such transfers, a cache may have received several ranges of
+ the same entity-body.
+
+ If a cache has a stored non-empty set of subranges for an entity, and
+ an incoming response transfers another subrange, the cache MAY
+ combine the new subrange with the existing set if both the following
+ conditions are met:
+
+ o Both the incoming response and the cache entry must have a cache
+ validator.
+ o The two cache validators must match using the strong comparison
+ function (see section 13.3.3).
+
+ If either requirement is not meant, the cache must use only the most
+ recent partial response (based on the Date values transmitted with
+ every response, and using the incoming response if these values are
+ equal or missing), and must discard the other partial information.
+
+13.6 Caching Negotiated Responses
+
+ Use of server-driven content negotiation (section 12), as indicated
+ by the presence of a Vary header field in a response, alters the
+ conditions and procedure by which a cache can use the response for
+ subsequent requests.
+
+ A server MUST use the Vary header field (section 14.43) to inform a
+ cache of what header field dimensions are used to select among
+ multiple representations of a cachable response. A cache may use the
+ selected representation (the entity included with that particular
+ response) for replying to subsequent requests on that resource only
+ when the subsequent requests have the same or equivalent values for
+ all header fields specified in the Vary response-header. Requests
+ with a different value for one or more of those header fields would
+ be forwarded toward the origin server.
+
+ If an entity tag was assigned to the representation, the forwarded
+ request SHOULD be conditional and include the entity tags in an If-
+ None-Match header field from all its cache entries for the Request-
+ URI. This conveys to the server the set of entities currently held by
+ the cache, so that if any one of these entities matches the requested
+ entity, the server can use the ETag header in its 304 (Not Modified)
+ response to tell the cache which entry is appropriate. If the
+ entity-tag of the new response matches that of an existing entry, the
+
+
+
+Fielding, et. al. Standards Track [Page 90]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ new response SHOULD be used to update the header fields of the
+ existing entry, and the result MUST be returned to the client.
+
+ The Vary header field may also inform the cache that the
+ representation was selected using criteria not limited to the
+ request-headers; in this case, a cache MUST NOT use the response in a
+ reply to a subsequent request unless the cache relays the new request
+ to the origin server in a conditional request and the server responds
+ with 304 (Not Modified), including an entity tag or Content-Location
+ that indicates which entity should be used.
+
+ If any of the existing cache entries contains only partial content
+ for the associated entity, its entity-tag SHOULD NOT be included in
+ the If-None-Match header unless the request is for a range that would
+ be fully satisfied by that entry.
+
+ If a cache receives a successful response whose Content-Location
+ field matches that of an existing cache entry for the same Request-
+ URI, whose entity-tag differs from that of the existing entry, and
+ whose Date is more recent than that of the existing entry, the
+ existing entry SHOULD NOT be returned in response to future requests,
+ and should be deleted from the cache.
+
+13.7 Shared and Non-Shared Caches
+
+ For reasons of security and privacy, it is necessary to make a
+ distinction between "shared" and "non-shared" caches. A non-shared
+ cache is one that is accessible only to a single user. Accessibility
+ in this case SHOULD be enforced by appropriate security mechanisms.
+ All other caches are considered to be "shared." Other sections of
+ this specification place certain constraints on the operation of
+ shared caches in order to prevent loss of privacy or failure of
+ access controls.
+
+13.8 Errors or Incomplete Response Cache Behavior
+
+ A cache that receives an incomplete response (for example, with fewer
+ bytes of data than specified in a Content-Length header) may store
+ the response. However, the cache MUST treat this as a partial
+ response. Partial responses may be combined as described in section
+ 13.5.4; the result might be a full response or might still be
+ partial. A cache MUST NOT return a partial response to a client
+ without explicitly marking it as such, using the 206 (Partial
+ Content) status code. A cache MUST NOT return a partial response
+ using a status code of 200 (OK).
+
+ If a cache receives a 5xx response while attempting to revalidate an
+ entry, it may either forward this response to the requesting client,
+
+
+
+Fielding, et. al. Standards Track [Page 91]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ or act as if the server failed to respond. In the latter case, it MAY
+ return a previously received response unless the cached entry
+ includes the "must-revalidate" Cache-Control directive (see section
+ 14.9).
+
+13.9 Side Effects of GET and HEAD
+
+ Unless the origin server explicitly prohibits the caching of their
+ responses, the application of GET and HEAD methods to any resources
+ SHOULD NOT have side effects that would lead to erroneous behavior if
+ these responses are taken from a cache. They may still have side
+ effects, but a cache is not required to consider such side effects in
+ its caching decisions. Caches are always expected to observe an
+ origin server's explicit restrictions on caching.
+
+ We note one exception to this rule: since some applications have
+ traditionally used GETs and HEADs with query URLs (those containing a
+ "?" in the rel_path part) to perform operations with significant side
+ effects, caches MUST NOT treat responses to such URLs as fresh unless
+ the server provides an explicit expiration time. This specifically
+ means that responses from HTTP/1.0 servers for such URIs should not
+ be taken from a cache. See section 9.1.1 for related information.
+
+13.10 Invalidation After Updates or Deletions
+
+ The effect of certain methods at the origin server may cause one or
+ more existing cache entries to become non-transparently invalid. That
+ is, although they may continue to be "fresh," they do not accurately
+ reflect what the origin server would return for a new request.
+
+ There is no way for the HTTP protocol to guarantee that all such
+ cache entries are marked invalid. For example, the request that
+ caused the change at the origin server may not have gone through the
+ proxy where a cache entry is stored. However, several rules help
+ reduce the likelihood of erroneous behavior.
+
+ In this section, the phrase "invalidate an entity" means that the
+ cache should either remove all instances of that entity from its
+ storage, or should mark these as "invalid" and in need of a mandatory
+ revalidation before they can be returned in response to a subsequent
+ request.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 92]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Some HTTP methods may invalidate an entity. This is either the entity
+ referred to by the Request-URI, or by the Location or Content-
+ Location response-headers (if present). These methods are:
+
+ o PUT
+ o DELETE
+ o POST
+
+ In order to prevent denial of service attacks, an invalidation based
+ on the URI in a Location or Content-Location header MUST only be
+ performed if the host part is the same as in the Request-URI.
+
+13.11 Write-Through Mandatory
+
+ All methods that may be expected to cause modifications to the origin
+ server's resources MUST be written through to the origin server. This
+ currently includes all methods except for GET and HEAD. A cache MUST
+ NOT reply to such a request from a client before having transmitted
+ the request to the inbound server, and having received a
+ corresponding response from the inbound server. This does not prevent
+ a cache from sending a 100 (Continue) response before the inbound
+ server has replied.
+
+ The alternative (known as "write-back" or "copy-back" caching) is not
+ allowed in HTTP/1.1, due to the difficulty of providing consistent
+ updates and the problems arising from server, cache, or network
+ failure prior to write-back.
+
+13.12 Cache Replacement
+
+ If a new cachable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
+ response is received from a resource while any existing responses for
+ the same resource are cached, the cache SHOULD use the new response
+ to reply to the current request. It may insert it into cache storage
+ and may, if it meets all other requirements, use it to respond to any
+ future requests that would previously have caused the old response to
+ be returned. If it inserts the new response into cache storage it
+ should follow the rules in section 13.5.3.
+
+ Note: a new response that has an older Date header value than
+ existing cached responses is not cachable.
+
+13.13 History Lists
+
+ User agents often have history mechanisms, such as "Back" buttons and
+ history lists, which can be used to redisplay an entity retrieved
+ earlier in a session.
+
+
+
+
+Fielding, et. al. Standards Track [Page 93]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ History mechanisms and caches are different. In particular history
+ mechanisms SHOULD NOT try to show a semantically transparent view of
+ the current state of a resource. Rather, a history mechanism is meant
+ to show exactly what the user saw at the time when the resource was
+ retrieved.
+
+ By default, an expiration time does not apply to history mechanisms.
+ If the entity is still in storage, a history mechanism should display
+ it even if the entity has expired, unless the user has specifically
+ configured the agent to refresh expired history documents.
+
+ This should not be construed to prohibit the history mechanism from
+ telling the user that a view may be stale.
+
+ Note: if history list mechanisms unnecessarily prevent users from
+ viewing stale resources, this will tend to force service authors to
+ avoid using HTTP expiration controls and cache controls when they
+ would otherwise like to. Service authors may consider it important
+ that users not be presented with error messages or warning messages
+ when they use navigation controls (such as BACK) to view previously
+ fetched resources. Even though sometimes such resources ought not
+ to cached, or ought to expire quickly, user interface
+ considerations may force service authors to resort to other means
+ of preventing caching (e.g. "once-only" URLs) in order not to
+ suffer the effects of improperly functioning history mechanisms.
+
+14 Header Field Definitions
+
+ This section defines the syntax and semantics of all standard
+ HTTP/1.1 header fields. For entity-header fields, both sender and
+ recipient refer to either the client or the server, depending on who
+ sends and who receives the entity.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 94]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.1 Accept
+
+ The Accept request-header field can be used to specify certain media
+ types which are acceptable for the response. Accept headers can be
+ used to indicate that the request is specifically limited to a small
+ set of desired types, as in the case of a request for an in-line
+ image.
+
+ Accept = "Accept" ":"
+ #( media-range [ accept-params ] )
+
+ media-range = ( "*/*"
+ | ( type "/" "*" )
+ | ( type "/" subtype )
+ ) *( ";" parameter )
+
+ accept-params = ";" "q" "=" qvalue *( accept-extension )
+
+ accept-extension = ";" token [ "=" ( token | quoted-string ) ]
+
+ The asterisk "*" character is used to group media types into ranges,
+ with "*/*" indicating all media types and "type/*" indicating all
+ subtypes of that type. The media-range MAY include media type
+ parameters that are applicable to that range.
+
+ Each media-range MAY be followed by one or more accept-params,
+ beginning with the "q" parameter for indicating a relative quality
+ factor. The first "q" parameter (if any) separates the media-range
+ parameter(s) from the accept-params. Quality factors allow the user
+ or user agent to indicate the relative degree of preference for that
+ media-range, using the qvalue scale from 0 to 1 (section 3.9). The
+ default value is q=1.
+
+ Note: Use of the "q" parameter name to separate media type
+ parameters from Accept extension parameters is due to historical
+ practice. Although this prevents any media type parameter named
+ "q" from being used with a media range, such an event is believed
+ to be unlikely given the lack of any "q" parameters in the IANA
+ media type registry and the rare usage of any media type parameters
+ in Accept. Future media types should be discouraged from
+ registering any parameter named "q".
+
+ The example
+
+ Accept: audio/*; q=0.2, audio/basic
+
+ SHOULD be interpreted as "I prefer audio/basic, but send me any audio
+ type if it is the best available after an 80% mark-down in quality."
+
+
+
+Fielding, et. al. Standards Track [Page 95]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If no Accept header field is present, then it is assumed that the
+ client accepts all media types. If an Accept header field is present,
+ and if the server cannot send a response which is acceptable
+ according to the combined Accept field value, then the server SHOULD
+ send a 406 (not acceptable) response.
+
+ A more elaborate example is
+
+ Accept: text/plain; q=0.5, text/html,
+ text/x-dvi; q=0.8, text/x-c
+
+ Verbally, this would be interpreted as "text/html and text/x-c are
+ the preferred media types, but if they do not exist, then send the
+ text/x-dvi entity, and if that does not exist, send the text/plain
+ entity."
+
+ Media ranges can be overridden by more specific media ranges or
+ specific media types. If more than one media range applies to a given
+ type, the most specific reference has precedence. For example,
+
+ Accept: text/*, text/html, text/html;level=1, */*
+
+ have the following precedence:
+
+ 1) text/html;level=1
+ 2) text/html
+ 3) text/*
+ 4) */*
+
+ The media type quality factor associated with a given type is
+ determined by finding the media range with the highest precedence
+ which matches that type. For example,
+
+ Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
+ text/html;level=2;q=0.4, */*;q=0.5
+
+ would cause the following values to be associated:
+
+ text/html;level=1 = 1
+ text/html = 0.7
+ text/plain = 0.3
+ image/jpeg = 0.5
+ text/html;level=2 = 0.4
+ text/html;level=3 = 0.7
+
+ Note: A user agent may be provided with a default set of quality
+ values for certain media ranges. However, unless the user agent is
+ a closed system which cannot interact with other rendering agents,
+
+
+
+Fielding, et. al. Standards Track [Page 96]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ this default set should be configurable by the user.
+
+14.2 Accept-Charset
+
+ The Accept-Charset request-header field can be used to indicate what
+ character sets are acceptable for the response. This field allows
+ clients capable of understanding more comprehensive or special-
+ purpose character sets to signal that capability to a server which is
+ capable of representing documents in those character sets. The ISO-
+ 8859-1 character set can be assumed to be acceptable to all user
+ agents.
+
+ Accept-Charset = "Accept-Charset" ":"
+ 1#( charset [ ";" "q" "=" qvalue ] )
+
+ Character set values are described in section 3.4. Each charset may
+ be given an associated quality value which represents the user's
+ preference for that charset. The default value is q=1. An example is
+
+ Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
+
+ If no Accept-Charset header is present, the default is that any
+ character set is acceptable. If an Accept-Charset header is present,
+ and if the server cannot send a response which is acceptable
+ according to the Accept-Charset header, then the server SHOULD send
+ an error response with the 406 (not acceptable) status code, though
+ the sending of an unacceptable response is also allowed.
+
+14.3 Accept-Encoding
+
+ The Accept-Encoding request-header field is similar to Accept, but
+ restricts the content-coding values (section 14.12) which are
+ acceptable in the response.
+
+ Accept-Encoding = "Accept-Encoding" ":"
+ #( content-coding )
+
+ An example of its use is
+
+ Accept-Encoding: compress, gzip
+
+ If no Accept-Encoding header is present in a request, the server MAY
+ assume that the client will accept any content coding. If an Accept-
+ Encoding header is present, and if the server cannot send a response
+ which is acceptable according to the Accept-Encoding header, then the
+ server SHOULD send an error response with the 406 (Not Acceptable)
+ status code.
+
+
+
+
+Fielding, et. al. Standards Track [Page 97]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ An empty Accept-Encoding value indicates none are acceptable.
+
+14.4 Accept-Language
+
+ The Accept-Language request-header field is similar to Accept, but
+ restricts the set of natural languages that are preferred as a
+ response to the request.
+
+ Accept-Language = "Accept-Language" ":"
+ 1#( language-range [ ";" "q" "=" qvalue ] )
+
+ language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
+
+ Each language-range MAY be given an associated quality value which
+ represents an estimate of the user's preference for the languages
+ specified by that range. The quality value defaults to "q=1". For
+ example,
+
+ Accept-Language: da, en-gb;q=0.8, en;q=0.7
+
+ would mean: "I prefer Danish, but will accept British English and
+ other types of English." A language-range matches a language-tag if
+ it exactly equals the tag, or if it exactly equals a prefix of the
+ tag such that the first tag character following the prefix is "-".
+ The special range "*", if present in the Accept-Language field,
+ matches every tag not matched by any other range present in the
+ Accept-Language field.
+
+ Note: This use of a prefix matching rule does not imply that
+ language tags are assigned to languages in such a way that it is
+ always true that if a user understands a language with a certain
+ tag, then this user will also understand all languages with tags
+ for which this tag is a prefix. The prefix rule simply allows the
+ use of prefix tags if this is the case.
+
+ The language quality factor assigned to a language-tag by the
+ Accept-Language field is the quality value of the longest language-
+ range in the field that matches the language-tag. If no language-
+ range in the field matches the tag, the language quality factor
+ assigned is 0. If no Accept-Language header is present in the
+ request, the server SHOULD assume that all languages are equally
+ acceptable. If an Accept-Language header is present, then all
+ languages which are assigned a quality factor greater than 0 are
+ acceptable.
+
+ It may be contrary to the privacy expectations of the user to send an
+ Accept-Language header with the complete linguistic preferences of
+ the user in every request. For a discussion of this issue, see
+
+
+
+Fielding, et. al. Standards Track [Page 98]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ section 15.7.
+
+ Note: As intelligibility is highly dependent on the individual
+ user, it is recommended that client applications make the choice of
+ linguistic preference available to the user. If the choice is not
+ made available, then the Accept-Language header field must not be
+ given in the request.
+
+14.5 Accept-Ranges
+
+ The Accept-Ranges response-header field allows the server to indicate
+ its acceptance of range requests for a resource:
+
+ Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
+
+ acceptable-ranges = 1#range-unit | "none"
+
+ Origin servers that accept byte-range requests MAY send
+
+ Accept-Ranges: bytes
+
+ but are not required to do so. Clients MAY generate byte-range
+ requests without having received this header for the resource
+ involved.
+
+ Servers that do not accept any kind of range request for a resource
+ MAY send
+
+ Accept-Ranges: none
+
+ to advise the client not to attempt a range request.
+
+14.6 Age
+
+ The Age response-header field conveys the sender's estimate of the
+ amount of time since the response (or its revalidation) was generated
+ at the origin server. A cached response is "fresh" if its age does
+ not exceed its freshness lifetime. Age values are calculated as
+ specified in section 13.2.3.
+
+ Age = "Age" ":" age-value
+
+ age-value = delta-seconds
+
+ Age values are non-negative decimal integers, representing time in
+ seconds.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 99]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If a cache receives a value larger than the largest positive integer
+ it can represent, or if any of its age calculations overflows, it
+ MUST transmit an Age header with a value of 2147483648 (2^31).
+ HTTP/1.1 caches MUST send an Age header in every response. Caches
+ SHOULD use an arithmetic type of at least 31 bits of range.
+
+14.7 Allow
+
+ The Allow entity-header field lists the set of methods supported by
+ the resource identified by the Request-URI. The purpose of this field
+ is strictly to inform the recipient of valid methods associated with
+ the resource. An Allow header field MUST be present in a 405 (Method
+ Not Allowed) response.
+
+ Allow = "Allow" ":" 1#method
+
+ Example of use:
+
+ Allow: GET, HEAD, PUT
+
+ This field cannot prevent a client from trying other methods.
+ However, the indications given by the Allow header field value SHOULD
+ be followed. The actual set of allowed methods is defined by the
+ origin server at the time of each request.
+
+ The Allow header field MAY be provided with a PUT request to
+ recommend the methods to be supported by the new or modified
+ resource. The server is not required to support these methods and
+ SHOULD include an Allow header in the response giving the actual
+ supported methods.
+
+ A proxy MUST NOT modify the Allow header field even if it does not
+ understand all the methods specified, since the user agent MAY have
+ other means of communicating with the origin server.
+
+ The Allow header field does not indicate what methods are implemented
+ at the server level. Servers MAY use the Public response-header field
+ (section 14.35) to describe what methods are implemented on the
+ server as a whole.
+
+14.8 Authorization
+
+ A user agent that wishes to authenticate itself with a server--
+ usually, but not necessarily, after receiving a 401 response--MAY do
+ so by including an Authorization request-header field with the
+ request. The Authorization field value consists of credentials
+ containing the authentication information of the user agent for the
+ realm of the resource being requested.
+
+
+
+Fielding, et. al. Standards Track [Page 100]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Authorization = "Authorization" ":" credentials
+
+ HTTP access authentication is described in section 11. If a request
+ is authenticated and a realm specified, the same credentials SHOULD
+ be valid for all other requests within this realm.
+
+ When a shared cache (see section 13.7) receives a request containing
+ an Authorization field, it MUST NOT return the corresponding response
+ as a reply to any other request, unless one of the following specific
+ exceptions holds:
+
+ 1. If the response includes the "proxy-revalidate" Cache-Control
+ directive, the cache MAY use that response in replying to a
+ subsequent request, but a proxy cache MUST first revalidate it with
+ the origin server, using the request-headers from the new request
+ to allow the origin server to authenticate the new request.
+ 2. If the response includes the "must-revalidate" Cache-Control
+ directive, the cache MAY use that response in replying to a
+ subsequent request, but all caches MUST first revalidate it with
+ the origin server, using the request-headers from the new request
+ to allow the origin server to authenticate the new request.
+ 3. If the response includes the "public" Cache-Control directive, it
+ may be returned in reply to any subsequent request.
+
+14.9 Cache-Control
+
+ The Cache-Control general-header field is used to specify directives
+ that MUST be obeyed by all caching mechanisms along the
+ request/response chain. The directives specify behavior intended to
+ prevent caches from adversely interfering with the request or
+ response. These directives typically override the default caching
+ algorithms. Cache directives are unidirectional in that the presence
+ of a directive in a request does not imply that the same directive
+ should be given in the response.
+
+ Note that HTTP/1.0 caches may not implement Cache-Control and may
+ only implement Pragma: no-cache (see section 14.32).
+
+ Cache directives must be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives may be applicable to all recipients along the
+ request/response chain. It is not possible to specify a cache-
+ directive for a specific cache.
+
+ Cache-Control = "Cache-Control" ":" 1#cache-directive
+
+ cache-directive = cache-request-directive
+ | cache-response-directive
+
+
+
+Fielding, et. al. Standards Track [Page 101]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ cache-request-directive =
+ "no-cache" [ "=" <"> 1#field-name <"> ]
+ | "no-store"
+ | "max-age" "=" delta-seconds
+ | "max-stale" [ "=" delta-seconds ]
+ | "min-fresh" "=" delta-seconds
+ | "only-if-cached"
+ | cache-extension
+
+ cache-response-directive =
+ "public"
+ | "private" [ "=" <"> 1#field-name <"> ]
+ | "no-cache" [ "=" <"> 1#field-name <"> ]
+ | "no-store"
+ | "no-transform"
+ | "must-revalidate"
+ | "proxy-revalidate"
+ | "max-age" "=" delta-seconds
+ | cache-extension
+
+ cache-extension = token [ "=" ( token | quoted-string ) ]
+
+ When a directive appears without any 1#field-name parameter, the
+ directive applies to the entire request or response. When such a
+ directive appears with a 1#field-name parameter, it applies only to
+ the named field or fields, and not to the rest of the request or
+ response. This mechanism supports extensibility; implementations of
+ future versions of the HTTP protocol may apply these directives to
+ header fields not defined in HTTP/1.1.
+
+ The cache-control directives can be broken down into these general
+ categories:
+
+ o Restrictions on what is cachable; these may only be imposed by the
+ origin server.
+ o Restrictions on what may be stored by a cache; these may be imposed
+ by either the origin server or the user agent.
+ o Modifications of the basic expiration mechanism; these may be
+ imposed by either the origin server or the user agent.
+ o Controls over cache revalidation and reload; these may only be
+ imposed by a user agent.
+ o Control over transformation of entities.
+ o Extensions to the caching system.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 102]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.9.1 What is Cachable
+
+ By default, a response is cachable if the requirements of the request
+ method, request header fields, and the response status indicate that
+ it is cachable. Section 13.4 summarizes these defaults for
+ cachability. The following Cache-Control response directives allow an
+ origin server to override the default cachability of a response:
+
+public
+ Indicates that the response is cachable by any cache, even if it
+ would normally be non-cachable or cachable only within a non-shared
+ cache. (See also Authorization, section 14.8, for additional
+ details.)
+
+private
+ Indicates that all or part of the response message is intended for a
+ single user and MUST NOT be cached by a shared cache. This allows an
+ origin server to state that the specified parts of the response are
+ intended for only one user and are not a valid response for requests
+ by other users. A private (non-shared) cache may cache the response.
+
+ Note: This usage of the word private only controls where the
+ response may be cached, and cannot ensure the privacy of the
+ message content.
+
+no-cache
+ Indicates that all or part of the response message MUST NOT be cached
+ anywhere. This allows an origin server to prevent caching even by
+ caches that have been configured to return stale responses to client
+ requests.
+
+ Note: Most HTTP/1.0 caches will not recognize or obey this
+ directive.
+
+14.9.2 What May be Stored by Caches
+
+ The purpose of the no-store directive is to prevent the inadvertent
+ release or retention of sensitive information (for example, on backup
+ tapes). The no-store directive applies to the entire message, and may
+ be sent either in a response or in a request. If sent in a request, a
+ cache MUST NOT store any part of either this request or any response
+ to it. If sent in a response, a cache MUST NOT store any part of
+ either this response or the request that elicited it. This directive
+ applies to both non-shared and shared caches. "MUST NOT store" in
+ this context means that the cache MUST NOT intentionally store the
+ information in non-volatile storage, and MUST make a best-effort
+ attempt to remove the information from volatile storage as promptly
+ as possible after forwarding it.
+
+
+
+Fielding, et. al. Standards Track [Page 103]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Even when this directive is associated with a response, users may
+ explicitly store such a response outside of the caching system (e.g.,
+ with a "Save As" dialog). History buffers may store such responses as
+ part of their normal operation.
+
+ The purpose of this directive is to meet the stated requirements of
+ certain users and service authors who are concerned about accidental
+ releases of information via unanticipated accesses to cache data
+ structures. While the use of this directive may improve privacy in
+ some cases, we caution that it is NOT in any way a reliable or
+ sufficient mechanism for ensuring privacy. In particular, malicious
+ or compromised caches may not recognize or obey this directive; and
+ communications networks may be vulnerable to eavesdropping.
+
+14.9.3 Modifications of the Basic Expiration Mechanism
+
+ The expiration time of an entity may be specified by the origin
+ server using the Expires header (see section 14.21). Alternatively,
+ it may be specified using the max-age directive in a response.
+
+ If a response includes both an Expires header and a max-age
+ directive, the max-age directive overrides the Expires header, even
+ if the Expires header is more restrictive. This rule allows an origin
+ server to provide, for a given response, a longer expiration time to
+ an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This may be
+ useful if certain HTTP/1.0 caches improperly calculate ages or
+ expiration times, perhaps due to desynchronized clocks.
+
+ Note: most older caches, not compliant with this specification, do
+ not implement any Cache-Control directives. An origin server
+ wishing to use a Cache-Control directive that restricts, but does
+ not prevent, caching by an HTTP/1.1-compliant cache may exploit the
+ requirement that the max-age directive overrides the Expires
+ header, and the fact that non-HTTP/1.1-compliant caches do not
+ observe the max-age directive.
+
+ Other directives allow an user agent to modify the basic expiration
+ mechanism. These directives may be specified on a request:
+
+ max-age
+ Indicates that the client is willing to accept a response whose age
+ is no greater than the specified time in seconds. Unless max-stale
+ directive is also included, the client is not willing to accept a
+ stale response.
+
+ min-fresh
+ Indicates that the client is willing to accept a response whose
+ freshness lifetime is no less than its current age plus the
+
+
+
+Fielding, et. al. Standards Track [Page 104]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ specified time in seconds. That is, the client wants a response
+ that will still be fresh for at least the specified number of
+ seconds.
+
+ max-stale
+ Indicates that the client is willing to accept a response that has
+ exceeded its expiration time. If max-stale is assigned a value,
+ then the client is willing to accept a response that has exceeded
+ its expiration time by no more than the specified number of
+ seconds. If no value is assigned to max-stale, then the client is
+ willing to accept a stale response of any age.
+
+ If a cache returns a stale response, either because of a max-stale
+ directive on a request, or because the cache is configured to
+ override the expiration time of a response, the cache MUST attach a
+ Warning header to the stale response, using Warning 10 (Response is
+ stale).
+
+14.9.4 Cache Revalidation and Reload Controls
+
+ Sometimes an user agent may want or need to insist that a cache
+ revalidate its cache entry with the origin server (and not just with
+ the next cache along the path to the origin server), or to reload its
+ cache entry from the origin server. End-to-end revalidation may be
+ necessary if either the cache or the origin server has overestimated
+ the expiration time of the cached response. End-to-end reload may be
+ necessary if the cache entry has become corrupted for some reason.
+
+ End-to-end revalidation may be requested either when the client does
+ not have its own local cached copy, in which case we call it
+ "unspecified end-to-end revalidation", or when the client does have a
+ local cached copy, in which case we call it "specific end-to-end
+ revalidation."
+
+ The client can specify these three kinds of action using Cache-
+ Control request directives:
+
+ End-to-end reload
+ The request includes a "no-cache" Cache-Control directive or, for
+ compatibility with HTTP/1.0 clients, "Pragma: no-cache". No field
+ names may be included with the no-cache directive in a request. The
+ server MUST NOT use a cached copy when responding to such a
+ request.
+
+ Specific end-to-end revalidation
+ The request includes a "max-age=0" Cache-Control directive, which
+ forces each cache along the path to the origin server to revalidate
+ its own entry, if any, with the next cache or server. The initial
+
+
+
+Fielding, et. al. Standards Track [Page 105]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ request includes a cache-validating conditional with the client's
+ current validator.
+
+ Unspecified end-to-end revalidation
+ The request includes "max-age=0" Cache-Control directive, which
+ forces each cache along the path to the origin server to revalidate
+ its own entry, if any, with the next cache or server. The initial
+ request does not include a cache-validating conditional; the first
+ cache along the path (if any) that holds a cache entry for this
+ resource includes a cache-validating conditional with its current
+ validator.
+
+ When an intermediate cache is forced, by means of a max-age=0
+ directive, to revalidate its own cache entry, and the client has
+ supplied its own validator in the request, the supplied validator may
+ differ from the validator currently stored with the cache entry. In
+ this case, the cache may use either validator in making its own
+ request without affecting semantic transparency.
+
+ However, the choice of validator may affect performance. The best
+ approach is for the intermediate cache to use its own validator when
+ making its request. If the server replies with 304 (Not Modified),
+ then the cache should return its now validated copy to the client
+ with a 200 (OK) response. If the server replies with a new entity and
+ cache validator, however, the intermediate cache should compare the
+ returned validator with the one provided in the client's request,
+ using the strong comparison function. If the client's validator is
+ equal to the origin server's, then the intermediate cache simply
+ returns 304 (Not Modified). Otherwise, it returns the new entity with
+ a 200 (OK) response.
+
+ If a request includes the no-cache directive, it should not include
+ min-fresh, max-stale, or max-age.
+
+ In some cases, such as times of extremely poor network connectivity,
+ a client may want a cache to return only those responses that it
+ currently has stored, and not to reload or revalidate with the origin
+ server. To do this, the client may include the only-if-cached
+ directive in a request. If it receives this directive, a cache SHOULD
+ either respond using a cached entry that is consistent with the other
+ constraints of the request, or respond with a 504 (Gateway Timeout)
+ status. However, if a group of caches is being operated as a unified
+ system with good internal connectivity, such a request MAY be
+ forwarded within that group of caches.
+
+ Because a cache may be configured to ignore a server's specified
+ expiration time, and because a client request may include a max-stale
+ directive (which has a similar effect), the protocol also includes a
+
+
+
+Fielding, et. al. Standards Track [Page 106]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ mechanism for the origin server to require revalidation of a cache
+ entry on any subsequent use. When the must-revalidate directive is
+ present in a response received by a cache, that cache MUST NOT use
+ the entry after it becomes stale to respond to a subsequent request
+ without first revalidating it with the origin server. (I.e., the
+ cache must do an end-to-end revalidation every time, if, based solely
+ on the origin server's Expires or max-age value, the cached response
+ is stale.)
+
+ The must-revalidate directive is necessary to support reliable
+ operation for certain protocol features. In all circumstances an
+ HTTP/1.1 cache MUST obey the must-revalidate directive; in
+ particular, if the cache cannot reach the origin server for any
+ reason, it MUST generate a 504 (Gateway Timeout) response.
+
+ Servers should send the must-revalidate directive if and only if
+ failure to revalidate a request on the entity could result in
+ incorrect operation, such as a silently unexecuted financial
+ transaction. Recipients MUST NOT take any automated action that
+ violates this directive, and MUST NOT automatically provide an
+ unvalidated copy of the entity if revalidation fails.
+
+ Although this is not recommended, user agents operating under severe
+ connectivity constraints may violate this directive but, if so, MUST
+ explicitly warn the user that an unvalidated response has been
+ provided. The warning MUST be provided on each unvalidated access,
+ and SHOULD require explicit user confirmation.
+
+ The proxy-revalidate directive has the same meaning as the must-
+ revalidate directive, except that it does not apply to non-shared
+ user agent caches. It can be used on a response to an authenticated
+ request to permit the user's cache to store and later return the
+ response without needing to revalidate it (since it has already been
+ authenticated once by that user), while still requiring proxies that
+ service many users to revalidate each time (in order to make sure
+ that each user has been authenticated). Note that such authenticated
+ responses also need the public cache control directive in order to
+ allow them to be cached at all.
+
+14.9.5 No-Transform Directive
+
+ Implementers of intermediate caches (proxies) have found it useful to
+ convert the media type of certain entity bodies. A proxy might, for
+ example, convert between image formats in order to save cache space
+ or to reduce the amount of traffic on a slow link. HTTP has to date
+ been silent on these transformations.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 107]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Serious operational problems have already occurred, however, when
+ these transformations have been applied to entity bodies intended for
+ certain kinds of applications. For example, applications for medical
+ imaging, scientific data analysis and those using end-to-end
+ authentication, all depend on receiving an entity body that is bit
+ for bit identical to the original entity-body.
+
+ Therefore, if a response includes the no-transform directive, an
+ intermediate cache or proxy MUST NOT change those headers that are
+ listed in section 13.5.2 as being subject to the no-transform
+ directive. This implies that the cache or proxy must not change any
+ aspect of the entity-body that is specified by these headers.
+
+14.9.6 Cache Control Extensions
+
+ The Cache-Control header field can be extended through the use of one
+ or more cache-extension tokens, each with an optional assigned value.
+ Informational extensions (those which do not require a change in
+ cache behavior) may be added without changing the semantics of other
+ directives. Behavioral extensions are designed to work by acting as
+ modifiers to the existing base of cache directives. Both the new
+ directive and the standard directive are supplied, such that
+ applications which do not understand the new directive will default
+ to the behavior specified by the standard directive, and those that
+ understand the new directive will recognize it as modifying the
+ requirements associated with the standard directive. In this way,
+ extensions to the Cache-Control directives can be made without
+ requiring changes to the base protocol.
+
+ This extension mechanism depends on a HTTP cache obeying all of the
+ cache-control directives defined for its native HTTP-version, obeying
+ certain extensions, and ignoring all directives that it does not
+ understand.
+
+ For example, consider a hypothetical new response directive called
+ "community" which acts as a modifier to the "private" directive. We
+ define this new directive to mean that, in addition to any non-shared
+ cache, any cache which is shared only by members of the community
+ named within its value may cache the response. An origin server
+ wishing to allow the "UCI" community to use an otherwise private
+ response in their shared cache(s) may do so by including
+
+ Cache-Control: private, community="UCI"
+
+ A cache seeing this header field will act correctly even if the cache
+ does not understand the "community" cache-extension, since it will
+ also see and understand the "private" directive and thus default to
+ the safe behavior.
+
+
+
+Fielding, et. al. Standards Track [Page 108]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Unrecognized cache-directives MUST be ignored; it is assumed that any
+ cache-directive likely to be unrecognized by an HTTP/1.1 cache will
+ be combined with standard directives (or the response's default
+ cachability) such that the cache behavior will remain minimally
+ correct even if the cache does not understand the extension(s).
+
+14.10 Connection
+
+ The Connection general-header field allows the sender to specify
+ options that are desired for that particular connection and MUST NOT
+ be communicated by proxies over further connections.
+
+ The Connection header has the following grammar:
+
+ Connection-header = "Connection" ":" 1#(connection-token)
+ connection-token = token
+
+ HTTP/1.1 proxies MUST parse the Connection header field before a
+ message is forwarded and, for each connection-token in this field,
+ remove any header field(s) from the message with the same name as the
+ connection-token. Connection options are signaled by the presence of
+ a connection-token in the Connection header field, not by any
+ corresponding additional header field(s), since the additional header
+ field may not be sent if there are no parameters associated with that
+ connection option. HTTP/1.1 defines the "close" connection option
+ for the sender to signal that the connection will be closed after
+ completion of the response. For example,
+
+ Connection: close
+
+ in either the request or the response header fields indicates that
+ the connection should not be considered `persistent' (section 8.1)
+ after the current request/response is complete.
+
+ HTTP/1.1 applications that do not support persistent connections MUST
+ include the "close" connection option in every message.
+
+14.11 Content-Base
+
+ The Content-Base entity-header field may be used to specify the base
+ URI for resolving relative URLs within the entity. This header field
+ is described as Base in RFC 1808, which is expected to be revised.
+
+ Content-Base = "Content-Base" ":" absoluteURI
+
+ If no Content-Base field is present, the base URI of an entity is
+ defined either by its Content-Location (if that Content-Location URI
+ is an absolute URI) or the URI used to initiate the request, in that
+
+
+
+Fielding, et. al. Standards Track [Page 109]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ order of precedence. Note, however, that the base URI of the contents
+ within the entity-body may be redefined within that entity-body.
+
+14.12 Content-Encoding
+
+ The Content-Encoding entity-header field is used as a modifier to the
+ media-type. When present, its value indicates what additional content
+ codings have been applied to the entity-body, and thus what decoding
+ mechanisms MUST be applied in order to obtain the media-type
+ referenced by the Content-Type header field. Content-Encoding is
+ primarily used to allow a document to be compressed without losing
+ the identity of its underlying media type.
+
+ Content-Encoding = "Content-Encoding" ":" 1#content-coding
+
+ Content codings are defined in section 3.5. An example of its use is
+
+ Content-Encoding: gzip
+
+ The Content-Encoding is a characteristic of the entity identified by
+ the Request-URI. Typically, the entity-body is stored with this
+ encoding and is only decoded before rendering or analogous usage.
+
+ If multiple encodings have been applied to an entity, the content
+ codings MUST be listed in the order in which they were applied.
+
+ Additional information about the encoding parameters MAY be provided
+ by other entity-header fields not defined by this specification.
+
+14.13 Content-Language
+
+ The Content-Language entity-header field describes the natural
+ language(s) of the intended audience for the enclosed entity. Note
+ that this may not be equivalent to all the languages used within the
+ entity-body.
+
+ Content-Language = "Content-Language" ":" 1#language-tag
+
+ Language tags are defined in section 3.10. The primary purpose of
+ Content-Language is to allow a user to identify and differentiate
+ entities according to the user's own preferred language. Thus, if the
+ body content is intended only for a Danish-literate audience, the
+ appropriate field is
+
+ Content-Language: da
+
+ If no Content-Language is specified, the default is that the content
+ is intended for all language audiences. This may mean that the sender
+
+
+
+Fielding, et. al. Standards Track [Page 110]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ does not consider it to be specific to any natural language, or that
+ the sender does not know for which language it is intended.
+
+ Multiple languages MAY be listed for content that is intended for
+ multiple audiences. For example, a rendition of the "Treaty of
+ Waitangi," presented simultaneously in the original Maori and English
+ versions, would call for
+
+ Content-Language: mi, en
+
+ However, just because multiple languages are present within an entity
+ does not mean that it is intended for multiple linguistic audiences.
+ An example would be a beginner's language primer, such as "A First
+ Lesson in Latin," which is clearly intended to be used by an
+ English-literate audience. In this case, the Content-Language should
+ only include "en".
+
+ Content-Language may be applied to any media type -- it is not
+ limited to textual documents.
+
+14.14 Content-Length
+
+ The Content-Length entity-header field indicates the size of the
+ message-body, in decimal number of octets, sent to the recipient or,
+ in the case of the HEAD method, the size of the entity-body that
+ would have been sent had the request been a GET.
+
+ Content-Length = "Content-Length" ":" 1*DIGIT
+
+ An example is
+
+ Content-Length: 3495
+
+ Applications SHOULD use this field to indicate the size of the
+ message-body to be transferred, regardless of the media type of the
+ entity. It must be possible for the recipient to reliably determine
+ the end of HTTP/1.1 requests containing an entity-body, e.g., because
+ the request has a valid Content-Length field, uses Transfer-Encoding:
+ chunked or a multipart body.
+
+ Any Content-Length greater than or equal to zero is a valid value.
+ Section 4.4 describes how to determine the length of a message-body
+ if a Content-Length is not given.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 111]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Note: The meaning of this field is significantly different from the
+ corresponding definition in MIME, where it is an optional field
+ used within the "message/external-body" content-type. In HTTP, it
+ SHOULD be sent whenever the message's length can be determined
+ prior to being transferred.
+
+14.15 Content-Location
+
+ The Content-Location entity-header field may be used to supply the
+ resource location for the entity enclosed in the message. In the case
+ where a resource has multiple entities associated with it, and those
+ entities actually have separate locations by which they might be
+ individually accessed, the server should provide a Content-Location
+ for the particular variant which is returned. In addition, a server
+ SHOULD provide a Content-Location for the resource corresponding to
+ the response entity.
+
+ Content-Location = "Content-Location" ":"
+ ( absoluteURI | relativeURI )
+
+ If no Content-Base header field is present, the value of Content-
+ Location also defines the base URL for the entity (see section
+ 14.11).
+
+ The Content-Location value is not a replacement for the original
+ requested URI; it is only a statement of the location of the resource
+ corresponding to this particular entity at the time of the request.
+ Future requests MAY use the Content-Location URI if the desire is to
+ identify the source of that particular entity.
+
+ A cache cannot assume that an entity with a Content-Location
+ different from the URI used to retrieve it can be used to respond to
+ later requests on that Content-Location URI. However, the Content-
+ Location can be used to differentiate between multiple entities
+ retrieved from a single requested resource, as described in section
+ 13.6.
+
+ If the Content-Location is a relative URI, the URI is interpreted
+ relative to any Content-Base URI provided in the response. If no
+ Content-Base is provided, the relative URI is interpreted relative to
+ the Request-URI.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 112]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.16 Content-MD5
+
+ The Content-MD5 entity-header field, as defined in RFC 1864 [23], is
+ an MD5 digest of the entity-body for the purpose of providing an
+ end-to-end message integrity check (MIC) of the entity-body. (Note: a
+ MIC is good for detecting accidental modification of the entity-body
+ in transit, but is not proof against malicious attacks.)
+
+ Content-MD5 = "Content-MD5" ":" md5-digest
+
+ md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
+
+ The Content-MD5 header field may be generated by an origin server to
+ function as an integrity check of the entity-body. Only origin
+ servers may generate the Content-MD5 header field; proxies and
+ gateways MUST NOT generate it, as this would defeat its value as an
+ end-to-end integrity check. Any recipient of the entity-body,
+ including gateways and proxies, MAY check that the digest value in
+ this header field matches that of the entity-body as received.
+
+ The MD5 digest is computed based on the content of the entity-body,
+ including any Content-Encoding that has been applied, but not
+ including any Transfer-Encoding that may have been applied to the
+ message-body. If the message is received with a Transfer-Encoding,
+ that encoding must be removed prior to checking the Content-MD5 value
+ against the received entity.
+
+ This has the result that the digest is computed on the octets of the
+ entity-body exactly as, and in the order that, they would be sent if
+ no Transfer-Encoding were being applied.
+
+ HTTP extends RFC 1864 to permit the digest to be computed for MIME
+ composite media-types (e.g., multipart/* and message/rfc822), but
+ this does not change how the digest is computed as defined in the
+ preceding paragraph.
+
+ Note: There are several consequences of this. The entity-body for
+ composite types may contain many body-parts, each with its own MIME
+ and HTTP headers (including Content-MD5, Content-Transfer-Encoding,
+ and Content-Encoding headers). If a body-part has a Content-
+ Transfer-Encoding or Content-Encoding header, it is assumed that
+ the content of the body-part has had the encoding applied, and the
+ body-part is included in the Content-MD5 digest as is -- i.e.,
+ after the application. The Transfer-Encoding header field is not
+ allowed within body-parts.
+
+ Note: while the definition of Content-MD5 is exactly the same for
+ HTTP as in RFC 1864 for MIME entity-bodies, there are several ways
+
+
+
+Fielding, et. al. Standards Track [Page 113]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ in which the application of Content-MD5 to HTTP entity-bodies
+ differs from its application to MIME entity-bodies. One is that
+ HTTP, unlike MIME, does not use Content-Transfer-Encoding, and does
+ use Transfer-Encoding and Content-Encoding. Another is that HTTP
+ more frequently uses binary content types than MIME, so it is worth
+ noting that, in such cases, the byte order used to compute the
+ digest is the transmission byte order defined for the type. Lastly,
+ HTTP allows transmission of text types with any of several line
+ break conventions and not just the canonical form using CRLF.
+ Conversion of all line breaks to CRLF should not be done before
+ computing or checking the digest: the line break convention used in
+ the text actually transmitted should be left unaltered when
+ computing the digest.
+
+14.17 Content-Range
+
+ The Content-Range entity-header is sent with a partial entity-body to
+ specify where in the full entity-body the partial body should be
+ inserted. It also indicates the total size of the full entity-body.
+ When a server returns a partial response to a client, it must
+ describe both the extent of the range covered by the response, and
+ the length of the entire entity-body.
+
+ Content-Range = "Content-Range" ":" content-range-spec
+
+ content-range-spec = byte-content-range-spec
+
+ byte-content-range-spec = bytes-unit SP first-byte-pos "-"
+ last-byte-pos "/" entity-length
+
+ entity-length = 1*DIGIT
+
+ Unlike byte-ranges-specifier values, a byte-content-range-spec may
+ only specify one range, and must contain absolute byte positions for
+ both the first and last byte of the range.
+
+ A byte-content-range-spec whose last-byte-pos value is less than its
+ first-byte-pos value, or whose entity-length value is less than or
+ equal to its last-byte-pos value, is invalid. The recipient of an
+ invalid byte-content-range-spec MUST ignore it and any content
+ transferred along with it.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 114]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Examples of byte-content-range-spec values, assuming that the entity
+ contains a total of 1234 bytes:
+
+ o The first 500 bytes:
+
+ bytes 0-499/1234
+
+ o The second 500 bytes:
+
+ bytes 500-999/1234
+
+ o All except for the first 500 bytes:
+
+ bytes 500-1233/1234
+
+ o The last 500 bytes:
+
+ bytes 734-1233/1234
+
+ When an HTTP message includes the content of a single range (for
+ example, a response to a request for a single range, or to a request
+ for a set of ranges that overlap without any holes), this content is
+ transmitted with a Content-Range header, and a Content-Length header
+ showing the number of bytes actually transferred. For example,
+
+ HTTP/1.1 206 Partial content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-Range: bytes 21010-47021/47022
+ Content-Length: 26012
+ Content-Type: image/gif
+
+ When an HTTP message includes the content of multiple ranges (for
+ example, a response to a request for multiple non-overlapping
+ ranges), these are transmitted as a multipart MIME message. The
+ multipart MIME content-type used for this purpose is defined in this
+ specification to be "multipart/byteranges". See appendix 19.2 for its
+ definition.
+
+ A client that cannot decode a MIME multipart/byteranges message
+ should not ask for multiple byte-ranges in a single request.
+
+ When a client requests multiple byte-ranges in one request, the
+ server SHOULD return them in the order that they appeared in the
+ request.
+
+ If the server ignores a byte-range-spec because it is invalid, the
+ server should treat the request as if the invalid Range header field
+
+
+
+Fielding, et. al. Standards Track [Page 115]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ did not exist. (Normally, this means return a 200 response containing
+ the full entity). The reason is that the only time a client will make
+ such an invalid request is when the entity is smaller than the entity
+ retrieved by a prior request.
+
+14.18 Content-Type
+
+ The Content-Type entity-header field indicates the media type of the
+ entity-body sent to the recipient or, in the case of the HEAD method,
+ the media type that would have been sent had the request been a GET.
+
+ Content-Type = "Content-Type" ":" media-type
+ Media types are defined in section 3.7. An example of the field is
+
+ Content-Type: text/html; charset=ISO-8859-4
+
+ Further discussion of methods for identifying the media type of an
+ entity is provided in section 7.2.1.
+
+14.19 Date
+
+ The Date general-header field represents the date and time at which
+ the message was originated, having the same semantics as orig-date in
+ RFC 822. The field value is an HTTP-date, as described in section
+ 3.3.1.
+
+ Date = "Date" ":" HTTP-date
+
+ An example is
+
+ Date: Tue, 15 Nov 1994 08:12:31 GMT
+
+ If a message is received via direct connection with the user agent
+ (in the case of requests) or the origin server (in the case of
+ responses), then the date can be assumed to be the current date at
+ the receiving end. However, since the date--as it is believed by the
+ origin--is important for evaluating cached responses, origin servers
+ MUST include a Date header field in all responses. Clients SHOULD
+ only send a Date header field in messages that include an entity-
+ body, as in the case of the PUT and POST requests, and even then it
+ is optional. A received message which does not have a Date header
+ field SHOULD be assigned one by the recipient if the message will be
+ cached by that recipient or gatewayed via a protocol which requires a
+ Date.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 116]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ In theory, the date SHOULD represent the moment just before the
+ entity is generated. In practice, the date can be generated at any
+ time during the message origination without affecting its semantic
+ value.
+
+ The format of the Date is an absolute date and time as defined by
+ HTTP-date in section 3.3; it MUST be sent in RFC1123 [8]-date format.
+
+14.20 ETag
+
+ The ETag entity-header field defines the entity tag for the
+ associated entity. The headers used with entity tags are described in
+ sections 14.20, 14.25, 14.26 and 14.43. The entity tag may be used
+ for comparison with other entities from the same resource (see
+ section 13.3.2).
+
+ ETag = "ETag" ":" entity-tag
+
+ Examples:
+
+ ETag: "xyzzy"
+ ETag: W/"xyzzy"
+ ETag: ""
+
+14.21 Expires
+
+ The Expires entity-header field gives the date/time after which the
+ response should be considered stale. A stale cache entry may not
+ normally be returned by a cache (either a proxy cache or an user
+ agent cache) unless it is first validated with the origin server (or
+ with an intermediate cache that has a fresh copy of the entity). See
+ section 13.2 for further discussion of the expiration model.
+
+ The presence of an Expires field does not imply that the original
+ resource will change or cease to exist at, before, or after that
+ time.
+
+ The format is an absolute date and time as defined by HTTP-date in
+ section 3.3; it MUST be in RFC1123-date format:
+
+ Expires = "Expires" ":" HTTP-date
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 117]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ An example of its use is
+
+ Expires: Thu, 01 Dec 1994 16:00:00 GMT
+
+ Note: if a response includes a Cache-Control field with the max-age
+ directive, that directive overrides the Expires field.
+
+ HTTP/1.1 clients and caches MUST treat other invalid date formats,
+ especially including the value "0", as in the past (i.e., "already
+ expired").
+
+ To mark a response as "already expired," an origin server should use
+ an Expires date that is equal to the Date header value. (See the
+ rules for expiration calculations in section 13.2.4.)
+
+ To mark a response as "never expires," an origin server should use an
+ Expires date approximately one year from the time the response is
+ sent. HTTP/1.1 servers should not send Expires dates more than one
+ year in the future.
+
+ The presence of an Expires header field with a date value of some
+ time in the future on an response that otherwise would by default be
+ non-cacheable indicates that the response is cachable, unless
+ indicated otherwise by a Cache-Control header field (section 14.9).
+
+14.22 From
+
+ The From request-header field, if given, SHOULD contain an Internet
+ e-mail address for the human user who controls the requesting user
+ agent. The address SHOULD be machine-usable, as defined by mailbox
+ in RFC 822 (as updated by RFC 1123 ):
+
+ From = "From" ":" mailbox
+
+ An example is:
+
+
+ This header field MAY be used for logging purposes and as a means for
+ identifying the source of invalid or unwanted requests. It SHOULD NOT
+ be used as an insecure form of access protection. The interpretation
+ of this field is that the request is being performed on behalf of the
+ person given, who accepts responsibility for the method performed. In
+ particular, robot agents SHOULD include this header so that the
+ person responsible for running the robot can be contacted if problems
+ occur on the receiving end.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 118]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The Internet e-mail address in this field MAY be separate from the
+ Internet host which issued the request. For example, when a request
+ is passed through a proxy the original issuer's address SHOULD be
+ used.
+
+ Note: The client SHOULD not send the From header field without the
+ user's approval, as it may conflict with the user's privacy
+ interests or their site's security policy. It is strongly
+ recommended that the user be able to disable, enable, and modify
+ the value of this field at any time prior to a request.
+
+14.23 Host
+
+ The Host request-header field specifies the Internet host and port
+ number of the resource being requested, as obtained from the original
+ URL given by the user or referring resource (generally an HTTP URL,
+ as described in section 3.2.2). The Host field value MUST represent
+ the network location of the origin server or gateway given by the
+ original URL. This allows the origin server or gateway to
+ differentiate between internally-ambiguous URLs, such as the root "/"
+ URL of a server for multiple host names on a single IP address.
+
+ Host = "Host" ":" host [ ":" port ] ; Section 3.2.2
+
+ A "host" without any trailing port information implies the default
+ port for the service requested (e.g., "80" for an HTTP URL). For
+ example, a request on the origin server for
+ <http://www.w3.org/pub/WWW/> MUST include:
+
+ GET /pub/WWW/ HTTP/1.1
+ Host: www.w3.org
+
+ A client MUST include a Host header field in all HTTP/1.1 request
+ messages on the Internet (i.e., on any message corresponding to a
+ request for a URL which includes an Internet host address for the
+ service being requested). If the Host field is not already present,
+ an HTTP/1.1 proxy MUST add a Host field to the request message prior
+ to forwarding it on the Internet. All Internet-based HTTP/1.1 servers
+ MUST respond with a 400 status code to any HTTP/1.1 request message
+ which lacks a Host header field.
+
+ See sections 5.2 and 19.5.1 for other requirements relating to Host.
+
+14.24 If-Modified-Since
+
+ The If-Modified-Since request-header field is used with the GET
+ method to make it conditional: if the requested variant has not been
+ modified since the time specified in this field, an entity will not
+
+
+
+Fielding, et. al. Standards Track [Page 119]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ be returned from the server; instead, a 304 (not modified) response
+ will be returned without any message-body.
+
+ If-Modified-Since = "If-Modified-Since" ":" HTTP-date
+
+ An example of the field is:
+
+ If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ A GET method with an If-Modified-Since header and no Range header
+ requests that the identified entity be transferred only if it has
+ been modified since the date given by the If-Modified-Since header.
+ The algorithm for determining this includes the following cases:
+
+ a)If the request would normally result in anything other than a 200
+ (OK) status, or if the passed If-Modified-Since date is invalid, the
+ response is exactly the same as for a normal GET. A date which is
+ later than the server's current time is invalid.
+
+ b)If the variant has been modified since the If-Modified-Since date,
+ the response is exactly the same as for a normal GET.
+
+ c)If the variant has not been modified since a valid If-Modified-Since
+ date, the server MUST return a 304 (Not Modified) response.
+
+ The purpose of this feature is to allow efficient updates of cached
+ information with a minimum amount of transaction overhead.
+
+ Note that the Range request-header field modifies the meaning of
+ If-Modified-Since; see section 14.36 for full details.
+
+ Note that If-Modified-Since times are interpreted by the server,
+ whose clock may not be synchronized with the client.
+
+ Note that if a client uses an arbitrary date in the If-Modified-Since
+ header instead of a date taken from the Last-Modified header for the
+ same request, the client should be aware of the fact that this date
+ is interpreted in the server's understanding of time. The client
+ should consider unsynchronized clocks and rounding problems due to
+ the different encodings of time between the client and server. This
+ includes the possibility of race conditions if the document has
+ changed between the time it was first requested and the If-Modified-
+ Since date of a subsequent request, and the possibility of clock-
+ skew-related problems if the If-Modified-Since date is derived from
+ the client's clock without correction to the server's clock.
+ Corrections for different time bases between client and server are at
+ best approximate due to network latency.
+
+
+
+
+Fielding, et. al. Standards Track [Page 120]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.25 If-Match
+
+ The If-Match request-header field is used with a method to make it
+ conditional. A client that has one or more entities previously
+ obtained from the resource can verify that one of those entities is
+ current by including a list of their associated entity tags in the
+ If-Match header field. The purpose of this feature is to allow
+ efficient updates of cached information with a minimum amount of
+ transaction overhead. It is also used, on updating requests, to
+ prevent inadvertent modification of the wrong version of a resource.
+ As a special case, the value "*" matches any current entity of the
+ resource.
+
+ If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-Match header) on that resource, or if "*" is given
+ and any current entity exists for that resource, then the server MAY
+ perform the requested method as if the If-Match header field did not
+ exist.
+
+ A server MUST use the strong comparison function (see section 3.11)
+ to compare the entity tags in If-Match.
+
+ If none of the entity tags match, or if "*" is given and no current
+ entity exists, the server MUST NOT perform the requested method, and
+ MUST return a 412 (Precondition Failed) response. This behavior is
+ most useful when the client wants to prevent an updating method, such
+ as PUT, from modifying a resource that has changed since the client
+ last retrieved it.
+
+ If the request would, without the If-Match header field, result in
+ anything other than a 2xx status, then the If-Match header MUST be
+ ignored.
+
+ The meaning of "If-Match: *" is that the method SHOULD be performed
+ if the representation selected by the origin server (or by a cache,
+ possibly using the Vary mechanism, see section 14.43) exists, and
+ MUST NOT be performed if the representation does not exist.
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 121]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ A request intended to update a resource (e.g., a PUT) MAY include an
+ If-Match header field to signal that the request method MUST NOT be
+ applied if the entity corresponding to the If-Match value (a single
+ entity tag) is no longer a representation of that resource. This
+ allows the user to indicate that they do not wish the request to be
+ successful if the resource has been changed without their knowledge.
+ Examples:
+
+ If-Match: "xyzzy"
+ If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-Match: *
+
+14.26 If-None-Match
+
+ The If-None-Match request-header field is used with a method to make
+ it conditional. A client that has one or more entities previously
+ obtained from the resource can verify that none of those entities is
+ current by including a list of their associated entity tags in the
+ If-None-Match header field. The purpose of this feature is to allow
+ efficient updates of cached information with a minimum amount of
+ transaction overhead. It is also used, on updating requests, to
+ prevent inadvertent modification of a resource which was not known to
+ exist.
+
+ As a special case, the value "*" matches any current entity of the
+ resource.
+
+ If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-None-Match header) on that resource, or if "*" is
+ given and any current entity exists for that resource, then the
+ server MUST NOT perform the requested method. Instead, if the request
+ method was GET or HEAD, the server SHOULD respond with a 304 (Not
+ Modified) response, including the cache-related entity-header fields
+ (particularly ETag) of one of the entities that matched. For all
+ other request methods, the server MUST respond with a status of 412
+ (Precondition Failed).
+
+ See section 13.3.3 for rules on how to determine if two entity tags
+ match. The weak comparison function can only be used with GET or HEAD
+ requests.
+
+ If none of the entity tags match, or if "*" is given and no current
+ entity exists, then the server MAY perform the requested method as if
+ the If-None-Match header field did not exist.
+
+
+
+
+Fielding, et. al. Standards Track [Page 122]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If the request would, without the If-None-Match header field, result
+ in anything other than a 2xx status, then the If-None-Match header
+ MUST be ignored.
+
+ The meaning of "If-None-Match: *" is that the method MUST NOT be
+ performed if the representation selected by the origin server (or by
+ a cache, possibly using the Vary mechanism, see section 14.43)
+ exists, and SHOULD be performed if the representation does not exist.
+ This feature may be useful in preventing races between PUT
+ operations.
+
+ Examples:
+
+ If-None-Match: "xyzzy"
+ If-None-Match: W/"xyzzy"
+ If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+ If-None-Match: *
+
+14.27 If-Range
+
+ If a client has a partial copy of an entity in its cache, and wishes
+ to have an up-to-date copy of the entire entity in its cache, it
+ could use the Range request-header with a conditional GET (using
+ either or both of If-Unmodified-Since and If-Match.) However, if the
+ condition fails because the entity has been modified, the client
+ would then have to make a second request to obtain the entire current
+ entity-body.
+
+ The If-Range header allows a client to "short-circuit" the second
+ request. Informally, its meaning is `if the entity is unchanged, send
+ me the part(s) that I am missing; otherwise, send me the entire new
+ entity.'
+
+ If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
+
+ If the client has no entity tag for an entity, but does have a Last-
+ Modified date, it may use that date in a If-Range header. (The server
+ can distinguish between a valid HTTP-date and any form of entity-tag
+ by examining no more than two characters.) The If-Range header should
+ only be used together with a Range header, and must be ignored if the
+ request does not include a Range header, or if the server does not
+ support the sub-range operation.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 123]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If the entity tag given in the If-Range header matches the current
+ entity tag for the entity, then the server should provide the
+ specified sub-range of the entity using a 206 (Partial content)
+ response. If the entity tag does not match, then the server should
+ return the entire entity using a 200 (OK) response.
+
+14.28 If-Unmodified-Since
+
+ The If-Unmodified-Since request-header field is used with a method to
+ make it conditional. If the requested resource has not been modified
+ since the time specified in this field, the server should perform the
+ requested operation as if the If-Unmodified-Since header were not
+ present.
+
+ If the requested variant has been modified since the specified time,
+ the server MUST NOT perform the requested operation, and MUST return
+ a 412 (Precondition Failed).
+
+ If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
+
+ An example of the field is:
+
+ If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ If the request normally (i.e., without the If-Unmodified-Since
+ header) would result in anything other than a 2xx status, the If-
+ Unmodified-Since header should be ignored.
+
+ If the specified date is invalid, the header is ignored.
+
+14.29 Last-Modified
+
+ The Last-Modified entity-header field indicates the date and time at
+ which the origin server believes the variant was last modified.
+
+ Last-Modified = "Last-Modified" ":" HTTP-date
+
+ An example of its use is
+
+ Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
+
+ The exact meaning of this header field depends on the implementation
+ of the origin server and the nature of the original resource. For
+ files, it may be just the file system last-modified time. For
+ entities with dynamically included parts, it may be the most recent
+ of the set of last-modify times for its component parts. For database
+ gateways, it may be the last-update time stamp of the record. For
+ virtual objects, it may be the last time the internal state changed.
+
+
+
+Fielding, et. al. Standards Track [Page 124]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ An origin server MUST NOT send a Last-Modified date which is later
+ than the server's time of message origination. In such cases, where
+ the resource's last modification would indicate some time in the
+ future, the server MUST replace that date with the message
+ origination date.
+
+ An origin server should obtain the Last-Modified value of the entity
+ as close as possible to the time that it generates the Date value of
+ its response. This allows a recipient to make an accurate assessment
+ of the entity's modification time, especially if the entity changes
+ near the time that the response is generated.
+
+ HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
+
+14.30 Location
+
+ The Location response-header field is used to redirect the recipient
+ to a location other than the Request-URI for completion of the
+ request or identification of a new resource. For 201 (Created)
+ responses, the Location is that of the new resource which was created
+ by the request. For 3xx responses, the location SHOULD indicate the
+ server's preferred URL for automatic redirection to the resource. The
+ field value consists of a single absolute URL.
+
+ Location = "Location" ":" absoluteURI
+
+ An example is
+
+ Location: http://www.w3.org/pub/WWW/People.html
+
+ Note: The Content-Location header field (section 14.15) differs
+ from Location in that the Content-Location identifies the original
+ location of the entity enclosed in the request. It is therefore
+ possible for a response to contain header fields for both Location
+ and Content-Location. Also see section 13.10 for cache requirements
+ of some methods.
+
+14.31 Max-Forwards
+
+ The Max-Forwards request-header field may be used with the TRACE
+ method (section 14.31) to limit the number of proxies or gateways
+ that can forward the request to the next inbound server. This can be
+ useful when the client is attempting to trace a request chain which
+ appears to be failing or looping in mid-chain.
+
+ Max-Forwards = "Max-Forwards" ":" 1*DIGIT
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 125]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The Max-Forwards value is a decimal integer indicating the remaining
+ number of times this request message may be forwarded.
+
+ Each proxy or gateway recipient of a TRACE request containing a Max-
+ Forwards header field SHOULD check and update its value prior to
+ forwarding the request. If the received value is zero (0), the
+ recipient SHOULD NOT forward the request; instead, it SHOULD respond
+ as the final recipient with a 200 (OK) response containing the
+ received request message as the response entity-body (as described in
+ section 9.8). If the received Max-Forwards value is greater than
+ zero, then the forwarded message SHOULD contain an updated Max-
+ Forwards field with a value decremented by one (1).
+
+ The Max-Forwards header field SHOULD be ignored for all other methods
+ defined by this specification and for any extension methods for which
+ it is not explicitly referred to as part of that method definition.
+
+14.32 Pragma
+
+ The Pragma general-header field is used to include implementation-
+ specific directives that may apply to any recipient along the
+ request/response chain. All pragma directives specify optional
+ behavior from the viewpoint of the protocol; however, some systems
+ MAY require that behavior be consistent with the directives.
+
+ Pragma = "Pragma" ":" 1#pragma-directive
+
+ pragma-directive = "no-cache" | extension-pragma
+ extension-pragma = token [ "=" ( token | quoted-string ) ]
+
+ When the no-cache directive is present in a request message, an
+ application SHOULD forward the request toward the origin server even
+ if it has a cached copy of what is being requested. This pragma
+ directive has the same semantics as the no-cache cache-directive (see
+ section 14.9) and is defined here for backwards compatibility with
+ HTTP/1.0. Clients SHOULD include both header fields when a no-cache
+ request is sent to a server not known to be HTTP/1.1 compliant.
+
+ Pragma directives MUST be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives may be applicable to all recipients along the
+ request/response chain. It is not possible to specify a pragma for a
+ specific recipient; however, any pragma directive not relevant to a
+ recipient SHOULD be ignored by that recipient.
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 126]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ HTTP/1.1 clients SHOULD NOT send the Pragma request-header. HTTP/1.1
+ caches SHOULD treat "Pragma: no-cache" as if the client had sent
+ "Cache-Control: no-cache". No new Pragma directives will be defined
+ in HTTP.
+
+14.33 Proxy-Authenticate
+
+ The Proxy-Authenticate response-header field MUST be included as part
+ of a 407 (Proxy Authentication Required) response. The field value
+ consists of a challenge that indicates the authentication scheme and
+ parameters applicable to the proxy for this Request-URI.
+
+ Proxy-Authenticate = "Proxy-Authenticate" ":" challenge
+
+ The HTTP access authentication process is described in section 11.
+ Unlike WWW-Authenticate, the Proxy-Authenticate header field applies
+ only to the current connection and SHOULD NOT be passed on to
+ downstream clients. However, an intermediate proxy may need to obtain
+ its own credentials by requesting them from the downstream client,
+ which in some circumstances will appear as if the proxy is forwarding
+ the Proxy-Authenticate header field.
+
+14.34 Proxy-Authorization
+
+ The Proxy-Authorization request-header field allows the client to
+ identify itself (or its user) to a proxy which requires
+ authentication. The Proxy-Authorization field value consists of
+ credentials containing the authentication information of the user
+ agent for the proxy and/or realm of the resource being requested.
+
+ Proxy-Authorization = "Proxy-Authorization" ":" credentials
+
+ The HTTP access authentication process is described in section 11.
+ Unlike Authorization, the Proxy-Authorization header field applies
+ only to the next outbound proxy that demanded authentication using
+ the Proxy-Authenticate field. When multiple proxies are used in a
+ chain, the Proxy-Authorization header field is consumed by the first
+ outbound proxy that was expecting to receive credentials. A proxy MAY
+ relay the credentials from the client request to the next proxy if
+ that is the mechanism by which the proxies cooperatively authenticate
+ a given request.
+
+14.35 Public
+
+ The Public response-header field lists the set of methods supported
+ by the server. The purpose of this field is strictly to inform the
+ recipient of the capabilities of the server regarding unusual
+ methods. The methods listed may or may not be applicable to the
+
+
+
+Fielding, et. al. Standards Track [Page 127]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Request-URI; the Allow header field (section 14.7) MAY be used to
+ indicate methods allowed for a particular URI.
+
+ Public = "Public" ":" 1#method
+
+ Example of use:
+
+ Public: OPTIONS, MGET, MHEAD, GET, HEAD
+
+ This header field applies only to the server directly connected to
+ the client (i.e., the nearest neighbor in a chain of connections). If
+ the response passes through a proxy, the proxy MUST either remove the
+ Public header field or replace it with one applicable to its own
+ capabilities.
+
+14.36 Range
+
+14.36.1 Byte Ranges
+
+ Since all HTTP entities are represented in HTTP messages as sequences
+ of bytes, the concept of a byte range is meaningful for any HTTP
+ entity. (However, not all clients and servers need to support byte-
+ range operations.)
+
+ Byte range specifications in HTTP apply to the sequence of bytes in
+ the entity-body (not necessarily the same as the message-body).
+
+ A byte range operation may specify a single range of bytes, or a set
+ of ranges within a single entity.
+
+ ranges-specifier = byte-ranges-specifier
+
+ byte-ranges-specifier = bytes-unit "=" byte-range-set
+
+ byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec )
+
+ byte-range-spec = first-byte-pos "-" [last-byte-pos]
+
+ first-byte-pos = 1*DIGIT
+
+ last-byte-pos = 1*DIGIT
+
+ The first-byte-pos value in a byte-range-spec gives the byte-offset
+ of the first byte in a range. The last-byte-pos value gives the
+ byte-offset of the last byte in the range; that is, the byte
+ positions specified are inclusive. Byte offsets start at zero.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 128]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ If the last-byte-pos value is present, it must be greater than or
+ equal to the first-byte-pos in that byte-range-spec, or the byte-
+ range-spec is invalid. The recipient of an invalid byte-range-spec
+ must ignore it.
+
+ If the last-byte-pos value is absent, or if the value is greater than
+ or equal to the current length of the entity-body, last-byte-pos is
+ taken to be equal to one less than the current length of the entity-
+ body in bytes.
+
+ By its choice of last-byte-pos, a client can limit the number of
+ bytes retrieved without knowing the size of the entity.
+
+ suffix-byte-range-spec = "-" suffix-length
+
+ suffix-length = 1*DIGIT
+
+ A suffix-byte-range-spec is used to specify the suffix of the
+ entity-body, of a length given by the suffix-length value. (That is,
+ this form specifies the last N bytes of an entity-body.) If the
+ entity is shorter than the specified suffix-length, the entire
+ entity-body is used.
+
+ Examples of byte-ranges-specifier values (assuming an entity-body of
+ length 10000):
+
+ o The first 500 bytes (byte offsets 0-499, inclusive):
+
+ bytes=0-499
+
+ o The second 500 bytes (byte offsets 500-999, inclusive):
+
+ bytes=500-999
+
+ o The final 500 bytes (byte offsets 9500-9999, inclusive):
+
+ bytes=-500
+
+ o Or
+
+ bytes=9500-
+
+ o The first and last bytes only (bytes 0 and 9999):
+
+ bytes=0-0,-1
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 129]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ o Several legal but not canonical specifications of the second
+ 500 bytes (byte offsets 500-999, inclusive):
+
+ bytes=500-600,601-999
+
+ bytes=500-700,601-999
+
+14.36.2 Range Retrieval Requests
+
+ HTTP retrieval requests using conditional or unconditional GET
+ methods may request one or more sub-ranges of the entity, instead of
+ the entire entity, using the Range request header, which applies to
+ the entity returned as the result of the request:
+
+ Range = "Range" ":" ranges-specifier
+
+ A server MAY ignore the Range header. However, HTTP/1.1 origin
+ servers and intermediate caches SHOULD support byte ranges when
+ possible, since Range supports efficient recovery from partially
+ failed transfers, and supports efficient partial retrieval of large
+ entities.
+
+ If the server supports the Range header and the specified range or
+ ranges are appropriate for the entity:
+
+ o The presence of a Range header in an unconditional GET modifies
+ what is returned if the GET is otherwise successful. In other
+ words, the response carries a status code of 206 (Partial
+ Content) instead of 200 (OK).
+
+ o The presence of a Range header in a conditional GET (a request
+ using one or both of If-Modified-Since and If-None-Match, or
+ one or both of If-Unmodified-Since and If-Match) modifies what
+ is returned if the GET is otherwise successful and the condition
+ is true. It does not affect the 304 (Not Modified) response
+ returned if the conditional is false.
+
+ In some cases, it may be more appropriate to use the If-Range header
+ (see section 14.27) in addition to the Range header.
+
+ If a proxy that supports ranges receives a Range request, forwards
+ the request to an inbound server, and receives an entire entity in
+ reply, it SHOULD only return the requested range to its client. It
+ SHOULD store the entire received response in its cache, if that is
+ consistent with its cache allocation policies.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 130]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.37 Referer
+
+ The Referer[sic] request-header field allows the client to specify,
+ for the server's benefit, the address (URI) of the resource from
+ which the Request-URI was obtained (the "referrer", although the
+ header field is misspelled.) The Referer request-header allows a
+ server to generate lists of back-links to resources for interest,
+ logging, optimized caching, etc. It also allows obsolete or mistyped
+ links to be traced for maintenance. The Referer field MUST NOT be
+ sent if the Request-URI was obtained from a source that does not have
+ its own URI, such as input from the user keyboard.
+
+ Referer = "Referer" ":" ( absoluteURI | relativeURI )
+
+ Example:
+
+ Referer: http://www.w3.org/hypertext/DataSources/Overview.html
+
+ If the field value is a partial URI, it SHOULD be interpreted
+ relative to the Request-URI. The URI MUST NOT include a fragment.
+
+ Note: Because the source of a link may be private information or
+ may reveal an otherwise private information source, it is strongly
+ recommended that the user be able to select whether or not the
+ Referer field is sent. For example, a browser client could have a
+ toggle switch for browsing openly/anonymously, which would
+ respectively enable/disable the sending of Referer and From
+ information.
+
+14.38 Retry-After
+
+ The Retry-After response-header field can be used with a 503 (Service
+ Unavailable) response to indicate how long the service is expected to
+ be unavailable to the requesting client. The value of this field can
+ be either an HTTP-date or an integer number of seconds (in decimal)
+ after the time of the response.
+
+ Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds )
+
+ Two examples of its use are
+
+ Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
+ Retry-After: 120
+
+ In the latter example, the delay is 2 minutes.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 131]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.39 Server
+
+ The Server response-header field contains information about the
+ software used by the origin server to handle the request. The field
+ can contain multiple product tokens (section 3.8) and comments
+ identifying the server and any significant subproducts. The product
+ tokens are listed in order of their significance for identifying the
+ application.
+
+ Server = "Server" ":" 1*( product | comment )
+
+ Example:
+
+ Server: CERN/3.0 libwww/2.17
+
+ If the response is being forwarded through a proxy, the proxy
+ application MUST NOT modify the Server response-header. Instead, it
+ SHOULD include a Via field (as described in section 14.44).
+
+ Note: Revealing the specific software version of the server may
+ allow the server machine to become more vulnerable to attacks
+ against software that is known to contain security holes. Server
+ implementers are encouraged to make this field a configurable
+ option.
+
+14.40 Transfer-Encoding
+
+ The Transfer-Encoding general-header field indicates what (if any)
+ type of transformation has been applied to the message body in order
+ to safely transfer it between the sender and the recipient. This
+ differs from the Content-Encoding in that the transfer coding is a
+ property of the message, not of the entity.
+
+ Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-
+ coding
+
+ Transfer codings are defined in section 3.6. An example is:
+
+ Transfer-Encoding: chunked
+
+ Many older HTTP/1.0 applications do not understand the Transfer-
+ Encoding header.
+
+14.41 Upgrade
+
+ The Upgrade general-header allows the client to specify what
+ additional communication protocols it supports and would like to use
+ if the server finds it appropriate to switch protocols. The server
+
+
+
+Fielding, et. al. Standards Track [Page 132]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ MUST use the Upgrade header field within a 101 (Switching Protocols)
+ response to indicate which protocol(s) are being switched.
+
+ Upgrade = "Upgrade" ":" 1#product
+
+ For example,
+
+ Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
+
+ The Upgrade header field is intended to provide a simple mechanism
+ for transition from HTTP/1.1 to some other, incompatible protocol. It
+ does so by allowing the client to advertise its desire to use another
+ protocol, such as a later version of HTTP with a higher major version
+ number, even though the current request has been made using HTTP/1.1.
+ This eases the difficult transition between incompatible protocols by
+ allowing the client to initiate a request in the more commonly
+ supported protocol while indicating to the server that it would like
+ to use a "better" protocol if available (where "better" is determined
+ by the server, possibly according to the nature of the method and/or
+ resource being requested).
+
+ The Upgrade header field only applies to switching application-layer
+ protocols upon the existing transport-layer connection. Upgrade
+ cannot be used to insist on a protocol change; its acceptance and use
+ by the server is optional. The capabilities and nature of the
+ application-layer communication after the protocol change is entirely
+ dependent upon the new protocol chosen, although the first action
+ after changing the protocol MUST be a response to the initial HTTP
+ request containing the Upgrade header field.
+
+ The Upgrade header field only applies to the immediate connection.
+ Therefore, the upgrade keyword MUST be supplied within a Connection
+ header field (section 14.10) whenever Upgrade is present in an
+ HTTP/1.1 message.
+
+ The Upgrade header field cannot be used to indicate a switch to a
+ protocol on a different connection. For that purpose, it is more
+ appropriate to use a 301, 302, 303, or 305 redirection response.
+
+ This specification only defines the protocol name "HTTP" for use by
+ the family of Hypertext Transfer Protocols, as defined by the HTTP
+ version rules of section 3.1 and future updates to this
+ specification. Any token can be used as a protocol name; however, it
+ will only be useful if both the client and server associate the name
+ with the same protocol.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 133]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14.42 User-Agent
+
+ The User-Agent request-header field contains information about the
+ user agent originating the request. This is for statistical purposes,
+ the tracing of protocol violations, and automated recognition of user
+ agents for the sake of tailoring responses to avoid particular user
+ agent limitations. User agents SHOULD include this field with
+ requests. The field can contain multiple product tokens (section 3.8)
+ and comments identifying the agent and any subproducts which form a
+ significant part of the user agent. By convention, the product tokens
+ are listed in order of their significance for identifying the
+ application.
+
+ User-Agent = "User-Agent" ":" 1*( product | comment )
+
+ Example:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+
+14.43 Vary
+
+ The Vary response-header field is used by a server to signal that the
+ response entity was selected from the available representations of
+ the response using server-driven negotiation (section 12). Field-
+ names listed in Vary headers are those of request-headers. The Vary
+ field value indicates either that the given set of header fields
+ encompass the dimensions over which the representation might vary, or
+ that the dimensions of variance are unspecified ("*") and thus may
+ vary over any aspect of future requests.
+
+ Vary = "Vary" ":" ( "*" | 1#field-name )
+
+ An HTTP/1.1 server MUST include an appropriate Vary header field with
+ any cachable response that is subject to server-driven negotiation.
+ Doing so allows a cache to properly interpret future requests on that
+ resource and informs the user agent about the presence of negotiation
+ on that resource. A server SHOULD include an appropriate Vary header
+ field with a non-cachable response that is subject to server-driven
+ negotiation, since this might provide the user agent with useful
+ information about the dimensions over which the response might vary.
+
+ The set of header fields named by the Vary field value is known as
+ the "selecting" request-headers.
+
+ When the cache receives a subsequent request whose Request-URI
+ specifies one or more cache entries including a Vary header, the
+ cache MUST NOT use such a cache entry to construct a response to the
+ new request unless all of the headers named in the cached Vary header
+
+
+
+Fielding, et. al. Standards Track [Page 134]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ are present in the new request, and all of the stored selecting
+ request-headers from the previous request match the corresponding
+ headers in the new request.
+
+ The selecting request-headers from two requests are defined to match
+ if and only if the selecting request-headers in the first request can
+ be transformed to the selecting request-headers in the second request
+ by adding or removing linear whitespace (LWS) at places where this is
+ allowed by the corresponding BNF, and/or combining multiple message-
+ header fields with the same field name following the rules about
+ message headers in section 4.2.
+
+ A Vary field value of "*" signals that unspecified parameters,
+ possibly other than the contents of request-header fields (e.g., the
+ network address of the client), play a role in the selection of the
+ response representation. Subsequent requests on that resource can
+ only be properly interpreted by the origin server, and thus a cache
+ MUST forward a (possibly conditional) request even when it has a
+ fresh response cached for the resource. See section 13.6 for use of
+ the Vary header by caches.
+
+ A Vary field value consisting of a list of field-names signals that
+ the representation selected for the response is based on a selection
+ algorithm which considers ONLY the listed request-header field values
+ in selecting the most appropriate representation. A cache MAY assume
+ that the same selection will be made for future requests with the
+ same values for the listed field names, for the duration of time in
+ which the response is fresh.
+
+ The field-names given are not limited to the set of standard
+ request-header fields defined by this specification. Field names are
+ case-insensitive.
+
+14.44 Via
+
+ The Via general-header field MUST be used by gateways and proxies to
+ indicate the intermediate protocols and recipients between the user
+ agent and the server on requests, and between the origin server and
+ the client on responses. It is analogous to the "Received" field of
+ RFC 822 and is intended to be used for tracking message forwards,
+ avoiding request loops, and identifying the protocol capabilities of
+ all senders along the request/response chain.
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 135]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Via = "Via" ":" 1#( received-protocol received-by [ comment ] )
+
+ received-protocol = [ protocol-name "/" ] protocol-version
+ protocol-name = token
+ protocol-version = token
+ received-by = ( host [ ":" port ] ) | pseudonym
+ pseudonym = token
+
+ The received-protocol indicates the protocol version of the message
+ received by the server or client along each segment of the
+ request/response chain. The received-protocol version is appended to
+ the Via field value when the message is forwarded so that information
+ about the protocol capabilities of upstream applications remains
+ visible to all recipients.
+
+ The protocol-name is optional if and only if it would be "HTTP". The
+ received-by field is normally the host and optional port number of a
+ recipient server or client that subsequently forwarded the message.
+ However, if the real host is considered to be sensitive information,
+ it MAY be replaced by a pseudonym. If the port is not given, it MAY
+ be assumed to be the default port of the received-protocol.
+
+ Multiple Via field values represent each proxy or gateway that has
+ forwarded the message. Each recipient MUST append its information
+ such that the end result is ordered according to the sequence of
+ forwarding applications.
+
+ Comments MAY be used in the Via header field to identify the software
+ of the recipient proxy or gateway, analogous to the User-Agent and
+ Server header fields. However, all comments in the Via field are
+ optional and MAY be removed by any recipient prior to forwarding the
+ message.
+
+ For example, a request message could be sent from an HTTP/1.0 user
+ agent to an internal proxy code-named "fred", which uses HTTP/1.1 to
+ forward the request to a public proxy at nowhere.com, which completes
+ the request by forwarding it to the origin server at www.ics.uci.edu.
+ The request received by www.ics.uci.edu would then have the following
+ Via header field:
+
+ Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
+
+ Proxies and gateways used as a portal through a network firewall
+ SHOULD NOT, by default, forward the names and ports of hosts within
+ the firewall region. This information SHOULD only be propagated if
+ explicitly enabled. If not enabled, the received-by host of any host
+ behind the firewall SHOULD be replaced by an appropriate pseudonym
+ for that host.
+
+
+
+Fielding, et. al. Standards Track [Page 136]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ For organizations that have strong privacy requirements for hiding
+ internal structures, a proxy MAY combine an ordered subsequence of
+ Via header field entries with identical received-protocol values into
+ a single such entry. For example,
+
+ Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
+
+ could be collapsed to
+
+ Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
+
+ Applications SHOULD NOT combine multiple entries unless they are all
+ under the same organizational control and the hosts have already been
+ replaced by pseudonyms. Applications MUST NOT combine entries which
+ have different received-protocol values.
+
+14.45 Warning
+
+ The Warning response-header field is used to carry additional
+ information about the status of a response which may not be reflected
+ by the response status code. This information is typically, though
+ not exclusively, used to warn about a possible lack of semantic
+ transparency from caching operations.
+
+ Warning headers are sent with responses using:
+
+ Warning = "Warning" ":" 1#warning-value
+
+ warning-value = warn-code SP warn-agent SP warn-text
+ warn-code = 2DIGIT
+ warn-agent = ( host [ ":" port ] ) | pseudonym
+ ; the name or pseudonym of the server adding
+ ; the Warning header, for use in debugging
+ warn-text = quoted-string
+
+ A response may carry more than one Warning header.
+
+ The warn-text should be in a natural language and character set that
+ is most likely to be intelligible to the human user receiving the
+ response. This decision may be based on any available knowledge,
+ such as the location of the cache or user, the Accept-Language field
+ in a request, the Content-Language field in a response, etc. The
+ default language is English and the default character set is ISO-
+ 8859-1.
+
+ If a character set other than ISO-8859-1 is used, it MUST be encoded
+ in the warn-text using the method described in RFC 1522 [14].
+
+
+
+
+Fielding, et. al. Standards Track [Page 137]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Any server or cache may add Warning headers to a response. New
+ Warning headers should be added after any existing Warning headers. A
+ cache MUST NOT delete any Warning header that it received with a
+ response. However, if a cache successfully validates a cache entry,
+ it SHOULD remove any Warning headers previously attached to that
+ entry except as specified for specific Warning codes. It MUST then
+ add any Warning headers received in the validating response. In other
+ words, Warning headers are those that would be attached to the most
+ recent relevant response.
+
+ When multiple Warning headers are attached to a response, the user
+ agent SHOULD display as many of them as possible, in the order that
+ they appear in the response. If it is not possible to display all of
+ the warnings, the user agent should follow these heuristics:
+
+ o Warnings that appear early in the response take priority over those
+ appearing later in the response.
+ o Warnings in the user's preferred character set take priority over
+ warnings in other character sets but with identical warn-codes and
+ warn-agents.
+
+ Systems that generate multiple Warning headers should order them with
+ this user agent behavior in mind.
+
+ This is a list of the currently-defined warn-codes, each with a
+ recommended warn-text in English, and a description of its meaning.
+
+10 Response is stale
+ MUST be included whenever the returned response is stale. A cache may
+ add this warning to any response, but may never remove it until the
+ response is known to be fresh.
+
+11 Revalidation failed
+ MUST be included if a cache returns a stale response because an
+ attempt to revalidate the response failed, due to an inability to
+ reach the server. A cache may add this warning to any response, but
+ may never remove it until the response is successfully revalidated.
+
+12 Disconnected operation
+ SHOULD be included if the cache is intentionally disconnected from
+ the rest of the network for a period of time.
+
+13 Heuristic expiration
+ MUST be included if the cache heuristically chose a freshness
+ lifetime greater than 24 hours and the response's age is greater than
+ 24 hours.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 138]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+14 Transformation applied
+ MUST be added by an intermediate cache or proxy if it applies any
+ transformation changing the content-coding (as specified in the
+ Content-Encoding header) or media-type (as specified in the
+ Content-Type header) of the response, unless this Warning code
+ already appears in the response. MUST NOT be deleted from a response
+ even after revalidation.
+
+99 Miscellaneous warning
+ The warning text may include arbitrary information to be presented to
+ a human user, or logged. A system receiving this warning MUST NOT
+ take any automated action.
+
+14.46 WWW-Authenticate
+
+ The WWW-Authenticate response-header field MUST be included in 401
+ (Unauthorized) response messages. The field value consists of at
+ least one challenge that indicates the authentication scheme(s) and
+ parameters applicable to the Request-URI.
+
+ WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
+
+ The HTTP access authentication process is described in section 11.
+ User agents MUST take special care in parsing the WWW-Authenticate
+ field value if it contains more than one challenge, or if more than
+ one WWW-Authenticate header field is provided, since the contents of
+ a challenge may itself contain a comma-separated list of
+ authentication parameters.
+
+15 Security Considerations
+
+ This section is meant to inform application developers, information
+ providers, and users of the security limitations in HTTP/1.1 as
+ described by this document. The discussion does not include
+ definitive solutions to the problems revealed, though it does make
+ some suggestions for reducing security risks.
+
+15.1 Authentication of Clients
+
+ The Basic authentication scheme is not a secure method of user
+ authentication, nor does it in any way protect the entity, which is
+ transmitted in clear text across the physical network used as the
+ carrier. HTTP does not prevent additional authentication schemes and
+ encryption mechanisms from being employed to increase security or the
+ addition of enhancements (such as schemes to use one-time passwords)
+ to Basic authentication.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 139]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The most serious flaw in Basic authentication is that it results in
+ the essentially clear text transmission of the user's password over
+ the physical network. It is this problem which Digest Authentication
+ attempts to address.
+
+ Because Basic authentication involves the clear text transmission of
+ passwords it SHOULD never be used (without enhancements) to protect
+ sensitive or valuable information.
+
+ A common use of Basic authentication is for identification purposes
+ -- requiring the user to provide a user name and password as a means
+ of identification, for example, for purposes of gathering accurate
+ usage statistics on a server. When used in this way it is tempting to
+ think that there is no danger in its use if illicit access to the
+ protected documents is not a major concern. This is only correct if
+ the server issues both user name and password to the users and in
+ particular does not allow the user to choose his or her own password.
+ The danger arises because naive users frequently reuse a single
+ password to avoid the task of maintaining multiple passwords.
+
+ If a server permits users to select their own passwords, then the
+ threat is not only illicit access to documents on the server but also
+ illicit access to the accounts of all users who have chosen to use
+ their account password. If users are allowed to choose their own
+ password that also means the server must maintain files containing
+ the (presumably encrypted) passwords. Many of these may be the
+ account passwords of users perhaps at distant sites. The owner or
+ administrator of such a system could conceivably incur liability if
+ this information is not maintained in a secure fashion.
+
+ Basic Authentication is also vulnerable to spoofing by counterfeit
+ servers. If a user can be led to believe that he is connecting to a
+ host containing information protected by basic authentication when in
+ fact he is connecting to a hostile server or gateway then the
+ attacker can request a password, store it for later use, and feign an
+ error. This type of attack is not possible with Digest Authentication
+ [32]. Server implementers SHOULD guard against the possibility of
+ this sort of counterfeiting by gateways or CGI scripts. In particular
+ it is very dangerous for a server to simply turn over a connection to
+ a gateway since that gateway can then use the persistent connection
+ mechanism to engage in multiple transactions with the client while
+ impersonating the original server in a way that is not detectable by
+ the client.
+
+15.2 Offering a Choice of Authentication Schemes
+
+ An HTTP/1.1 server may return multiple challenges with a 401
+ (Authenticate) response, and each challenge may use a different
+
+
+
+Fielding, et. al. Standards Track [Page 140]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ scheme. The order of the challenges returned to the user agent is in
+ the order that the server would prefer they be chosen. The server
+ should order its challenges with the "most secure" authentication
+ scheme first. A user agent should choose as the challenge to be made
+ to the user the first one that the user agent understands.
+
+ When the server offers choices of authentication schemes using the
+ WWW-Authenticate header, the "security" of the authentication is only
+ as malicious user could capture the set of challenges and try to
+ authenticate him/herself using the weakest of the authentication
+ schemes. Thus, the ordering serves more to protect the user's
+ credentials than the server's information.
+
+ A possible man-in-the-middle (MITM) attack would be to add a weak
+ authentication scheme to the set of choices, hoping that the client
+ will use one that exposes the user's credentials (e.g. password). For
+ this reason, the client should always use the strongest scheme that
+ it understands from the choices accepted.
+
+ An even better MITM attack would be to remove all offered choices,
+ and to insert a challenge that requests Basic authentication. For
+ this reason, user agents that are concerned about this kind of attack
+ could remember the strongest authentication scheme ever requested by
+ a server and produce a warning message that requires user
+ confirmation before using a weaker one. A particularly insidious way
+ to mount such a MITM attack would be to offer a "free" proxy caching
+ service to gullible users.
+
+15.3 Abuse of Server Log Information
+
+ A server is in the position to save personal data about a user's
+ requests which may identify their reading patterns or subjects of
+ interest. This information is clearly confidential in nature and its
+ handling may be constrained by law in certain countries. People using
+ the HTTP protocol to provide data are responsible for ensuring that
+ such material is not distributed without the permission of any
+ individuals that are identifiable by the published results.
+
+15.4 Transfer of Sensitive Information
+
+ Like any generic data transfer protocol, HTTP cannot regulate the
+ content of the data that is transferred, nor is there any a priori
+ method of determining the sensitivity of any particular piece of
+ information within the context of any given request. Therefore,
+ applications SHOULD supply as much control over this information as
+ possible to the provider of that information. Four header fields are
+ worth special mention in this context: Server, Via, Referer and From.
+
+
+
+
+Fielding, et. al. Standards Track [Page 141]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Revealing the specific software version of the server may allow the
+ server machine to become more vulnerable to attacks against software
+ that is known to contain security holes. Implementers SHOULD make the
+ Server header field a configurable option.
+
+ Proxies which serve as a portal through a network firewall SHOULD
+ take special precautions regarding the transfer of header information
+ that identifies the hosts behind the firewall. In particular, they
+ SHOULD remove, or replace with sanitized versions, any Via fields
+ generated behind the firewall.
+
+ The Referer field allows reading patterns to be studied and reverse
+ links drawn. Although it can be very useful, its power can be abused
+ if user details are not separated from the information contained in
+ the Referer. Even when the personal information has been removed, the
+ Referer field may indicate a private document's URI whose publication
+ would be inappropriate.
+
+ The information sent in the From field might conflict with the user's
+ privacy interests or their site's security policy, and hence it
+ SHOULD NOT be transmitted without the user being able to disable,
+ enable, and modify the contents of the field. The user MUST be able
+ to set the contents of this field within a user preference or
+ application defaults configuration.
+
+ We suggest, though do not require, that a convenient toggle interface
+ be provided for the user to enable or disable the sending of From and
+ Referer information.
+
+15.5 Attacks Based On File and Path Names
+
+ Implementations of HTTP origin servers SHOULD be careful to restrict
+ the documents returned by HTTP requests to be only those that were
+ intended by the server administrators. If an HTTP server translates
+ HTTP URIs directly into file system calls, the server MUST take
+ special care not to serve files that were not intended to be
+ delivered to HTTP clients. For example, UNIX, Microsoft Windows, and
+ other operating systems use ".." as a path component to indicate a
+ directory level above the current one. On such a system, an HTTP
+ server MUST disallow any such construct in the Request-URI if it
+ would otherwise allow access to a resource outside those intended to
+ be accessible via the HTTP server. Similarly, files intended for
+ reference only internally to the server (such as access control
+ files, configuration files, and script code) MUST be protected from
+ inappropriate retrieval, since they might contain sensitive
+ information. Experience has shown that minor bugs in such HTTP server
+ implementations have turned into security risks.
+
+
+
+
+Fielding, et. al. Standards Track [Page 142]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+15.6 Personal Information
+
+ HTTP clients are often privy to large amounts of personal information
+ (e.g. the user's name, location, mail address, passwords, encryption
+ keys, etc.), and SHOULD be very careful to prevent unintentional
+ leakage of this information via the HTTP protocol to other sources.
+ We very strongly recommend that a convenient interface be provided
+ for the user to control dissemination of such information, and that
+ designers and implementers be particularly careful in this area.
+ History shows that errors in this area are often both serious
+ security and/or privacy problems, and often generate highly adverse
+ publicity for the implementer's company.
+
+15.7 Privacy Issues Connected to Accept Headers
+
+ Accept request-headers can reveal information about the user to all
+ servers which are accessed. The Accept-Language header in particular
+ can reveal information the user would consider to be of a private
+ nature, because the understanding of particular languages is often
+ strongly correlated to the membership of a particular ethnic group.
+ User agents which offer the option to configure the contents of an
+ Accept-Language header to be sent in every request are strongly
+ encouraged to let the configuration process include a message which
+ makes the user aware of the loss of privacy involved.
+
+ An approach that limits the loss of privacy would be for a user agent
+ to omit the sending of Accept-Language headers by default, and to ask
+ the user whether it should start sending Accept-Language headers to a
+ server if it detects, by looking for any Vary response-header fields
+ generated by the server, that such sending could improve the quality
+ of service.
+
+ Elaborate user-customized accept header fields sent in every request,
+ in particular if these include quality values, can be used by servers
+ as relatively reliable and long-lived user identifiers. Such user
+ identifiers would allow content providers to do click-trail tracking,
+ and would allow collaborating content providers to match cross-server
+ click-trails or form submissions of individual users. Note that for
+ many users not behind a proxy, the network address of the host
+ running the user agent will also serve as a long-lived user
+ identifier. In environments where proxies are used to enhance
+ privacy, user agents should be conservative in offering accept header
+ configuration options to end users. As an extreme privacy measure,
+ proxies could filter the accept headers in relayed requests. General
+ purpose user agents which provide a high degree of header
+ configurability should warn users about the loss of privacy which can
+ be involved.
+
+
+
+
+Fielding, et. al. Standards Track [Page 143]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+15.8 DNS Spoofing
+
+ Clients using HTTP rely heavily on the Domain Name Service, and are
+ thus generally prone to security attacks based on the deliberate
+ mis-association of IP addresses and DNS names. Clients need to be
+ cautious in assuming the continuing validity of an IP number/DNS name
+ association.
+
+ In particular, HTTP clients SHOULD rely on their name resolver for
+ confirmation of an IP number/DNS name association, rather than
+ caching the result of previous host name lookups. Many platforms
+ already can cache host name lookups locally when appropriate, and
+ they SHOULD be configured to do so. These lookups should be cached,
+ however, only when the TTL (Time To Live) information reported by the
+ name server makes it likely that the cached information will remain
+ useful.
+
+ If HTTP clients cache the results of host name lookups in order to
+ achieve a performance improvement, they MUST observe the TTL
+ information reported by DNS.
+
+ If HTTP clients do not observe this rule, they could be spoofed when
+ a previously-accessed server's IP address changes. As network
+ renumbering is expected to become increasingly common, the
+ possibility of this form of attack will grow. Observing this
+ requirement thus reduces this potential security vulnerability.
+
+ This requirement also improves the load-balancing behavior of clients
+ for replicated servers using the same DNS name and reduces the
+ likelihood of a user's experiencing failure in accessing sites which
+ use that strategy.
+
+15.9 Location Headers and Spoofing
+
+ If a single server supports multiple organizations that do not trust
+ one another, then it must check the values of Location and Content-
+ Location headers in responses that are generated under control of
+ said organizations to make sure that they do not attempt to
+ invalidate resources over which they have no authority.
+
+16 Acknowledgments
+
+ This specification makes heavy use of the augmented BNF and generic
+ constructs defined by David H. Crocker for RFC 822. Similarly, it
+ reuses many of the definitions provided by Nathaniel Borenstein and
+ Ned Freed for MIME. We hope that their inclusion in this
+ specification will help reduce past confusion over the relationship
+ between HTTP and Internet mail message formats.
+
+
+
+Fielding, et. al. Standards Track [Page 144]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The HTTP protocol has evolved considerably over the past four years.
+ It has benefited from a large and active developer community--the
+ many people who have participated on the www-talk mailing list--and
+ it is that community which has been most responsible for the success
+ of HTTP and of the World-Wide Web in general. Marc Andreessen, Robert
+ Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois
+ Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob
+ McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc
+ VanHeyningen deserve special recognition for their efforts in
+ defining early aspects of the protocol.
+
+ This document has benefited greatly from the comments of all those
+ participating in the HTTP-WG. In addition to those already mentioned,
+ the following individuals have contributed to this specification:
+
+ Gary Adams Albert Lunde
+ Harald Tveit Alvestrand John C. Mallery
+ Keith Ball Jean-Philippe Martin-Flatin
+ Brian Behlendorf Larry Masinter
+ Paul Burchard Mitra
+ Maurizio Codogno David Morris
+ Mike Cowlishaw Gavin Nicol
+ Roman Czyborra Bill Perry
+ Michael A. Dolan Jeffrey Perry
+ David J. Fiander Scott Powers
+ Alan Freier Owen Rees
+ Marc Hedlund Luigi Rizzo
+ Greg Herlihy David Robinson
+ Koen Holtman Marc Salomon
+ Alex Hopmann Rich Salz
+ Bob Jernigan Allan M. Schiffman
+ Shel Kaphan Jim Seidman
+ Rohit Khare Chuck Shotton
+ John Klensin Eric W. Sink
+ Martijn Koster Simon E. Spero
+ Alexei Kosut Richard N. Taylor
+ David M. Kristol Robert S. Thau
+ Daniel LaLiberte Bill (BearHeart) Weinman
+ Ben Laurie Francois Yergeau
+ Paul J. Leach Mary Ellen Zurko
+ Daniel DuBois
+
+ Much of the content and presentation of the caching design is due to
+ suggestions and comments from individuals including: Shel Kaphan,
+ Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 145]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Most of the specification of ranges is based on work originally done
+ by Ari Luotonen and John Franks, with additional input from Steve
+ Zilles.
+
+ Thanks to the "cave men" of Palo Alto. You know who you are.
+
+ Jim Gettys (the current editor of this document) wishes particularly
+ to thank Roy Fielding, the previous editor of this document, along
+ with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen
+ Holtman, John Franks, Alex Hopmann, and Larry Masinter for their
+ help.
+
+17 References
+
+ [1] Alvestrand, H., "Tags for the identification of languages", RFC
+ 1766, UNINETT, March 1995.
+
+ [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey,
+ D., and B. Alberti. "The Internet Gopher Protocol: (a distributed
+ document search and retrieval protocol)", RFC 1436, University of
+ Minnesota, March 1993.
+
+ [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", A
+ Unifying Syntax for the Expression of Names and Addresses of Objects
+ on the Network as used in the World-Wide Web", RFC 1630, CERN, June
+ 1994.
+
+ [4] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource
+ Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota,
+ December 1994.
+
+ [5] Berners-Lee, T., and D. Connolly, "HyperText Markup Language
+ Specification - 2.0", RFC 1866, MIT/LCS, November 1995.
+
+ [6] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext
+ Transfer Protocol -- HTTP/1.0.", RFC 1945 MIT/LCS, UC Irvine, May
+ 1996.
+
+ [7] Freed, N., and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message Bodies", RFC
+ 2045, Innosoft, First Virtual, November 1996.
+
+ [8] Braden, R., "Requirements for Internet hosts - application and
+ support", STD 3, RFC 1123, IETF, October 1989.
+
+ [9] Crocker, D., "Standard for the Format of ARPA Internet Text
+ Messages", STD 11, RFC 822, UDEL, August 1982.
+
+
+
+
+Fielding, et. al. Standards Track [Page 146]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R.,
+ Sui, J., and M. Grinbaum. "WAIS Interface Protocol Prototype
+ Functional Specification", (v1.5), Thinking Machines Corporation,
+ April 1990.
+
+ [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808, UC
+ Irvine, June 1995.
+
+ [12] Horton, M., and R. Adams. "Standard for interchange of USENET
+ messages", RFC 1036, AT&T Bell Laboratories, Center for Seismic
+ Studies, December 1987.
+
+ [13] Kantor, B., and P. Lapsley. "Network News Transfer Protocol." A
+ Proposed Standard for the Stream-Based Transmission of News", RFC
+ 977, UC San Diego, UC Berkeley, February 1986.
+
+ [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
+ Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
+ University of Tennessee, November 1996.
+
+ [15] Nebel, E., and L. Masinter. "Form-based File Upload in HTML",
+ RFC 1867, Xerox Corporation, November 1995.
+
+ [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
+ USC/ISI, August 1982.
+
+ [17] Postel, J., "Media Type Registration Procedure", RFC 2048,
+ USC/ISI, November 1996.
+
+ [18] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)", STD
+ 9, RFC 959, USC/ISI, October 1985.
+
+ [19] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC
+ 1700, USC/ISI, October 1994.
+
+ [20] Sollins, K., and L. Masinter, "Functional Requirements for
+ Uniform Resource Names", RFC 1737, MIT/LCS, Xerox Corporation,
+ December 1994.
+
+ [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for
+ Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
+
+ [22] ISO-8859. International Standard -- Information Processing --
+ 8-bit Single-Byte Coded Graphic Character Sets --
+ Part 1: Latin alphabet No. 1, ISO 8859-1:1987.
+ Part 2: Latin alphabet No. 2, ISO 8859-2, 1987.
+ Part 3: Latin alphabet No. 3, ISO 8859-3, 1988.
+ Part 4: Latin alphabet No. 4, ISO 8859-4, 1988.
+
+
+
+Fielding, et. al. Standards Track [Page 147]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988.
+ Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987.
+ Part 7: Latin/Greek alphabet, ISO 8859-7, 1987.
+ Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988.
+ Part 9: Latin alphabet No. 5, ISO 8859-9, 1990.
+
+ [23] Meyers, J., and M. Rose "The Content-MD5 Header Field", RFC
+ 1864, Carnegie Mellon, Dover Beach Consulting, October, 1995.
+
+ [24] Carpenter, B., and Y. Rekhter, "Renumbering Needs Work", RFC
+ 1900, IAB, February 1996.
+
+ [25] Deutsch, P., "GZIP file format specification version 4.3." RFC
+ 1952, Aladdin Enterprises, May 1996.
+
+ [26] Venkata N. Padmanabhan and Jeffrey C. Mogul. Improving HTTP
+ Latency. Computer Networks and ISDN Systems, v. 28, pp. 25-35, Dec.
+ 1995. Slightly revised version of paper in Proc. 2nd International
+ WWW Conf. '94: Mosaic and the Web, Oct. 1994, which is available at
+ http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/
+ HTTPLatency.html.
+
+ [27] Joe Touch, John Heidemann, and Katia Obraczka, "Analysis of HTTP
+ Performance", <URL: http://www.isi.edu/lsam/ib/http-perf/>,
+ USC/Information Sciences Institute, June 1996
+
+ [28] Mills, D., "Network Time Protocol, Version 3, Specification,
+ Implementation and Analysis", RFC 1305, University of Delaware, March
+ 1992.
+
+ [29] Deutsch, P., "DEFLATE Compressed Data Format Specification
+ version 1.3." RFC 1951, Aladdin Enterprises, May 1996.
+
+ [30] Spero, S., "Analysis of HTTP Performance Problems"
+ <URL:http://sunsite.unc.edu/mdma-release/http-prob.html>.
+
+ [31] Deutsch, P., and J-L. Gailly, "ZLIB Compressed Data Format
+ Specification version 3.3", RFC 1950, Aladdin Enterprises, Info-ZIP,
+ May 1996.
+
+ [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
+ Luotonen, A., Sink, E., and L. Stewart, "An Extension to HTTP :
+ Digest Access Authentication", RFC 2069, January 1997.
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 148]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+18 Authors' Addresses
+
+ Roy T. Fielding
+ Department of Information and Computer Science
+ University of California
+ Irvine, CA 92717-3425, USA
+
+ Fax: +1 (714) 824-4056
+
+
+ Jim Gettys
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+ Jeffrey C. Mogul
+ Western Research Laboratory
+ Digital Equipment Corporation
+ 250 University Avenue
+ Palo Alto, California, 94305, USA
+
+
+
+ Henrik Frystyk Nielsen
+ W3 Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+ Tim Berners-Lee
+ Director, W3 Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+
+
+Fielding, et. al. Standards Track [Page 149]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19 Appendices
+
+19.1 Internet Media Type message/http
+
+ In addition to defining the HTTP/1.1 protocol, this document serves
+ as the specification for the Internet media type "message/http". The
+ following is to be registered with IANA.
+
+ Media Type name: message
+ Media subtype name: http
+ Required parameters: none
+ Optional parameters: version, msgtype
+
+ version: The HTTP-Version number of the enclosed message
+ (e.g., "1.1"). If not present, the version can be
+ determined from the first line of the body.
+
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+
+ Security considerations: none
+
+19.2 Internet Media Type multipart/byteranges
+
+ When an HTTP message includes the content of multiple ranges (for
+ example, a response to a request for multiple non-overlapping
+ ranges), these are transmitted as a multipart MIME message. The
+ multipart media type for this purpose is called
+ "multipart/byteranges".
+
+ The multipart/byteranges media type includes two or more parts, each
+ with its own Content-Type and Content-Range fields. The parts are
+ separated using a MIME boundary parameter.
+
+ Media Type name: multipart
+ Media subtype name: byteranges
+ Required parameters: boundary
+ Optional parameters: none
+
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+
+ Security considerations: none
+
+
+
+
+Fielding, et. al. Standards Track [Page 150]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+For example:
+
+ HTTP/1.1 206 Partial content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
+
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 500-999/8000
+
+ ...the first range...
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 7000-7999/8000
+
+ ...the second range
+ --THIS_STRING_SEPARATES--
+
+19.3 Tolerant Applications
+
+ Although this document specifies the requirements for the generation
+ of HTTP/1.1 messages, not all applications will be correct in their
+ implementation. We therefore recommend that operational applications
+ be tolerant of deviations whenever those deviations can be
+ interpreted unambiguously.
+
+ Clients SHOULD be tolerant in parsing the Status-Line and servers
+ tolerant when parsing the Request-Line. In particular, they SHOULD
+ accept any amount of SP or HT characters between fields, even though
+ only a single SP is required.
+
+ The line terminator for message-header fields is the sequence CRLF.
+ However, we recommend that applications, when parsing such headers,
+ recognize a single LF as a line terminator and ignore the leading CR.
+
+ The character set of an entity-body should be labeled as the lowest
+ common denominator of the character codes used within that body, with
+ the exception that no label is preferred over the labels US-ASCII or
+ ISO-8859-1.
+
+ Additional rules for requirements on parsing and encoding of dates
+ and other potential problems with date encodings include:
+
+ o HTTP/1.1 clients and caches should assume that an RFC-850 date
+ which appears to be more than 50 years in the future is in fact
+ in the past (this helps solve the "year 2000" problem).
+
+
+
+
+Fielding, et. al. Standards Track [Page 151]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ o An HTTP/1.1 implementation may internally represent a parsed
+ Expires date as earlier than the proper value, but MUST NOT
+ internally represent a parsed Expires date as later than the
+ proper value.
+
+ o All expiration-related calculations must be done in GMT. The
+ local time zone MUST NOT influence the calculation or comparison
+ of an age or expiration time.
+
+ o If an HTTP header incorrectly carries a date value with a time
+ zone other than GMT, it must be converted into GMT using the most
+ conservative possible conversion.
+
+19.4 Differences Between HTTP Entities and MIME Entities
+
+ HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC
+ 822) and the Multipurpose Internet Mail Extensions (MIME ) to allow
+ entities to be transmitted in an open variety of representations and
+ with extensible mechanisms. However, MIME [7] discusses mail, and
+ HTTP has a few features that are different from those described in
+ MIME. These differences were carefully chosen to optimize
+ performance over binary connections, to allow greater freedom in the
+ use of new media types, to make date comparisons easier, and to
+ acknowledge the practice of some early HTTP servers and clients.
+
+ This appendix describes specific areas where HTTP differs from MIME.
+ Proxies and gateways to strict MIME environments SHOULD be aware of
+ these differences and provide the appropriate conversions where
+ necessary. Proxies and gateways from MIME environments to HTTP also
+ need to be aware of the differences because some conversions may be
+ required.
+
+19.4.1 Conversion to Canonical Form
+
+ MIME requires that an Internet mail entity be converted to canonical
+ form prior to being transferred. Section 3.7.1 of this document
+ describes the forms allowed for subtypes of the "text" media type
+ when transmitted over HTTP. MIME requires that content with a type of
+ "text" represent line breaks as CRLF and forbids the use of CR or LF
+ outside of line break sequences. HTTP allows CRLF, bare CR, and bare
+ LF to indicate a line break within text content when a message is
+ transmitted over HTTP.
+
+ Where it is possible, a proxy or gateway from HTTP to a strict MIME
+ environment SHOULD translate all line breaks within the text media
+ types described in section 3.7.1 of this document to the MIME
+ canonical form of CRLF. Note, however, that this may be complicated
+ by the presence of a Content-Encoding and by the fact that HTTP
+
+
+
+Fielding, et. al. Standards Track [Page 152]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ allows the use of some character sets which do not use octets 13 and
+ 10 to represent CR and LF, as is the case for some multi-byte
+ character sets.
+
+19.4.2 Conversion of Date Formats
+
+ HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to
+ simplify the process of date comparison. Proxies and gateways from
+ other protocols SHOULD ensure that any Date header field present in a
+ message conforms to one of the HTTP/1.1 formats and rewrite the date
+ if necessary.
+
+19.4.3 Introduction of Content-Encoding
+
+ MIME does not include any concept equivalent to HTTP/1.1's Content-
+ Encoding header field. Since this acts as a modifier on the media
+ type, proxies and gateways from HTTP to MIME-compliant protocols MUST
+ either change the value of the Content-Type header field or decode
+ the entity-body before forwarding the message. (Some experimental
+ applications of Content-Type for Internet mail have used a media-type
+ parameter of ";conversions=<content-coding>" to perform an equivalent
+ function as Content-Encoding. However, this parameter is not part of
+ MIME.)
+
+19.4.4 No Content-Transfer-Encoding
+
+ HTTP does not use the Content-Transfer-Encoding (CTE) field of MIME.
+ Proxies and gateways from MIME-compliant protocols to HTTP MUST
+ remove any non-identity CTE ("quoted-printable" or "base64") encoding
+ prior to delivering the response message to an HTTP client.
+
+ Proxies and gateways from HTTP to MIME-compliant protocols are
+ responsible for ensuring that the message is in the correct format
+ and encoding for safe transport on that protocol, where "safe
+ transport" is defined by the limitations of the protocol being used.
+ Such a proxy or gateway SHOULD label the data with an appropriate
+ Content-Transfer-Encoding if doing so will improve the likelihood of
+ safe transport over the destination protocol.
+
+19.4.5 HTTP Header Fields in Multipart Body-Parts
+
+ In MIME, most header fields in multipart body-parts are generally
+ ignored unless the field name begins with "Content-". In HTTP/1.1,
+ multipart body-parts may contain any HTTP header fields which are
+ significant to the meaning of that part.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 153]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.4.6 Introduction of Transfer-Encoding
+
+ HTTP/1.1 introduces the Transfer-Encoding header field (section
+ 14.40). Proxies/gateways MUST remove any transfer coding prior to
+ forwarding a message via a MIME-compliant protocol.
+
+ A process for decoding the "chunked" transfer coding (section 3.6)
+ can be represented in pseudo-code as:
+
+ length := 0
+ read chunk-size, chunk-ext (if any) and CRLF
+ while (chunk-size > 0) {
+ read chunk-data and CRLF
+ append chunk-data to entity-body
+ length := length + chunk-size
+ read chunk-size and CRLF
+ }
+ read entity-header
+ while (entity-header not empty) {
+ append entity-header to existing header fields
+ read entity-header
+ }
+ Content-Length := length
+ Remove "chunked" from Transfer-Encoding
+
+19.4.7 MIME-Version
+
+ HTTP is not a MIME-compliant protocol (see appendix 19.4). However,
+ HTTP/1.1 messages may include a single MIME-Version general-header
+ field to indicate what version of the MIME protocol was used to
+ construct the message. Use of the MIME-Version header field indicates
+ that the message is in full compliance with the MIME protocol.
+ Proxies/gateways are responsible for ensuring full compliance (where
+ possible) when exporting HTTP messages to strict MIME environments.
+
+ MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT
+
+ MIME version "1.0" is the default for use in HTTP/1.1. However,
+ HTTP/1.1 message parsing and semantics are defined by this document
+ and not the MIME specification.
+
+19.5 Changes from HTTP/1.0
+
+ This section summarizes major differences between versions HTTP/1.0
+ and HTTP/1.1.
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 154]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.5.1 Changes to Simplify Multi-homed Web Servers and Conserve IP
+ Addresses
+
+ The requirements that clients and servers support the Host request-
+ header, report an error if the Host request-header (section 14.23) is
+ missing from an HTTP/1.1 request, and accept absolute URIs (section
+ 5.1.2) are among the most important changes defined by this
+ specification.
+
+ Older HTTP/1.0 clients assumed a one-to-one relationship of IP
+ addresses and servers; there was no other established mechanism for
+ distinguishing the intended server of a request than the IP address
+ to which that request was directed. The changes outlined above will
+ allow the Internet, once older HTTP clients are no longer common, to
+ support multiple Web sites from a single IP address, greatly
+ simplifying large operational Web servers, where allocation of many
+ IP addresses to a single host has created serious problems. The
+ Internet will also be able to recover the IP addresses that have been
+ allocated for the sole purpose of allowing special-purpose domain
+ names to be used in root-level HTTP URLs. Given the rate of growth of
+ the Web, and the number of servers already deployed, it is extremely
+ important that all implementations of HTTP (including updates to
+ existing HTTP/1.0 applications) correctly implement these
+ requirements:
+
+ o Both clients and servers MUST support the Host request-header.
+
+ o Host request-headers are required in HTTP/1.1 requests.
+
+ o Servers MUST report a 400 (Bad Request) error if an HTTP/1.1
+ request does not include a Host request-header.
+
+ o Servers MUST accept absolute URIs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 155]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.6 Additional Features
+
+ This appendix documents protocol elements used by some existing HTTP
+ implementations, but not consistently and correctly across most
+ HTTP/1.1 applications. Implementers should be aware of these
+ features, but cannot rely upon their presence in, or interoperability
+ with, other HTTP/1.1 applications. Some of these describe proposed
+ experimental features, and some describe features that experimental
+ deployment found lacking that are now addressed in the base HTTP/1.1
+ specification.
+
+19.6.1 Additional Request Methods
+
+19.6.1.1 PATCH
+
+ The PATCH method is similar to PUT except that the entity contains a
+ list of differences between the original version of the resource
+ identified by the Request-URI and the desired content of the resource
+ after the PATCH action has been applied. The list of differences is
+ in a format defined by the media type of the entity (e.g.,
+ "application/diff") and MUST include sufficient information to allow
+ the server to recreate the changes necessary to convert the original
+ version of the resource to the desired version.
+
+ If the request passes through a cache and the Request-URI identifies
+ a currently cached entity, that entity MUST be removed from the
+ cache. Responses to this method are not cachable.
+
+ The actual method for determining how the patched resource is placed,
+ and what happens to its predecessor, is defined entirely by the
+ origin server. If the original version of the resource being patched
+ included a Content-Version header field, the request entity MUST
+ include a Derived-From header field corresponding to the value of the
+ original Content-Version header field. Applications are encouraged to
+ use these fields for constructing versioning relationships and
+ resolving version conflicts.
+
+ PATCH requests must obey the message transmission requirements set
+ out in section 8.2.
+
+ Caches that implement PATCH should invalidate cached responses as
+ defined in section 13.10 for PUT.
+
+19.6.1.2 LINK
+
+ The LINK method establishes one or more Link relationships between
+ the existing resource identified by the Request-URI and other
+ existing resources. The difference between LINK and other methods
+
+
+
+Fielding, et. al. Standards Track [Page 156]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ allowing links to be established between resources is that the LINK
+ method does not allow any message-body to be sent in the request and
+ does not directly result in the creation of new resources.
+
+ If the request passes through a cache and the Request-URI identifies
+ a currently cached entity, that entity MUST be removed from the
+ cache. Responses to this method are not cachable.
+
+ Caches that implement LINK should invalidate cached responses as
+ defined in section 13.10 for PUT.
+
+19.6.1.3 UNLINK
+
+ The UNLINK method removes one or more Link relationships from the
+ existing resource identified by the Request-URI. These relationships
+ may have been established using the LINK method or by any other
+ method supporting the Link header. The removal of a link to a
+ resource does not imply that the resource ceases to exist or becomes
+ inaccessible for future references.
+
+ If the request passes through a cache and the Request-URI identifies
+ a currently cached entity, that entity MUST be removed from the
+ cache. Responses to this method are not cachable.
+
+ Caches that implement UNLINK should invalidate cached responses as
+ defined in section 13.10 for PUT.
+
+19.6.2 Additional Header Field Definitions
+
+19.6.2.1 Alternates
+
+ The Alternates response-header field has been proposed as a means for
+ the origin server to inform the client about other available
+ representations of the requested resource, along with their
+ distinguishing attributes, and thus providing a more reliable means
+ for a user agent to perform subsequent selection of another
+ representation which better fits the desires of its user (described
+ as agent-driven negotiation in section 12).
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 157]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ The Alternates header field is orthogonal to the Vary header field in
+ that both may coexist in a message without affecting the
+ interpretation of the response or the available representations. It
+ is expected that Alternates will provide a significant improvement
+ over the server-driven negotiation provided by the Vary field for
+ those resources that vary over common dimensions like type and
+ language.
+
+ The Alternates header field will be defined in a future
+ specification.
+
+19.6.2.2 Content-Version
+
+ The Content-Version entity-header field defines the version tag
+ associated with a rendition of an evolving entity. Together with the
+ Derived-From field described in section 19.6.2.3, it allows a group
+ of people to work simultaneously on the creation of a work as an
+ iterative process. The field should be used to allow evolution of a
+ particular work along a single path rather than derived works or
+ renditions in different representations.
+
+ Content-Version = "Content-Version" ":" quoted-string
+
+ Examples of the Content-Version field include:
+
+ Content-Version: "2.1.2"
+ Content-Version: "Fred 19950116-12:26:48"
+ Content-Version: "2.5a4-omega7"
+
+19.6.2.3 Derived-From
+
+ The Derived-From entity-header field can be used to indicate the
+ version tag of the resource from which the enclosed entity was
+ derived before modifications were made by the sender. This field is
+ used to help manage the process of merging successive changes to a
+ resource, particularly when such changes are being made in parallel
+ and from multiple sources.
+
+ Derived-From = "Derived-From" ":" quoted-string
+
+ An example use of the field is:
+
+ Derived-From: "2.1.1"
+
+ The Derived-From field is required for PUT and PATCH requests if the
+ entity being sent was previously retrieved from the same URI and a
+ Content-Version header was included with the entity when it was last
+ retrieved.
+
+
+
+Fielding, et. al. Standards Track [Page 158]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.6.2.4 Link
+
+ The Link entity-header field provides a means for describing a
+ relationship between two resources, generally between the requested
+ resource and some other resource. An entity MAY include multiple Link
+ values. Links at the metainformation level typically indicate
+ relationships like hierarchical structure and navigation paths. The
+ Link field is semantically equivalent to the <LINK> element in
+ HTML.[5]
+
+ Link = "Link" ":" #("<" URI ">" *( ";" link-param )
+
+ link-param = ( ( "rel" "=" relationship )
+ | ( "rev" "=" relationship )
+ | ( "title" "=" quoted-string )
+ | ( "anchor" "=" <"> URI <"> )
+ | ( link-extension ) )
+
+ link-extension = token [ "=" ( token | quoted-string ) ]
+
+ relationship = sgml-name
+ | ( <"> sgml-name *( SP sgml-name) <"> )
+
+ sgml-name = ALPHA *( ALPHA | DIGIT | "." | "-" )
+
+ Relationship values are case-insensitive and MAY be extended within
+ the constraints of the sgml-name syntax. The title parameter MAY be
+ used to label the destination of a link such that it can be used as
+ identification within a human-readable menu. The anchor parameter MAY
+ be used to indicate a source anchor other than the entire current
+ resource, such as a fragment of this resource or a third resource.
+
+ Examples of usage include:
+
+ Link: <http://www.cern.ch/TheBook/chapter2>; rel="Previous"
+
+ Link: <mailto:[email protected]>; rev="Made"; title="Tim Berners-Lee"
+
+ The first example indicates that chapter2 is previous to this
+ resource in a logical navigation path. The second indicates that the
+ person responsible for making the resource available is identified by
+ the given e-mail address.
+
+19.6.2.5 URI
+
+ The URI header field has, in past versions of this specification,
+ been used as a combination of the existing Location, Content-
+ Location, and Vary header fields as well as the future Alternates
+
+
+
+Fielding, et. al. Standards Track [Page 159]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+ field (above). Its primary purpose has been to include a list of
+ additional URIs for the resource, including names and mirror
+ locations. However, it has become clear that the combination of many
+ different functions within this single field has been a barrier to
+ consistently and correctly implementing any of those functions.
+ Furthermore, we believe that the identification of names and mirror
+ locations would be better performed via the Link header field. The
+ URI header field is therefore deprecated in favor of those other
+ fields.
+
+ URI-header = "URI" ":" 1#( "<" URI ">" )
+
+19.7 Compatibility with Previous Versions
+
+ It is beyond the scope of a protocol specification to mandate
+ compliance with previous versions. HTTP/1.1 was deliberately
+ designed, however, to make supporting previous versions easy. It is
+ worth noting that at the time of composing this specification, we
+ would expect commercial HTTP/1.1 servers to:
+
+ o recognize the format of the Request-Line for HTTP/0.9, 1.0, and 1.1
+ requests;
+
+ o understand any valid request in the format of HTTP/0.9, 1.0, or
+ 1.1;
+
+ o respond appropriately with a message in the same major version used
+ by the client.
+
+ And we would expect HTTP/1.1 clients to:
+
+ o recognize the format of the Status-Line for HTTP/1.0 and 1.1
+ responses;
+
+ o understand any valid response in the format of HTTP/0.9, 1.0, or
+ 1.1.
+
+ For most implementations of HTTP/1.0, each connection is established
+ by the client prior to the request and closed by the server after
+ sending the response. A few implementations implement the Keep-Alive
+ version of persistent connections described in section 19.7.1.1.
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 160]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.7.1 Compatibility with HTTP/1.0 Persistent Connections
+
+ Some clients and servers may wish to be compatible with some previous
+ implementations of persistent connections in HTTP/1.0 clients and
+ servers. Persistent connections in HTTP/1.0 must be explicitly
+ negotiated as they are not the default behavior. HTTP/1.0
+ experimental implementations of persistent connections are faulty,
+ and the new facilities in HTTP/1.1 are designed to rectify these
+ problems. The problem was that some existing 1.0 clients may be
+ sending Keep-Alive to a proxy server that doesn't understand
+ Connection, which would then erroneously forward it to the next
+ inbound server, which would establish the Keep-Alive connection and
+ result in a hung HTTP/1.0 proxy waiting for the close on the
+ response. The result is that HTTP/1.0 clients must be prevented from
+ using Keep-Alive when talking to proxies.
+
+ However, talking to proxies is the most important use of persistent
+ connections, so that prohibition is clearly unacceptable. Therefore,
+ we need some other mechanism for indicating a persistent connection
+ is desired, which is safe to use even when talking to an old proxy
+ that ignores Connection. Persistent connections are the default for
+ HTTP/1.1 messages; we introduce a new keyword (Connection: close) for
+ declaring non-persistence.
+
+ The following describes the original HTTP/1.0 form of persistent
+ connections.
+
+ When it connects to an origin server, an HTTP client MAY send the
+ Keep-Alive connection-token in addition to the Persist connection-
+ token:
+
+ Connection: Keep-Alive
+
+ An HTTP/1.0 server would then respond with the Keep-Alive connection
+ token and the client may proceed with an HTTP/1.0 (or Keep-Alive)
+ persistent connection.
+
+ An HTTP/1.1 server may also establish persistent connections with
+ HTTP/1.0 clients upon receipt of a Keep-Alive connection token.
+ However, a persistent connection with an HTTP/1.0 client cannot make
+ use of the chunked transfer-coding, and therefore MUST use a
+ Content-Length for marking the ending boundary of each message.
+
+ A client MUST NOT send the Keep-Alive connection token to a proxy
+ server as HTTP/1.0 proxy servers do not obey the rules of HTTP/1.1
+ for parsing the Connection header field.
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 161]
+
+RFC 2068 HTTP/1.1 January 1997
+
+
+19.7.1.1 The Keep-Alive Header
+
+ When the Keep-Alive connection-token has been transmitted with a
+ request or a response, a Keep-Alive header field MAY also be
+ included. The Keep-Alive header field takes the following form:
+
+ Keep-Alive-header = "Keep-Alive" ":" 0# keepalive-param
+
+ keepalive-param = param-name "=" value
+
+ The Keep-Alive header itself is optional, and is used only if a
+ parameter is being sent. HTTP/1.1 does not define any parameters.
+
+ If the Keep-Alive header is sent, the corresponding connection token
+ MUST be transmitted. The Keep-Alive header MUST be ignored if
+ received without the connection token.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et. al. Standards Track [Page 162]
+
diff --git a/lib/inets/doc/archive/rfc2145.txt b/lib/inets/doc/archive/rfc2145.txt
new file mode 100644
index 0000000000..b6db4d588d
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2145.txt
@@ -0,0 +1,395 @@
+
+
+
+
+
+
+Network Working Group J. C. Mogul
+Request for Comments: 2145 DEC
+Category: Informational R. Fielding
+ UC Irvine
+ J. Gettys
+ DEC
+ H. Frystyk
+ MIT/LCS
+ May 1997
+
+ Use and Interpretation of
+ HTTP Version Numbers
+
+Status of this Memo
+
+ This memo provides information for the Internet community. This memo
+ does not specify an Internet standard of any kind. Distribution of
+ this memo is unlimited.
+
+ Distribution of this document is unlimited. Please send comments to
+ the HTTP working group at <[email protected]>. Discussions
+ of the working group are archived at
+ <URL:http://www.ics.uci.edu/pub/ietf/http/>. General discussions
+ about HTTP and the applications which use HTTP should take place on
+ the <[email protected]> mailing list.
+
+Abstract
+
+ HTTP request and response messages include an HTTP protocol version
+ number. Some confusion exists concerning the proper use and
+ interpretation of HTTP version numbers, and concerning
+ interoperability of HTTP implementations of different protocol
+ versions. This document is an attempt to clarify the situation. It
+ is not a modification of the intended meaning of the existing
+ HTTP/1.0 and HTTP/1.1 documents, but it does describe the intention
+ of the authors of those documents, and can be considered definitive
+ when there is any ambiguity in those documents concerning HTTP
+ version numbers, for all versions of HTTP.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mogul, et. al. Informational [Page 1]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+TABLE OF CONTENTS
+
+ 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.1 Robustness Principle . . . . . . . . . . . . . . . . . . 3
+ 2 HTTP version numbers. . . . . . . . . . . . . . . . . . . . . . 3
+ 2.1 Proxy behavior. . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2.2 Compatibility between minor versions of the same major
+ version. . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2.3 Which version number to send in a message. . . . . . . . 5
+ 3 Security Considerations . . . . . . . . . . . . . . . . . . . . 6
+ 4 References. . . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 5 Authors' addresses. . . . . . . . . . . . . . . . . . . . . . . 6
+
+1 Introduction
+
+ HTTP request and response messages include an HTTP protocol version
+ number. According to section 3.1 of the HTTP/1.1 specification [2],
+
+ HTTP uses a "<major>.<minor>" numbering scheme to indicate
+ versions of the protocol. The protocol versioning policy is
+ intended to allow the sender to indicate the format of a message
+ and its capacity for understanding further HTTP communication,
+ rather than the features obtained via that communication. No
+ change is made to the version number for the addition of message
+ components which do not affect communication behavior or which
+ only add to extensible field values. The <minor> number is
+ incremented when the changes made to the protocol add features
+ which do not change the general message parsing algorithm, but
+ which may add to the message semantics and imply additional
+ capabilities of the sender. The <major> number is incremented when
+ the format of a message within the protocol is changed.
+
+ The same language appears in the description of HTTP/1.0 [1].
+
+ Many readers of these documents have expressed some confusion about
+ the intended meaning of this policy. Also, some people who wrote
+ HTTP implementations before RFC1945 [1] was issued were not aware of
+ the intentions behind the introduction of version numbers in
+ HTTP/1.0. This has led to debate and inconsistency regarding the use
+ and interpretation of HTTP version numbers, and has led to
+ interoperability problems in certain cases.
+
+
+
+
+
+
+
+
+
+
+Mogul, et. al. Informational [Page 2]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+ This document is an attempt to clarify the situation. It is not a
+ modification of the intended meaning of the existing HTTP/1.0 and
+ HTTP/1.1 documents, but it does describe the intention of the authors
+ of those documents. In any case where either of those two documents
+ is ambiguous regarding the use and interpretation of HTTP version
+ numbers, this document should be considered the definitive as to the
+ intentions of the designers of HTTP.
+
+ The specification described in this document is not part of the
+ specification of any individual version of HTTP, such as HTTP/1.0 or
+ HTTP/1.1. Rather, this document describes the use of HTTP version
+ numbers in any version of HTTP (except for HTTP/0.9, which did not
+ include version numbers).
+
+ No vendor or other provider of an HTTP implementation should claim
+ any compliance with any IETF HTTP specification unless the
+ implementation conditionally complies with the rules in this
+ document.
+
+1.1 Robustness Principle
+
+ RFC791 [4] defines the "robustness principle" in section 3.2:
+
+ an implementation must be conservative in its sending
+ behavior, and liberal in its receiving behavior.
+
+ This principle applies to HTTP, as well. It is the fundamental basis
+ for interpreting any part of the HTTP specification that might still
+ be ambiguous. In particular, implementations of HTTP SHOULD NOT
+ reject messages or generate errors unnecessarily.
+
+2 HTTP version numbers
+
+ We start by restating the language quoted above from section 3.1 of
+ the HTTP/1.1 specification [2]:
+
+ It is, and has always been, the explicit intent of the
+ HTTP specification that the interpretation of an HTTP message
+ header does not change between minor versions of the same major
+ version.
+
+ It is, and has always been, the explicit intent of the
+ HTTP specification that an implementation receiving a message
+ header that it does not understand MUST ignore that header. (The
+ word "ignore" has a special meaning for proxies; see section 2.1
+ below.)
+
+
+
+
+
+Mogul, et. al. Informational [Page 3]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+ To make this as clear as possible: The major version sent in a
+ message MAY indicate the interpretation of other header fields. The
+ minor version sent in a message MUST NOT indicate the interpretation
+ of other header fields. This reflects the principle that the minor
+ version labels the capability of the sender, not the interpretation
+ of the message.
+
+ Note: In a future version of HTTP, we may introduce a mechanism
+ that explicitly requires a receiving implementation to reject a
+ message if it does not understand certain headers. For example,
+ this might be implemented by means of a header that lists a set of
+ other message headers that must be understood by the recipient.
+ Any implementation claiming at least conditional compliance with
+ this future version of HTTP would have to implement this
+ mechanism. However, no implementation claiming compliance with a
+ lower HTTP version (in particular, HTTP/1.1) will have to
+ implement this mechanism.
+
+ This future change may be required to support the Protocol
+ Extension Protocol (PEP) [3].
+
+ One consequence of these rules is that an HTTP/1.1 message sent to an
+ HTTP/1.0 recipient (or a recipient whose version is unknown) MUST be
+ constructed so that it remains a valid HTTP/1.0 message when all
+ headers not defined in the HTTP/1.0 specification [1] are removed.
+
+2.1 Proxy behavior
+
+ A proxy MUST forward an unknown header, unless it is protected by a
+ Connection header. A proxy implementing an HTTP version >= 1.1 MUST
+ NOT forward unknown headers that are protected by a Connection
+ header, as described in section 14.10 of the HTTP/1.1 specification
+ [2].
+
+ We remind the reader that that HTTP version numbers are hop-by-hop
+ components of HTTP messages, and are not end-to-end. That is, an
+ HTTP proxy never "forwards" an HTTP version number in either a
+ request or response.
+
+2.2 Compatibility between minor versions of the same major version
+
+ An implementation of HTTP/x.b sending a message to a recipient whose
+ version is known to be HTTP/x.a, a < b, MAY send a header that is not
+ defined in the specification for HTTP/x.a. For example, an HTTP/1.1
+ server may send a "Cache-control" header to an HTTP/1.0 client; this
+ may be useful if the immediate recipient is an HTTP/1.0 proxy, but
+ the ultimate recipient is an HTTP/1.1 client.
+
+
+
+
+Mogul, et. al. Informational [Page 4]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+ An implementation of HTTP/x.b sending a message to a recipient whose
+ version is known to be HTTP/x.a, a < b, MUST NOT depend on the
+ recipient understanding a header not defined in the specification for
+ HTTP/x.a. For example, HTTP/1.0 clients cannot be expected to
+ understand chunked encodings, and so an HTTP/1.1 server must never
+ send "Transfer-Encoding: chunked" in response to an HTTP/1.0 request.
+
+2.3 Which version number to send in a message
+
+ The most strenuous debate over the use of HTTP version numbers has
+ centered on the problem of implementations that do not follow the
+ robustness principle, and which fail to produce useful results when
+ they receive a message with an HTTP minor version higher than the
+ minor version they implement. We consider these implementations
+ buggy, but we recognize that the robustness principle also implies
+ that message senders should make concessions to buggy implementations
+ when this is truly necessary for interoperation.
+
+ An HTTP client SHOULD send a request version equal to the highest
+ version for which the client is at least conditionally compliant, and
+ whose major version is no higher than the highest version supported
+ by the server, if this is known. An HTTP client MUST NOT send a
+ version for which it is not at least conditionally compliant.
+
+ An HTTP client MAY send a lower request version, if it is known that
+ the server incorrectly implements the HTTP specification, but only
+ after the client has determined that the server is actually buggy.
+
+ An HTTP server SHOULD send a response version equal to the highest
+ version for which the server is at least conditionally compliant, and
+ whose major version is less than or equal to the one received in the
+ request. An HTTP server MUST NOT send a version for which it is not
+ at least conditionally compliant. A server MAY send a 505 (HTTP
+ Version Not Supported) response if cannot send a response using the
+ major version used in the client's request.
+
+ An HTTP server MAY send a lower response version, if it is known or
+ suspected that the client incorrectly implements the HTTP
+ specification, but this should not be the default, and this SHOULD
+ NOT be done if the request version is HTTP/1.1 or greater.
+
+
+
+
+
+
+
+
+
+
+
+Mogul, et. al. Informational [Page 5]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+3 Security Considerations
+
+ None, except to the extent that security mechanisms introduced in one
+ version of HTTP might depend on the proper interpretation of HTTP
+ version numbers in older implementations.
+
+4 References
+
+ 1. Berners-Lee, T., R. Fielding, and H. Frystyk. Hypertext
+ Transfer Protocol -- HTTP/1.0. RFC 1945, HTTP Working Group, May,
+ 1996.
+
+ 2. Fielding, Roy T., Jim Gettys, Jeffrey C. Mogul, Henrik Frystyk
+ Nielsen, and Tim Berners-Lee. Hypertext Transfer Protocol --
+ HTTP/1.1. RFC 2068, HTTP Working Group, January, 1997.
+
+ 3. Khare, Rohit. HTTP/1.2 Extension Protocol (PEP). HTTP Working
+ Group, Work in Progress.
+
+ 4. Postel, Jon. Internet Protocol. RFC 791, NIC, September, 1981.
+
+5 Authors' addresses
+
+ Jeffrey C. Mogul
+ Western Research Laboratory
+ Digital Equipment Corporation
+ 250 University Avenue
+ Palo Alto, California, 94305, USA
+
+ Roy T. Fielding
+ Department of Information and Computer Science
+ University of California
+ Irvine, CA 92717-3425, USA
+ Fax: +1 (714) 824-4056
+
+ Jim Gettys
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+ Fax: +1 (617) 258 8682
+
+
+
+
+
+
+
+
+Mogul, et. al. Informational [Page 6]
+
+RFC 2145 HTTP Version Numbers May 1997
+
+
+ Henrik Frystyk Nielsen
+ W3 Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+ Fax: +1 (617) 258 8682
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mogul, et. al. Informational [Page 7]
+
diff --git a/lib/inets/doc/archive/rfc2428.txt b/lib/inets/doc/archive/rfc2428.txt
new file mode 100644
index 0000000000..a6ec3535ed
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2428.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Network Working Group M. Allman
+Request for Comments: 2428 NASA Lewis/Sterling Software
+Category: Standards Track S. Ostermann
+ Ohio University
+ C. Metz
+ The Inner Net
+ September 1998
+
+
+ FTP Extensions for IPv6 and NATs
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ The specification for the File Transfer Protocol assumes that the
+ underlying network protocol uses a 32-bit network address
+ (specifically IP version 4). With the deployment of version 6 of the
+ Internet Protocol, network addresses will no longer be 32-bits. This
+ paper specifies extensions to FTP that will allow the protocol to
+ work over IPv4 and IPv6. In addition, the framework defined can
+ support additional network protocols in the future.
+
+1. Introduction
+
+ The keywords, such as MUST and SHOULD, found in this document are
+ used as defined in RFC 2119 [Bra97].
+
+ The File Transfer Protocol [PR85] only provides the ability to
+ communicate information about IPv4 data connections. FTP assumes
+ network addresses will be 32 bits in length. However, with the
+ deployment of version 6 of the Internet Protocol [DH96] addresses
+ will no longer be 32 bits long. RFC 1639 [Pis94] specifies
+ extensions to FTP to enable its use over various network protocols.
+ Unfortunately, the mechanism can fail in a multi-protocol
+ environment. During the transition between IPv4 and IPv6, FTP needs
+ the ability to negotiate the network protocol that will be used for
+ data transfer.
+
+
+
+Allman, et. al. Standards Track [Page 1]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+ This document provides a specification for a way that FTP can
+ communicate data connection endpoint information for network
+ protocols other than IPv4. In this specification, the FTP commands
+ PORT and PASV are replaced with EPRT and EPSV, respectively. This
+ document is organized as follows. Section 2 outlines the EPRT
+ command and Section 3 outlines the EPSV command. Section 4 defines
+ the utilization of these two new FTP commands. Section 5 briefly
+ presents security considerations. Finally, Section 6 provides
+ conclusions.
+
+2. The EPRT Command
+
+ The EPRT command allows for the specification of an extended address
+ for the data connection. The extended address MUST consist of the
+ network protocol as well as the network and transport addresses. The
+ format of EPRT is:
+
+ EPRT<space><d><net-prt><d><net-addr><d><tcp-port><d>
+
+ The EPRT command keyword MUST be followed by a single space (ASCII
+ 32). Following the space, a delimiter character (<d>) MUST be
+ specified. The delimiter character MUST be one of the ASCII
+ characters in range 33-126 inclusive. The character "|" (ASCII 124)
+ is recommended unless it coincides with a character needed to encode
+ the network address.
+
+ The <net-prt> argument MUST be an address family number defined by
+ IANA in the latest Assigned Numbers RFC (RFC 1700 [RP94] as of the
+ writing of this document). This number indicates the protocol to be
+ used (and, implicitly, the address length). This document will use
+ two of address family numbers from [RP94] as examples, according to
+ the following table:
+
+ AF Number Protocol
+ --------- --------
+ 1 Internet Protocol, Version 4 [Pos81a]
+ 2 Internet Protocol, Version 6 [DH96]
+
+ The <net-addr> is a protocol specific string representation of the
+ network address. For the two address families specified above (AF
+ Number 1 and 2), addresses MUST be in the following format:
+
+ AF Number Address Format Example
+ --------- -------------- -------
+ 1 dotted decimal 132.235.1.2
+ 2 IPv6 string 1080::8:800:200C:417A
+ representations
+ defined in [HD96]
+
+
+
+Allman, et. al. Standards Track [Page 2]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+ The <tcp-port> argument must be the string representation of the
+ number of the TCP port on which the host is listening for the data
+ connection.
+
+ The following are sample EPRT commands:
+
+ EPRT |1|132.235.1.2|6275|
+
+ EPRT |2|1080::8:800:200C:417A|5282|
+
+ The first command specifies that the server should use IPv4 to open a
+ data connection to the host "132.235.1.2" on TCP port 6275. The
+ second command specifies that the server should use the IPv6 network
+ protocol and the network address "1080::8:800:200C:417A" to open a
+ TCP data connection on port 5282.
+
+ Upon receipt of a valid EPRT command, the server MUST return a code
+ of 200 (Command OK). The standard negative error code 500 and 501
+ [PR85] are sufficient to handle most errors (e.g., syntax errors)
+ involving the EPRT command. However, an additional error code is
+ needed. The response code 522 indicates that the server does not
+ support the requested network protocol. The interpretation of this
+ new error code is:
+
+ 5yz Negative Completion
+ x2z Connections
+ xy2 Extended Port Failure - unknown network protocol
+
+ The text portion of the response MUST indicate which network
+ protocols the server does support. If the network protocol is
+ unsupported, the format of the response string MUST be:
+
+ <text stating that the network protocol is unsupported> \
+ (prot1,prot2,...,protn)
+
+ Both the numeric code specified above and the protocol information
+ between the characters '(' and ')' are intended for the software
+ automata receiving the response; the textual message between the
+ numeric code and the '(' is intended for the human user and can be
+ any arbitrary text, but MUST NOT include the characters '(' and ')'.
+ In the above case, the text SHOULD indicate that the network protocol
+ in the EPRT command is not supported by the server. The list of
+ protocols inside the parenthesis MUST be a comma separated list of
+ address family numbers. Two example response strings follow:
+
+ Network protocol not supported, use (1)
+
+ Network protocol not supported, use (1,2)
+
+
+
+Allman, et. al. Standards Track [Page 3]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+3. The EPSV Command
+
+ The EPSV command requests that a server listen on a data port and
+ wait for a connection. The EPSV command takes an optional argument.
+ The response to this command includes only the TCP port number of the
+ listening connection. The format of the response, however, is
+ similar to the argument of the EPRT command. This allows the same
+ parsing routines to be used for both commands. In addition, the
+ format leaves a place holder for the network protocol and/or network
+ address, which may be needed in the EPSV response in the future. The
+ response code for entering passive mode using an extended address
+ MUST be 229. The interpretation of this code, according to [PR85]
+ is:
+
+ 2yz Positive Completion
+ x2z Connections
+ xy9 Extended Passive Mode Entered
+
+ The text returned in response to the EPSV command MUST be:
+
+ <text indicating server is entering extended passive mode> \
+ (<d><d><d><tcp-port><d>)
+
+ The portion of the string enclosed in parentheses MUST be the exact
+ string needed by the EPRT command to open the data connection, as
+ specified above.
+
+ The first two fields contained in the parenthesis MUST be blank. The
+ third field MUST be the string representation of the TCP port number
+ on which the server is listening for a data connection. The network
+ protocol used by the data connection will be the same network
+ protocol used by the control connection. In addition, the network
+ address used to establish the data connection will be the same
+ network address used for the control connection. An example response
+ string follows:
+
+ Entering Extended Passive Mode (|||6446|)
+
+ The standard negative error codes 500 and 501 are sufficient to
+ handle all errors involving the EPSV command (e.g., syntax errors).
+
+ When the EPSV command is issued with no argument, the server will
+ choose the network protocol for the data connection based on the
+ protocol used for the control connection. However, in the case of
+ proxy FTP, this protocol might not be appropriate for communication
+ between the two servers. Therefore, the client needs to be able to
+ request a specific protocol. If the server returns a protocol that
+ is not supported by the host that will be connecting to the port, the
+
+
+
+Allman, et. al. Standards Track [Page 4]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+ client MUST issue an ABOR (abort) command to allow the server to
+ close down the listening connection. The client can then send an
+ EPSV command requesting the use of a specific network protocol, as
+ follows:
+
+ EPSV<space><net-prt>
+
+ If the requested protocol is supported by the server, it SHOULD use
+ the protocol. If not, the server MUST return the 522 error messages
+ as outlined in section 2.
+
+ Finally, the EPSV command can be used with the argument "ALL" to
+ inform Network Address Translators that the EPRT command (as well as
+ other data commands) will no longer be used. An example of this
+ command follows:
+
+ EPSV<space>ALL
+
+ Upon receipt of an EPSV ALL command, the server MUST reject all data
+ connection setup commands other than EPSV (i.e., EPRT, PORT, PASV, et
+ al.). This use of the EPSV command is further explained in section
+ 4.
+
+4. Command Usage
+
+ For all FTP transfers where the control and data connection(s) are
+ being established between the same two machines, the EPSV command
+ MUST be used. Using the EPSV command benefits performance of
+ transfers that traverse firewalls or Network Address Translators
+ (NATs). RFC 1579 [Bel94] recommends using the passive command when
+ behind firewalls since firewalls do not generally allow incoming
+ connections (which are required when using the PORT (EPRT) command).
+ In addition, using EPSV as defined in this document does not require
+ NATs to change the network address in the traffic as it is forwarded.
+ The NAT would have to change the address if the EPRT command was
+ used. Finally, if the client issues an "EPSV ALL" command, NATs may
+ be able to put the connection on a "fast path" through the
+ translator, as the EPRT command will never be used and therefore,
+ translation of the data portion of the segments will never be needed.
+ When a client only expects to do two-way FTP transfers, it SHOULD
+ issue this command as soon as possible. If a client later finds that
+ it must do a three-way FTP transfer after issuing an EPSV ALL
+ command, a new FTP session MUST be started.
+
+
+
+
+
+
+
+
+Allman, et. al. Standards Track [Page 5]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+5. Security Issues
+
+ The authors do not believe that these changes to FTP introduce new
+ security problems. A companion Work in Progress [AO98] is a more
+ general discussion of FTP security issues and techniques to reduce
+ these security problems.
+
+6. Conclusions
+
+ The extensions specified in this paper will enable FTP to operate
+ over a variety of network protocols.
+
+References
+
+ [AO98] Allman, M., and S. Ostermann, "FTP Security
+ Considerations", Work in Progress.
+
+ [Bel94] Bellovin, S., "Firewall-Friendly FTP", RFC 1579, February
+ 1994.
+
+ [Bra97] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [DH96] Deering, S., and R. Hinden, "Internet Protocol, Version 6
+ (IPv6) Specification", RFC 1883, December 1995.
+
+ [HD96] Hinden, R., and S. Deering, "IP Version 6 Addressing
+ Architecture", RFC 2373, July 1998.
+
+ [Pis94] Piscitello, D., "FTP Operation Over Big Address Records
+ (FOOBAR)", RFC 1639, June 1994.
+
+ [Pos81a] Postel, J., "Internet Protocol", STD 5, RFC 791, September
+ 1981.
+
+ [Pos81b] Postel, J., "Transmission Control Protocol", STD 7, RFC 793,
+ September 1981.
+
+ [PR85] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)",
+ STD 9, RFC 959, October 1985.
+
+ [RP94] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC
+ 1700, October 1994. See also:
+ http://www.iana.org/numbers.html
+
+
+
+
+
+
+
+Allman, et. al. Standards Track [Page 6]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+Authors' Addresses
+
+ Mark Allman
+ NASA Lewis Research Center/Sterling Software
+ 21000 Brookpark Rd. MS 54-2
+ Cleveland, OH 44135
+
+ Phone: (216) 433-6586
+ http://gigahertz.lerc.nasa.gov/~mallman/
+
+
+ Shawn Ostermann
+ School of Electrical Engineering and Computer Science
+ Ohio University
+ 416 Morton Hall
+ Athens, OH 45701
+
+ Phone: (740) 593-1234
+
+
+ Craig Metz
+ The Inner Net
+ Box 10314-1954
+ Blacksburg, VA 24062-0314
+
+ Phone: (DSN) 754-8590
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Allman, et. al. Standards Track [Page 7]
+
+RFC 2428 FTP Extensions for IPv6 and NATs September 1998
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Allman, et. al. Standards Track [Page 8]
+
diff --git a/lib/inets/doc/archive/rfc2577.txt b/lib/inets/doc/archive/rfc2577.txt
new file mode 100644
index 0000000000..83ba203130
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2577.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Network Working Group M. Allman
+Request for Comments: 2577 NASA Glenn/Sterling Software
+Category: Informational S. Ostermann
+ Ohio University
+ May 1999
+
+
+ FTP Security Considerations
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ The specification for the File Transfer Protocol (FTP) contains a
+ number of mechanisms that can be used to compromise network security.
+ The FTP specification allows a client to instruct a server to
+ transfer files to a third machine. This third-party mechanism, known
+ as proxy FTP, causes a well known security problem. The FTP
+ specification also allows an unlimited number of attempts at entering
+ a user's password. This allows brute force "password guessing"
+ attacks. This document provides suggestions for system
+ administrators and those implementing FTP servers that will decrease
+ the security problems associated with FTP.
+
+1 Introduction
+
+ The File Transfer Protocol specification (FTP) [PR85] provides a
+ mechanism that allows a client to establish an FTP control connection
+ and transfer a file between two FTP servers. This "proxy FTP"
+ mechanism can be used to decrease the amount of traffic on the
+ network; the client instructs one server to transfer a file to
+ another server, rather than transferring the file from the first
+ server to the client and then from the client to the second server.
+ This is particularly useful when the client connects to the network
+ using a slow link (e.g., a modem). While useful, proxy FTP provides
+ a security problem known as a "bounce attack" [CERT97:27]. In
+ addition to the bounce attack, FTP servers can be used by attackers
+ to guess passwords using brute force.
+
+
+
+
+
+Allman & Ostermann Informational [Page 1]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ This document does not contain a discussion of FTP when used in
+ conjunction with strong security protocols, such as IP Security.
+ These security concerns should be documented, however they are out of
+ the scope of this document.
+
+ This paper provides information for FTP server implementers and
+ system administrators, as follows. Section 2 describes the FTP
+ "bounce attack". Section 3 provides suggestions for minimizing the
+ bounce attack. Section 4 provides suggestions for servers which
+ limit access based on network address. Section 5 provides
+ recommendations for limiting brute force "password guessing" by
+ clients. Next, section 6 provides a brief discussion of mechanisms
+ to improve privacy. Section 7 provides a mechanism to prevent user
+ identity guessing. Section 8 discusses the practice of port
+ stealing. Finally, section 9 provides an overview of other FTP
+ security issues related to software bugs rather than protocol issues.
+
+2 The Bounce Attack
+
+ The version of FTP specified in the standard [PR85] provides a method
+ for attacking well known network servers, while making the
+ perpetrators difficult to track down. The attack involves sending an
+ FTP "PORT" command to an FTP server containing the network address
+ and the port number of the machine and service being attacked. At
+ this point, the original client can instruct the FTP server to send a
+ file to the service being attacked. Such a file would contain
+ commands relevant to the service being attacked (SMTP, NNTP, etc.).
+ Instructing a third party to connect to the service, rather than
+ connecting directly, makes tracking down the perpetrator difficult
+ and can circumvent network-address-based access restrictions.
+
+ As an example, a client uploads a file containing SMTP commands to an
+ FTP server. Then, using an appropriate PORT command, the client
+ instructs the server to open a connection to a third machine's SMTP
+ port. Finally, the client instructs the server to transfer the
+ uploaded file containing SMTP commands to the third machine. This
+ may allow the client to forge mail on the third machine without
+ making a direct connection. This makes it difficult to track
+ attackers.
+
+3 Protecting Against the Bounce Attack
+
+ The original FTP specification [PR85] assumes that data connections
+ will be made using the Transmission Control Protocol (TCP) [Pos81].
+ TCP port numbers in the range 0 - 1023 are reserved for well known
+ services such as mail, network news and FTP control connections
+ [RP94]. The FTP specification makes no restrictions on the TCP port
+ number used for the data connection. Therefore, using proxy FTP,
+
+
+
+Allman & Ostermann Informational [Page 2]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ clients have the ability to tell the server to attack a well known
+ service on any machine.
+
+ To avoid such bounce attacks, it is suggested that servers not open
+ data connections to TCP ports less than 1024. If a server receives a
+ PORT command containing a TCP port number less than 1024, the
+ suggested response is 504 (defined as "Command not implemented for
+ that parameter" by [PR85]). Note that this still leaves non-well
+ known servers (those running on ports greater than 1023) vulnerable
+ to bounce attacks.
+
+ Several proposals (e.g., [AOM98] and [Pis94]) provide a mechanism
+ that would allow data connections to be made using a transport
+ protocol other than TCP. Similar precautions should be taken to
+ protect well known services when using these protocols.
+
+ Also note that the bounce attack generally requires that a
+ perpetrator be able to upload a file to an FTP server and later
+ download it to the service being attacked. Using proper file
+ protections will prevent this behavior. However, attackers can also
+ attack services by sending random data from a remote FTP server which
+ may cause problems for some services.
+
+ Disabling the PORT command is also an option for protecting against
+ the bounce attack. Most file transfers can be made using only the
+ PASV command [Bel94]. The disadvantage of disabling the PORT command
+ is that one loses the ability to use proxy FTP, but proxy FTP may not
+ be necessary in a particular environment.
+
+4 Restricted Access
+
+ For some FTP servers, it is desirable to restrict access based on
+ network address. For example, a server might want to restrict access
+ to certain files from certain places (e.g., a certain file should not
+ be transferred out of an organization). In such a situation, the
+ server should confirm that the network address of the remote hosts on
+ both the control connection and the data connection are within the
+ organization before sending a restricted file. By checking both
+ connections, a server is protected against the case when the control
+ connection is established with a trusted host and the data connection
+ is not. Likewise, the client should verify the IP address of the
+ remote host after accepting a connection on a port opened in listen
+ mode to verify that the connection was made by the expected server.
+
+ Note that restricting access based on network address leaves the FTP
+ server vulnerable to "spoof" attacks. In a spoof attack, for
+ example, an attacking machine could assume the host address of
+ another machine inside an organization and download files that are
+
+
+
+Allman & Ostermann Informational [Page 3]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ not accessible from outside the organization. Whenever possible,
+ secure authentication mechanisms should be used, such as those
+ outlined in [HL97].
+
+5 Protecting Passwords
+
+ To minimize the risk of brute force password guessing through the FTP
+ server, it is suggested that servers limit the number of attempts
+ that can be made at sending a correct password. After a small number
+ of attempts (3-5), the server should close the control connection
+ with the client. Before closing the control connection the server
+ must send a return code of 421 ("Service not available, closing
+ control connection." [PR85]) to the client. In addition, it is
+ suggested that the server impose a 5 second delay before replying to
+ an invalid "PASS" command to diminish the efficiency of a brute force
+ attack. If available, mechanisms already provided by the target
+ operating system should be used to implement the above suggestions.
+
+ An intruder can subvert the above mechanisms by establishing
+ multiple, parallel control connections to a server. To combat the
+ use of multiple concurrent connections, the server could either limit
+ the total number of control connections possible or attempt to detect
+ suspicious activity across sessions and refuse further connections
+ from the site. However, both of these mechanisms open the door to
+ "denial of service" attacks, in which an attacker purposely initiates
+ the attack to disable access by a valid user.
+
+ Standard FTP [PR85] sends passwords in clear text using the "PASS"
+ command. It is suggested that FTP clients and servers use alternate
+ authentication mechanisms that are not subject to eavesdropping (such
+ as the mechanisms being developed by the IETF Common Authentication
+ Technology Working Group [HL97]).
+
+6 Privacy
+
+ All data and control information (including passwords) is sent across
+ the network in unencrypted form by standard FTP [PR85]. To guarantee
+ the privacy of the information FTP transmits, a strong encryption
+ scheme should be used whenever possible. One such mechanism is
+ defined in [HL97].
+
+7 Protecting Usernames
+
+ Standard FTP [PR85] specifies a 530 response to the USER command when
+ the username is rejected. If the username is valid and a password is
+ required FTP returns a 331 response instead. In order to prevent a
+ malicious client from determining valid usernames on a server, it is
+ suggested that a server always return 331 to the USER command and
+
+
+
+Allman & Ostermann Informational [Page 4]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ then reject the combination of username and password for an invalid
+ username.
+
+8 Port Stealing
+
+ Many operating systems assign dynamic port numbers in increasing
+ order. By making a legitimate transfer, an attacker can observe the
+ current port number allocated by the server and "guess" the next one
+ that will be used. The attacker can make a connection to this port,
+ thus denying another legitimate client the ability to make a
+ transfer. Alternatively, the attacker can steal a file meant for a
+ legitimate user. In addition, an attacker can insert a forged file
+ into a data stream thought to come from an authenticated client.
+ This problem can be mitigated by making FTP clients and servers use
+ random local port numbers for data connections, either by requesting
+ random ports from the operating system or using system dependent
+ mechanisms.
+
+9 Software-Base Security Problems
+
+ The emphasis in this document is on protocol-related security issues.
+ There are a number of documented FTP security-related problems that
+ are due to poor implementation as well. Although the details of
+ these types of problems are beyond the scope of this document, it
+ should be pointed out that the following FTP features has been abused
+ in the past and should be treated with great care by future
+ implementers:
+
+ Anonymous FTP
+
+ Anonymous FTP refers to the ability of a client to connect to an
+ FTP server with minimal authentication and gain access to public
+ files. Security problems arise when such a user can read all
+ files on the system or can create files. [CERT92:09] [CERT93:06]
+
+ Remote Command Execution
+
+ An optional FTP extension, "SITE EXEC", allows clients to execute
+ arbitrary commands on the server. This feature should obviously
+ be implemented with great care. There are several documented
+ cases of the FTP "SITE EXEC" command being used to subvert server
+ security [CERT94:08] [CERT95:16]
+
+ Debug Code
+
+ Several previous security compromises related to FTP can be
+ attributed to software that was installed with debugging features
+ enabled [CERT88:01].
+
+
+
+Allman & Ostermann Informational [Page 5]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ This document recommends that implementors of FTP servers with these
+ capabilities review all of the CERT advisories for attacks on these
+ or similar mechanisms before releasing their software.
+
+10 Conclusion
+
+ Using the above suggestions can decrease the security problems
+ associated with FTP servers without eliminating functionality.
+
+11 Security Considerations
+
+ Security issues are discussed throughout this memo.
+
+Acknowledgments
+
+ We would like to thank Alex Belits, Jim Bound, William Curtin, Robert
+ Elz, Paul Hethmon, Alun Jones and Stephen Tihor for their helpful
+ comments on this paper. Also, we thank the FTPEXT WG members who
+ gave many useful suggestions at the Memphis IETF meeting.
+
+References
+
+ [AOM98] Allman, M., Ostermann, S. and C. Metz, "FTP Extensions
+ for IPv6 and NATs", RFC 2428, September 1998.
+
+ [Bel94] Bellovin. S., "Firewall-Friendly FTP", RFC 1579, February
+ 1994.
+
+ [CERT88:01] CERT Advisory CA-88:01. ftpd Vulnerability. December,
+ 1988 ftp://info.cert.org/pub/cert_advisories/
+
+ [CERT92:09] CERT Advisory CA-92:09. AIX Anonymous FTP Vulnerability.
+ April 27, 1992. ftp://info.cert.org/pub/cert_advisories/
+
+ [CERT93:06] CERT Advisory CA-93:06. Wuarchive ftpd Vulnerability.
+ September 19,1997
+ ftp://info.cert.org/pub/cert_advisories/
+
+ [CERT94:08] CERT Advisory CA-94:08. ftpd Vulnerabilities. September
+ 23, 1997. ftp://info.cert.org/pub/cert_advisories/
+
+ [CERT95:16] CERT Advisory CA-95:16. wu-ftpd Misconfiguration
+ Vulnerability. September 23, 1997
+ ftp://info.cert.org/pub/cert_advisories/
+
+ [CERT97:27] CERT Advisory CA-97.27. FTP Bounce. January 8, 1998.
+ ftp://info.cert.org/pub/cert_advisories/
+
+
+
+
+Allman & Ostermann Informational [Page 6]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+ [HL97] Horowitz, M. and S. Lunt, "FTP Security Extensions", RFC
+ 2228, October 1997.
+
+ [Pis94] Piscitello, D., "FTP Operation Over Big Address Records
+ (FOOBAR), RFC 1639, June 1994.
+
+ [Pos81] Postel, J., "Transmission Control Protocol", STD 7, RFC
+ 793, September 1981.
+
+ [PR85] Postel, J. and J. Reynolds, "File Transfer Protocol
+ (FTP)", STD 9, RFC 959, October 1985.
+
+ [RP94] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2,
+ RFC 1700, October 1994. See also:
+ http://www.iana.org/numbers.html
+
+Authors' Addresses
+
+ Mark Allman
+ NASA Glenn Research Center/Sterling Software
+ 21000 Brookpark Rd. MS 54-2
+ Cleveland, OH 44135
+
+
+
+ Shawn Ostermann
+ School of Electrical Engineering and Computer Science
+ Ohio University
+ 416 Morton Hall
+ Athens, OH 45701
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Allman & Ostermann Informational [Page 7]
+
+RFC 2577 FTP Security Considerations May 1999
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Allman & Ostermann Informational [Page 8]
+
diff --git a/lib/inets/doc/archive/rfc2616.pdf b/lib/inets/doc/archive/rfc2616.pdf
new file mode 100644
index 0000000000..d3d4bae2c8
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2616.pdf
Binary files differ
diff --git a/lib/inets/doc/archive/rfc2616.txt b/lib/inets/doc/archive/rfc2616.txt
new file mode 100644
index 0000000000..45d7d08b8f
--- /dev/null
+++ b/lib/inets/doc/archive/rfc2616.txt
@@ -0,0 +1,9859 @@
+
+
+
+
+
+
+Network Working Group R. Fielding
+Request for Comments: 2616 UC Irvine
+Obsoletes: 2068 J. Gettys
+Category: Standards Track Compaq/W3C
+ J. Mogul
+ Compaq
+ H. Frystyk
+ W3C/MIT
+ L. Masinter
+ Xerox
+ P. Leach
+ Microsoft
+ T. Berners-Lee
+ W3C/MIT
+ June 1999
+
+
+ Hypertext Transfer Protocol -- HTTP/1.1
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. It is a generic, stateless, protocol which can be used for
+ many tasks beyond its use for hypertext, such as name servers and
+ distributed object management systems, through extension of its
+ request methods, error codes and headers [47]. A feature of HTTP is
+ the typing and negotiation of data representation, allowing systems
+ to be built independently of the data being transferred.
+
+ HTTP has been in use by the World-Wide Web global information
+ initiative since 1990. This specification defines the protocol
+ referred to as "HTTP/1.1", and is an update to RFC 2068 [33].
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 1]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+Table of Contents
+
+ 1 Introduction ...................................................7
+ 1.1 Purpose......................................................7
+ 1.2 Requirements .................................................8
+ 1.3 Terminology ..................................................8
+ 1.4 Overall Operation ...........................................12
+ 2 Notational Conventions and Generic Grammar ....................14
+ 2.1 Augmented BNF ...............................................14
+ 2.2 Basic Rules .................................................15
+ 3 Protocol Parameters ...........................................17
+ 3.1 HTTP Version ................................................17
+ 3.2 Uniform Resource Identifiers ................................18
+ 3.2.1 General Syntax ...........................................19
+ 3.2.2 http URL .................................................19
+ 3.2.3 URI Comparison ...........................................20
+ 3.3 Date/Time Formats ...........................................20
+ 3.3.1 Full Date ................................................20
+ 3.3.2 Delta Seconds ............................................21
+ 3.4 Character Sets ..............................................21
+ 3.4.1 Missing Charset ..........................................22
+ 3.5 Content Codings .............................................23
+ 3.6 Transfer Codings ............................................24
+ 3.6.1 Chunked Transfer Coding ..................................25
+ 3.7 Media Types .................................................26
+ 3.7.1 Canonicalization and Text Defaults .......................27
+ 3.7.2 Multipart Types ..........................................27
+ 3.8 Product Tokens ..............................................28
+ 3.9 Quality Values ..............................................29
+ 3.10 Language Tags ...............................................29
+ 3.11 Entity Tags .................................................30
+ 3.12 Range Units .................................................30
+ 4 HTTP Message ..................................................31
+ 4.1 Message Types ...............................................31
+ 4.2 Message Headers .............................................31
+ 4.3 Message Body ................................................32
+ 4.4 Message Length ..............................................33
+ 4.5 General Header Fields .......................................34
+ 5 Request .......................................................35
+ 5.1 Request-Line ................................................35
+ 5.1.1 Method ...................................................36
+ 5.1.2 Request-URI ..............................................36
+ 5.2 The Resource Identified by a Request ........................38
+ 5.3 Request Header Fields .......................................38
+ 6 Response ......................................................39
+ 6.1 Status-Line .................................................39
+ 6.1.1 Status Code and Reason Phrase ............................39
+ 6.2 Response Header Fields ......................................41
+
+
+
+Fielding, et al. Standards Track [Page 2]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 7 Entity ........................................................42
+ 7.1 Entity Header Fields ........................................42
+ 7.2 Entity Body .................................................43
+ 7.2.1 Type .....................................................43
+ 7.2.2 Entity Length ............................................43
+ 8 Connections ...................................................44
+ 8.1 Persistent Connections ......................................44
+ 8.1.1 Purpose ..................................................44
+ 8.1.2 Overall Operation ........................................45
+ 8.1.3 Proxy Servers ............................................46
+ 8.1.4 Practical Considerations .................................46
+ 8.2 Message Transmission Requirements ...........................47
+ 8.2.1 Persistent Connections and Flow Control ..................47
+ 8.2.2 Monitoring Connections for Error Status Messages .........48
+ 8.2.3 Use of the 100 (Continue) Status .........................48
+ 8.2.4 Client Behavior if Server Prematurely Closes Connection ..50
+ 9 Method Definitions ............................................51
+ 9.1 Safe and Idempotent Methods .................................51
+ 9.1.1 Safe Methods .............................................51
+ 9.1.2 Idempotent Methods .......................................51
+ 9.2 OPTIONS .....................................................52
+ 9.3 GET .........................................................53
+ 9.4 HEAD ........................................................54
+ 9.5 POST ........................................................54
+ 9.6 PUT .........................................................55
+ 9.7 DELETE ......................................................56
+ 9.8 TRACE .......................................................56
+ 9.9 CONNECT .....................................................57
+ 10 Status Code Definitions ......................................57
+ 10.1 Informational 1xx ...........................................57
+ 10.1.1 100 Continue .............................................58
+ 10.1.2 101 Switching Protocols ..................................58
+ 10.2 Successful 2xx ..............................................58
+ 10.2.1 200 OK ...................................................58
+ 10.2.2 201 Created ..............................................59
+ 10.2.3 202 Accepted .............................................59
+ 10.2.4 203 Non-Authoritative Information ........................59
+ 10.2.5 204 No Content ...........................................60
+ 10.2.6 205 Reset Content ........................................60
+ 10.2.7 206 Partial Content ......................................60
+ 10.3 Redirection 3xx .............................................61
+ 10.3.1 300 Multiple Choices .....................................61
+ 10.3.2 301 Moved Permanently ....................................62
+ 10.3.3 302 Found ................................................62
+ 10.3.4 303 See Other ............................................63
+ 10.3.5 304 Not Modified .........................................63
+ 10.3.6 305 Use Proxy ............................................64
+ 10.3.7 306 (Unused) .............................................64
+
+
+
+Fielding, et al. Standards Track [Page 3]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 10.3.8 307 Temporary Redirect ...................................65
+ 10.4 Client Error 4xx ............................................65
+ 10.4.1 400 Bad Request .........................................65
+ 10.4.2 401 Unauthorized ........................................66
+ 10.4.3 402 Payment Required ....................................66
+ 10.4.4 403 Forbidden ...........................................66
+ 10.4.5 404 Not Found ...........................................66
+ 10.4.6 405 Method Not Allowed ..................................66
+ 10.4.7 406 Not Acceptable ......................................67
+ 10.4.8 407 Proxy Authentication Required .......................67
+ 10.4.9 408 Request Timeout .....................................67
+ 10.4.10 409 Conflict ............................................67
+ 10.4.11 410 Gone ................................................68
+ 10.4.12 411 Length Required .....................................68
+ 10.4.13 412 Precondition Failed .................................68
+ 10.4.14 413 Request Entity Too Large ............................69
+ 10.4.15 414 Request-URI Too Long ................................69
+ 10.4.16 415 Unsupported Media Type ..............................69
+ 10.4.17 416 Requested Range Not Satisfiable .....................69
+ 10.4.18 417 Expectation Failed ..................................70
+ 10.5 Server Error 5xx ............................................70
+ 10.5.1 500 Internal Server Error ................................70
+ 10.5.2 501 Not Implemented ......................................70
+ 10.5.3 502 Bad Gateway ..........................................70
+ 10.5.4 503 Service Unavailable ..................................70
+ 10.5.5 504 Gateway Timeout ......................................71
+ 10.5.6 505 HTTP Version Not Supported ...........................71
+ 11 Access Authentication ........................................71
+ 12 Content Negotiation ..........................................71
+ 12.1 Server-driven Negotiation ...................................72
+ 12.2 Agent-driven Negotiation ....................................73
+ 12.3 Transparent Negotiation .....................................74
+ 13 Caching in HTTP ..............................................74
+ 13.1.1 Cache Correctness ........................................75
+ 13.1.2 Warnings .................................................76
+ 13.1.3 Cache-control Mechanisms .................................77
+ 13.1.4 Explicit User Agent Warnings .............................78
+ 13.1.5 Exceptions to the Rules and Warnings .....................78
+ 13.1.6 Client-controlled Behavior ...............................79
+ 13.2 Expiration Model ............................................79
+ 13.2.1 Server-Specified Expiration ..............................79
+ 13.2.2 Heuristic Expiration .....................................80
+ 13.2.3 Age Calculations .........................................80
+ 13.2.4 Expiration Calculations ..................................83
+ 13.2.5 Disambiguating Expiration Values .........................84
+ 13.2.6 Disambiguating Multiple Responses ........................84
+ 13.3 Validation Model ............................................85
+ 13.3.1 Last-Modified Dates ......................................86
+
+
+
+Fielding, et al. Standards Track [Page 4]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 13.3.2 Entity Tag Cache Validators ..............................86
+ 13.3.3 Weak and Strong Validators ...............................86
+ 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates.89
+ 13.3.5 Non-validating Conditionals ..............................90
+ 13.4 Response Cacheability .......................................91
+ 13.5 Constructing Responses From Caches ..........................92
+ 13.5.1 End-to-end and Hop-by-hop Headers ........................92
+ 13.5.2 Non-modifiable Headers ...................................92
+ 13.5.3 Combining Headers ........................................94
+ 13.5.4 Combining Byte Ranges ....................................95
+ 13.6 Caching Negotiated Responses ................................95
+ 13.7 Shared and Non-Shared Caches ................................96
+ 13.8 Errors or Incomplete Response Cache Behavior ................97
+ 13.9 Side Effects of GET and HEAD ................................97
+ 13.10 Invalidation After Updates or Deletions ...................97
+ 13.11 Write-Through Mandatory ...................................98
+ 13.12 Cache Replacement .........................................99
+ 13.13 History Lists .............................................99
+ 14 Header Field Definitions ....................................100
+ 14.1 Accept .....................................................100
+ 14.2 Accept-Charset .............................................102
+ 14.3 Accept-Encoding ............................................102
+ 14.4 Accept-Language ............................................104
+ 14.5 Accept-Ranges ..............................................105
+ 14.6 Age ........................................................106
+ 14.7 Allow ......................................................106
+ 14.8 Authorization ..............................................107
+ 14.9 Cache-Control ..............................................108
+ 14.9.1 What is Cacheable .......................................109
+ 14.9.2 What May be Stored by Caches ............................110
+ 14.9.3 Modifications of the Basic Expiration Mechanism .........111
+ 14.9.4 Cache Revalidation and Reload Controls ..................113
+ 14.9.5 No-Transform Directive ..................................115
+ 14.9.6 Cache Control Extensions ................................116
+ 14.10 Connection ...............................................117
+ 14.11 Content-Encoding .........................................118
+ 14.12 Content-Language .........................................118
+ 14.13 Content-Length ...........................................119
+ 14.14 Content-Location .........................................120
+ 14.15 Content-MD5 ..............................................121
+ 14.16 Content-Range ............................................122
+ 14.17 Content-Type .............................................124
+ 14.18 Date .....................................................124
+ 14.18.1 Clockless Origin Server Operation ......................125
+ 14.19 ETag .....................................................126
+ 14.20 Expect ...................................................126
+ 14.21 Expires ..................................................127
+ 14.22 From .....................................................128
+
+
+
+Fielding, et al. Standards Track [Page 5]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 14.23 Host .....................................................128
+ 14.24 If-Match .................................................129
+ 14.25 If-Modified-Since ........................................130
+ 14.26 If-None-Match ............................................132
+ 14.27 If-Range .................................................133
+ 14.28 If-Unmodified-Since ......................................134
+ 14.29 Last-Modified ............................................134
+ 14.30 Location .................................................135
+ 14.31 Max-Forwards .............................................136
+ 14.32 Pragma ...................................................136
+ 14.33 Proxy-Authenticate .......................................137
+ 14.34 Proxy-Authorization ......................................137
+ 14.35 Range ....................................................138
+ 14.35.1 Byte Ranges ...........................................138
+ 14.35.2 Range Retrieval Requests ..............................139
+ 14.36 Referer ..................................................140
+ 14.37 Retry-After ..............................................141
+ 14.38 Server ...................................................141
+ 14.39 TE .......................................................142
+ 14.40 Trailer ..................................................143
+ 14.41 Transfer-Encoding..........................................143
+ 14.42 Upgrade ..................................................144
+ 14.43 User-Agent ...............................................145
+ 14.44 Vary .....................................................145
+ 14.45 Via ......................................................146
+ 14.46 Warning ..................................................148
+ 14.47 WWW-Authenticate .........................................150
+ 15 Security Considerations .......................................150
+ 15.1 Personal Information....................................151
+ 15.1.1 Abuse of Server Log Information .........................151
+ 15.1.2 Transfer of Sensitive Information .......................151
+ 15.1.3 Encoding Sensitive Information in URI's .................152
+ 15.1.4 Privacy Issues Connected to Accept Headers ..............152
+ 15.2 Attacks Based On File and Path Names .......................153
+ 15.3 DNS Spoofing ...............................................154
+ 15.4 Location Headers and Spoofing ..............................154
+ 15.5 Content-Disposition Issues .................................154
+ 15.6 Authentication Credentials and Idle Clients ................155
+ 15.7 Proxies and Caching ........................................155
+ 15.7.1 Denial of Service Attacks on Proxies....................156
+ 16 Acknowledgments .............................................156
+ 17 References ..................................................158
+ 18 Authors' Addresses ..........................................162
+ 19 Appendices ..................................................164
+ 19.1 Internet Media Type message/http and application/http ......164
+ 19.2 Internet Media Type multipart/byteranges ...................165
+ 19.3 Tolerant Applications ......................................166
+ 19.4 Differences Between HTTP Entities and RFC 2045 Entities ....167
+
+
+
+Fielding, et al. Standards Track [Page 6]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 19.4.1 MIME-Version ............................................167
+ 19.4.2 Conversion to Canonical Form ............................167
+ 19.4.3 Conversion of Date Formats ..............................168
+ 19.4.4 Introduction of Content-Encoding ........................168
+ 19.4.5 No Content-Transfer-Encoding ............................168
+ 19.4.6 Introduction of Transfer-Encoding .......................169
+ 19.4.7 MHTML and Line Length Limitations .......................169
+ 19.5 Additional Features ........................................169
+ 19.5.1 Content-Disposition .....................................170
+ 19.6 Compatibility with Previous Versions .......................170
+ 19.6.1 Changes from HTTP/1.0 ...................................171
+ 19.6.2 Compatibility with HTTP/1.0 Persistent Connections ......172
+ 19.6.3 Changes from RFC 2068 ...................................172
+ 20 Index .......................................................175
+ 21 Full Copyright Statement ....................................176
+
+1 Introduction
+
+1.1 Purpose
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. HTTP has been in use by the World-Wide Web global
+ information initiative since 1990. The first version of HTTP,
+ referred to as HTTP/0.9, was a simple protocol for raw data transfer
+ across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved
+ the protocol by allowing messages to be in the format of MIME-like
+ messages, containing metainformation about the data transferred and
+ modifiers on the request/response semantics. However, HTTP/1.0 does
+ not sufficiently take into consideration the effects of hierarchical
+ proxies, caching, the need for persistent connections, or virtual
+ hosts. In addition, the proliferation of incompletely-implemented
+ applications calling themselves "HTTP/1.0" has necessitated a
+ protocol version change in order for two communicating applications
+ to determine each other's true capabilities.
+
+ This specification defines the protocol referred to as "HTTP/1.1".
+ This protocol includes more stringent requirements than HTTP/1.0 in
+ order to ensure reliable implementation of its features.
+
+ Practical information systems require more functionality than simple
+ retrieval, including search, front-end update, and annotation. HTTP
+ allows an open-ended set of methods and headers that indicate the
+ purpose of a request [47]. It builds on the discipline of reference
+ provided by the Uniform Resource Identifier (URI) [3], as a location
+ (URL) [4] or name (URN) [20], for indicating the resource to which a
+
+
+
+
+
+Fielding, et al. Standards Track [Page 7]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ method is to be applied. Messages are passed in a format similar to
+ that used by Internet mail [9] as defined by the Multipurpose
+ Internet Mail Extensions (MIME) [7].
+
+ HTTP is also used as a generic protocol for communication between
+ user agents and proxies/gateways to other Internet systems, including
+ those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2],
+ and WAIS [10] protocols. In this way, HTTP allows basic hypermedia
+ access to resources available from diverse applications.
+
+1.2 Requirements
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [34].
+
+ An implementation is not compliant if it fails to satisfy one or more
+ of the MUST or REQUIRED level requirements for the protocols it
+ implements. An implementation that satisfies all the MUST or REQUIRED
+ level and all the SHOULD level requirements for its protocols is said
+ to be "unconditionally compliant"; one that satisfies all the MUST
+ level requirements but not all the SHOULD level requirements for its
+ protocols is said to be "conditionally compliant."
+
+1.3 Terminology
+
+ This specification uses a number of terms to refer to the roles
+ played by participants in, and objects of, the HTTP communication.
+
+ connection
+ A transport layer virtual circuit established between two programs
+ for the purpose of communication.
+
+ message
+ The basic unit of HTTP communication, consisting of a structured
+ sequence of octets matching the syntax defined in section 4 and
+ transmitted via the connection.
+
+ request
+ An HTTP request message, as defined in section 5.
+
+ response
+ An HTTP response message, as defined in section 6.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 8]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ resource
+ A network data object or service that can be identified by a URI,
+ as defined in section 3.2. Resources may be available in multiple
+ representations (e.g. multiple languages, data formats, size, and
+ resolutions) or vary in other ways.
+
+ entity
+ The information transferred as the payload of a request or
+ response. An entity consists of metainformation in the form of
+ entity-header fields and content in the form of an entity-body, as
+ described in section 7.
+
+ representation
+ An entity included with a response that is subject to content
+ negotiation, as described in section 12. There may exist multiple
+ representations associated with a particular response status.
+
+ content negotiation
+ The mechanism for selecting the appropriate representation when
+ servicing a request, as described in section 12. The
+ representation of entities in any response can be negotiated
+ (including error responses).
+
+ variant
+ A resource may have one, or more than one, representation(s)
+ associated with it at any given instant. Each of these
+ representations is termed a `varriant'. Use of the term `variant'
+ does not necessarily imply that the resource is subject to content
+ negotiation.
+
+ client
+ A program that establishes connections for the purpose of sending
+ requests.
+
+ user agent
+ The client which initiates a request. These are often browsers,
+ editors, spiders (web-traversing robots), or other end user tools.
+
+ server
+ An application program that accepts connections in order to
+ service requests by sending back responses. Any given program may
+ be capable of being both a client and a server; our use of these
+ terms refers only to the role being performed by the program for a
+ particular connection, rather than to the program's capabilities
+ in general. Likewise, any server may act as an origin server,
+ proxy, gateway, or tunnel, switching behavior based on the nature
+ of each request.
+
+
+
+
+Fielding, et al. Standards Track [Page 9]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ origin server
+ The server on which a given resource resides or is to be created.
+
+ proxy
+ An intermediary program which acts as both a server and a client
+ for the purpose of making requests on behalf of other clients.
+ Requests are serviced internally or by passing them on, with
+ possible translation, to other servers. A proxy MUST implement
+ both the client and server requirements of this specification. A
+ "transparent proxy" is a proxy that does not modify the request or
+ response beyond what is required for proxy authentication and
+ identification. A "non-transparent proxy" is a proxy that modifies
+ the request or response in order to provide some added service to
+ the user agent, such as group annotation services, media type
+ transformation, protocol reduction, or anonymity filtering. Except
+ where either transparent or non-transparent behavior is explicitly
+ stated, the HTTP proxy requirements apply to both types of
+ proxies.
+
+ gateway
+ A server which acts as an intermediary for some other server.
+ Unlike a proxy, a gateway receives requests as if it were the
+ origin server for the requested resource; the requesting client
+ may not be aware that it is communicating with a gateway.
+
+ tunnel
+ An intermediary program which is acting as a blind relay between
+ two connections. Once active, a tunnel is not considered a party
+ to the HTTP communication, though the tunnel may have been
+ initiated by an HTTP request. The tunnel ceases to exist when both
+ ends of the relayed connections are closed.
+
+ cache
+ A program's local store of response messages and the subsystem
+ that controls its message storage, retrieval, and deletion. A
+ cache stores cacheable responses in order to reduce the response
+ time and network bandwidth consumption on future, equivalent
+ requests. Any client or server may include a cache, though a cache
+ cannot be used by a server that is acting as a tunnel.
+
+ cacheable
+ A response is cacheable if a cache is allowed to store a copy of
+ the response message for use in answering subsequent requests. The
+ rules for determining the cacheability of HTTP responses are
+ defined in section 13. Even if a resource is cacheable, there may
+ be additional constraints on whether a cache can use the cached
+ copy for a particular request.
+
+
+
+
+Fielding, et al. Standards Track [Page 10]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ first-hand
+ A response is first-hand if it comes directly and without
+ unnecessary delay from the origin server, perhaps via one or more
+ proxies. A response is also first-hand if its validity has just
+ been checked directly with the origin server.
+
+ explicit expiration time
+ The time at which the origin server intends that an entity should
+ no longer be returned by a cache without further validation.
+
+ heuristic expiration time
+ An expiration time assigned by a cache when no explicit expiration
+ time is available.
+
+ age
+ The age of a response is the time since it was sent by, or
+ successfully validated with, the origin server.
+
+ freshness lifetime
+ The length of time between the generation of a response and its
+ expiration time.
+
+ fresh
+ A response is fresh if its age has not yet exceeded its freshness
+ lifetime.
+
+ stale
+ A response is stale if its age has passed its freshness lifetime.
+
+ semantically transparent
+ A cache behaves in a "semantically transparent" manner, with
+ respect to a particular response, when its use affects neither the
+ requesting client nor the origin server, except to improve
+ performance. When a cache is semantically transparent, the client
+ receives exactly the same response (except for hop-by-hop headers)
+ that it would have received had its request been handled directly
+ by the origin server.
+
+ validator
+ A protocol element (e.g., an entity tag or a Last-Modified time)
+ that is used to find out whether a cache entry is an equivalent
+ copy of an entity.
+
+ upstream/downstream
+ Upstream and downstream describe the flow of a message: all
+ messages flow from upstream to downstream.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 11]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ inbound/outbound
+ Inbound and outbound refer to the request and response paths for
+ messages: "inbound" means "traveling toward the origin server",
+ and "outbound" means "traveling toward the user agent"
+
+1.4 Overall Operation
+
+ The HTTP protocol is a request/response protocol. A client sends a
+ request to the server in the form of a request method, URI, and
+ protocol version, followed by a MIME-like message containing request
+ modifiers, client information, and possible body content over a
+ connection with a server. The server responds with a status line,
+ including the message's protocol version and a success or error code,
+ followed by a MIME-like message containing server information, entity
+ metainformation, and possible entity-body content. The relationship
+ between HTTP and MIME is described in appendix 19.4.
+
+ Most HTTP communication is initiated by a user agent and consists of
+ a request to be applied to a resource on some origin server. In the
+ simplest case, this may be accomplished via a single connection (v)
+ between the user agent (UA) and the origin server (O).
+
+ request chain ------------------------>
+ UA -------------------v------------------- O
+ <----------------------- response chain
+
+ A more complicated situation occurs when one or more intermediaries
+ are present in the request/response chain. There are three common
+ forms of intermediary: proxy, gateway, and tunnel. A proxy is a
+ forwarding agent, receiving requests for a URI in its absolute form,
+ rewriting all or part of the message, and forwarding the reformatted
+ request toward the server identified by the URI. A gateway is a
+ receiving agent, acting as a layer above some other server(s) and, if
+ necessary, translating the requests to the underlying server's
+ protocol. A tunnel acts as a relay point between two connections
+ without changing the messages; tunnels are used when the
+ communication needs to pass through an intermediary (such as a
+ firewall) even when the intermediary cannot understand the contents
+ of the messages.
+
+ request chain -------------------------------------->
+ UA -----v----- A -----v----- B -----v----- C -----v----- O
+ <------------------------------------- response chain
+
+ The figure above shows three intermediaries (A, B, and C) between the
+ user agent and origin server. A request or response message that
+ travels the whole chain will pass through four separate connections.
+ This distinction is important because some HTTP communication options
+
+
+
+Fielding, et al. Standards Track [Page 12]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ may apply only to the connection with the nearest, non-tunnel
+ neighbor, only to the end-points of the chain, or to all connections
+ along the chain. Although the diagram is linear, each participant may
+ be engaged in multiple, simultaneous communications. For example, B
+ may be receiving requests from many clients other than A, and/or
+ forwarding requests to servers other than C, at the same time that it
+ is handling A's request.
+
+ Any party to the communication which is not acting as a tunnel may
+ employ an internal cache for handling requests. The effect of a cache
+ is that the request/response chain is shortened if one of the
+ participants along the chain has a cached response applicable to that
+ request. The following illustrates the resulting chain if B has a
+ cached copy of an earlier response from O (via C) for a request which
+ has not been cached by UA or A.
+
+ request chain ---------->
+ UA -----v----- A -----v----- B - - - - - - C - - - - - - O
+ <--------- response chain
+
+ Not all responses are usefully cacheable, and some requests may
+ contain modifiers which place special requirements on cache behavior.
+ HTTP requirements for cache behavior and cacheable responses are
+ defined in section 13.
+
+ In fact, there are a wide variety of architectures and configurations
+ of caches and proxies currently being experimented with or deployed
+ across the World Wide Web. These systems include national hierarchies
+ of proxy caches to save transoceanic bandwidth, systems that
+ broadcast or multicast cache entries, organizations that distribute
+ subsets of cached data via CD-ROM, and so on. HTTP systems are used
+ in corporate intranets over high-bandwidth links, and for access via
+ PDAs with low-power radio links and intermittent connectivity. The
+ goal of HTTP/1.1 is to support the wide diversity of configurations
+ already deployed while introducing protocol constructs that meet the
+ needs of those who build web applications that require high
+ reliability and, failing that, at least reliable indications of
+ failure.
+
+ HTTP communication usually takes place over TCP/IP connections. The
+ default port is TCP 80 [19], but other ports can be used. This does
+ not preclude HTTP from being implemented on top of any other protocol
+ on the Internet, or on other networks. HTTP only presumes a reliable
+ transport; any protocol that provides such guarantees can be used;
+ the mapping of the HTTP/1.1 request and response structures onto the
+ transport data units of the protocol in question is outside the scope
+ of this specification.
+
+
+
+
+Fielding, et al. Standards Track [Page 13]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ In HTTP/1.0, most implementations used a new connection for each
+ request/response exchange. In HTTP/1.1, a connection may be used for
+ one or more request/response exchanges, although connections may be
+ closed for a variety of reasons (see section 8.1).
+
+2 Notational Conventions and Generic Grammar
+
+2.1 Augmented BNF
+
+ All of the mechanisms specified in this document are described in
+ both prose and an augmented Backus-Naur Form (BNF) similar to that
+ used by RFC 822 [9]. Implementors will need to be familiar with the
+ notation in order to understand this specification. The augmented BNF
+ includes the following constructs:
+
+ name = definition
+ The name of a rule is simply the name itself (without any
+ enclosing "<" and ">") and is separated from its definition by the
+ equal "=" character. White space is only significant in that
+ indentation of continuation lines is used to indicate a rule
+ definition that spans more than one line. Certain basic rules are
+ in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle
+ brackets are used within definitions whenever their presence will
+ facilitate discerning the use of rule names.
+
+ "literal"
+ Quotation marks surround literal text. Unless stated otherwise,
+ the text is case-insensitive.
+
+ rule1 | rule2
+ Elements separated by a bar ("|") are alternatives, e.g., "yes |
+ no" will accept yes or no.
+
+ (rule1 rule2)
+ Elements enclosed in parentheses are treated as a single element.
+ Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
+ foo elem" and "elem bar elem".
+
+ *rule
+ The character "*" preceding an element indicates repetition. The
+ full form is "<n>*<m>element" indicating at least <n> and at most
+ <m> occurrences of element. Default values are 0 and infinity so
+ that "*(element)" allows any number, including zero; "1*element"
+ requires at least one; and "1*2element" allows one or two.
+
+ [rule]
+ Square brackets enclose optional elements; "[foo bar]" is
+ equivalent to "*1(foo bar)".
+
+
+
+Fielding, et al. Standards Track [Page 14]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ N rule
+ Specific repetition: "<n>(element)" is equivalent to
+ "<n>*<n>(element)"; that is, exactly <n> occurrences of (element).
+ Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three
+ alphabetic characters.
+
+ #rule
+ A construct "#" is defined, similar to "*", for defining lists of
+ elements. The full form is "<n>#<m>element" indicating at least
+ <n> and at most <m> elements, each separated by one or more commas
+ (",") and OPTIONAL linear white space (LWS). This makes the usual
+ form of lists very easy; a rule such as
+ ( *LWS element *( *LWS "," *LWS element ))
+ can be shown as
+ 1#element
+ Wherever this construct is used, null elements are allowed, but do
+ not contribute to the count of elements present. That is,
+ "(element), , (element) " is permitted, but counts as only two
+ elements. Therefore, where at least one element is required, at
+ least one non-null element MUST be present. Default values are 0
+ and infinity so that "#element" allows any number, including zero;
+ "1#element" requires at least one; and "1#2element" allows one or
+ two.
+
+ ; comment
+ A semi-colon, set off some distance to the right of rule text,
+ starts a comment that continues to the end of line. This is a
+ simple way of including useful notes in parallel with the
+ specifications.
+
+ implied *LWS
+ The grammar described by this specification is word-based. Except
+ where noted otherwise, linear white space (LWS) can be included
+ between any two adjacent words (token or quoted-string), and
+ between adjacent words and separators, without changing the
+ interpretation of a field. At least one delimiter (LWS and/or
+
+ separators) MUST exist between any two tokens (for the definition
+ of "token" below), since they would otherwise be interpreted as a
+ single token.
+
+2.2 Basic Rules
+
+ The following rules are used throughout this specification to
+ describe basic parsing constructs. The US-ASCII coded character set
+ is defined by ANSI X3.4-1986 [21].
+
+
+
+
+
+Fielding, et al. Standards Track [Page 15]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ OCTET = <any 8-bit sequence of data>
+ CHAR = <any US-ASCII character (octets 0 - 127)>
+ UPALPHA = <any US-ASCII uppercase letter "A".."Z">
+ LOALPHA = <any US-ASCII lowercase letter "a".."z">
+ ALPHA = UPALPHA | LOALPHA
+ DIGIT = <any US-ASCII digit "0".."9">
+ CTL = <any US-ASCII control character
+ (octets 0 - 31) and DEL (127)>
+ CR = <US-ASCII CR, carriage return (13)>
+ LF = <US-ASCII LF, linefeed (10)>
+ SP = <US-ASCII SP, space (32)>
+ HT = <US-ASCII HT, horizontal-tab (9)>
+ <"> = <US-ASCII double-quote mark (34)>
+
+ HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
+ protocol elements except the entity-body (see appendix 19.3 for
+ tolerant applications). The end-of-line marker within an entity-body
+ is defined by its associated media type, as described in section 3.7.
+
+ CRLF = CR LF
+
+ HTTP/1.1 header field values can be folded onto multiple lines if the
+ continuation line begins with a space or horizontal tab. All linear
+ white space, including folding, has the same semantics as SP. A
+ recipient MAY replace any linear white space with a single SP before
+ interpreting the field value or forwarding the message downstream.
+
+ LWS = [CRLF] 1*( SP | HT )
+
+ The TEXT rule is only used for descriptive field contents and values
+ that are not intended to be interpreted by the message parser. Words
+ of *TEXT MAY contain characters from character sets other than ISO-
+ 8859-1 [22] only when encoded according to the rules of RFC 2047
+ [14].
+
+ TEXT = <any OCTET except CTLs,
+ but including LWS>
+
+ A CRLF is allowed in the definition of TEXT only as part of a header
+ field continuation. It is expected that the folding LWS will be
+ replaced with a single SP before interpretation of the TEXT value.
+
+ Hexadecimal numeric characters are used in several protocol elements.
+
+ HEX = "A" | "B" | "C" | "D" | "E" | "F"
+ | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
+
+
+
+
+
+Fielding, et al. Standards Track [Page 16]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Many HTTP/1.1 header field values consist of words separated by LWS
+ or special characters. These special characters MUST be in a quoted
+ string to be used within a parameter value (as defined in section
+ 3.6).
+
+ token = 1*<any CHAR except CTLs or separators>
+ separators = "(" | ")" | "<" | ">" | "@"
+ | "," | ";" | ":" | "\" | <">
+ | "/" | "[" | "]" | "?" | "="
+ | "{" | "}" | SP | HT
+
+ Comments can be included in some HTTP header fields by surrounding
+ the comment text with parentheses. Comments are only allowed in
+ fields containing "comment" as part of their field value definition.
+ In all other fields, parentheses are considered part of the field
+ value.
+
+ comment = "(" *( ctext | quoted-pair | comment ) ")"
+ ctext = <any TEXT excluding "(" and ")">
+
+ A string of text is parsed as a single word if it is quoted using
+ double-quote marks.
+
+ quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
+ qdtext = <any TEXT except <">>
+
+ The backslash character ("\") MAY be used as a single-character
+ quoting mechanism only within quoted-string and comment constructs.
+
+ quoted-pair = "\" CHAR
+
+3 Protocol Parameters
+
+3.1 HTTP Version
+
+ HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
+ of the protocol. The protocol versioning policy is intended to allow
+ the sender to indicate the format of a message and its capacity for
+ understanding further HTTP communication, rather than the features
+ obtained via that communication. No change is made to the version
+ number for the addition of message components which do not affect
+ communication behavior or which only add to extensible field values.
+ The <minor> number is incremented when the changes made to the
+ protocol add features which do not change the general message parsing
+ algorithm, but which may add to the message semantics and imply
+ additional capabilities of the sender. The <major> number is
+ incremented when the format of a message within the protocol is
+ changed. See RFC 2145 [36] for a fuller explanation.
+
+
+
+Fielding, et al. Standards Track [Page 17]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The version of an HTTP message is indicated by an HTTP-Version field
+ in the first line of the message.
+
+ HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
+
+ Note that the major and minor numbers MUST be treated as separate
+ integers and that each MAY be incremented higher than a single digit.
+ Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is
+ lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and
+ MUST NOT be sent.
+
+ An application that sends a request or response message that includes
+ HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant
+ with this specification. Applications that are at least conditionally
+ compliant with this specification SHOULD use an HTTP-Version of
+ "HTTP/1.1" in their messages, and MUST do so for any message that is
+ not compatible with HTTP/1.0. For more details on when to send
+ specific HTTP-Version values, see RFC 2145 [36].
+
+ The HTTP version of an application is the highest HTTP version for
+ which the application is at least conditionally compliant.
+
+ Proxy and gateway applications need to be careful when forwarding
+ messages in protocol versions different from that of the application.
+ Since the protocol version indicates the protocol capability of the
+ sender, a proxy/gateway MUST NOT send a message with a version
+ indicator which is greater than its actual version. If a higher
+ version request is received, the proxy/gateway MUST either downgrade
+ the request version, or respond with an error, or switch to tunnel
+ behavior.
+
+ Due to interoperability problems with HTTP/1.0 proxies discovered
+ since the publication of RFC 2068[33], caching proxies MUST, gateways
+ MAY, and tunnels MUST NOT upgrade the request to the highest version
+ they support. The proxy/gateway's response to that request MUST be in
+ the same major version as the request.
+
+ Note: Converting between versions of HTTP may involve modification
+ of header fields required or forbidden by the versions involved.
+
+3.2 Uniform Resource Identifiers
+
+ URIs have been known by many names: WWW addresses, Universal Document
+ Identifiers, Universal Resource Identifiers [3], and finally the
+ combination of Uniform Resource Locators (URL) [4] and Names (URN)
+ [20]. As far as HTTP is concerned, Uniform Resource Identifiers are
+ simply formatted strings which identify--via name, location, or any
+ other characteristic--a resource.
+
+
+
+Fielding, et al. Standards Track [Page 18]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+3.2.1 General Syntax
+
+ URIs in HTTP can be represented in absolute form or relative to some
+ known base URI [11], depending upon the context of their use. The two
+ forms are differentiated by the fact that absolute URIs always begin
+ with a scheme name followed by a colon. For definitive information on
+ URL syntax and semantics, see "Uniform Resource Identifiers (URI):
+ Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs
+ 1738 [4] and RFC 1808 [11]). This specification adopts the
+ definitions of "URI-reference", "absoluteURI", "relativeURI", "port",
+ "host","abs_path", "rel_path", and "authority" from that
+ specification.
+
+ The HTTP protocol does not place any a priori limit on the length of
+ a URI. Servers MUST be able to handle the URI of any resource they
+ serve, and SHOULD be able to handle URIs of unbounded length if they
+ provide GET-based forms that could generate such URIs. A server
+ SHOULD return 414 (Request-URI Too Long) status if a URI is longer
+ than the server can handle (see section 10.4.15).
+
+ Note: Servers ought to be cautious about depending on URI lengths
+ above 255 bytes, because some older client or proxy
+ implementations might not properly support these lengths.
+
+3.2.2 http URL
+
+ The "http" scheme is used to locate network resources via the HTTP
+ protocol. This section defines the scheme-specific syntax and
+ semantics for http URLs.
+
+ http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
+
+ If the port is empty or not given, port 80 is assumed. The semantics
+ are that the identified resource is located at the server listening
+ for TCP connections on that port of that host, and the Request-URI
+ for the resource is abs_path (section 5.1.2). The use of IP addresses
+ in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If
+ the abs_path is not present in the URL, it MUST be given as "/" when
+ used as a Request-URI for a resource (section 5.1.2). If a proxy
+ receives a host name which is not a fully qualified domain name, it
+ MAY add its domain to the host name it received. If a proxy receives
+ a fully qualified domain name, the proxy MUST NOT change the host
+ name.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 19]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+3.2.3 URI Comparison
+
+ When comparing two URIs to decide if they match or not, a client
+ SHOULD use a case-sensitive octet-by-octet comparison of the entire
+ URIs, with these exceptions:
+
+ - A port that is empty or not given is equivalent to the default
+ port for that URI-reference;
+
+ - Comparisons of host names MUST be case-insensitive;
+
+ - Comparisons of scheme names MUST be case-insensitive;
+
+ - An empty abs_path is equivalent to an abs_path of "/".
+
+ Characters other than those in the "reserved" and "unsafe" sets (see
+ RFC 2396 [42]) are equivalent to their ""%" HEX HEX" encoding.
+
+ For example, the following three URIs are equivalent:
+
+ http://abc.com:80/~smith/home.html
+ http://ABC.com/%7Esmith/home.html
+ http://ABC.com:/%7esmith/home.html
+
+3.3 Date/Time Formats
+
+3.3.1 Full Date
+
+ HTTP applications have historically allowed three different formats
+ for the representation of date/time stamps:
+
+ Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
+ Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
+ Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
+
+ The first format is preferred as an Internet standard and represents
+ a fixed-length subset of that defined by RFC 1123 [8] (an update to
+ RFC 822 [9]). The second format is in common use, but is based on the
+ obsolete RFC 850 [12] date format and lacks a four-digit year.
+ HTTP/1.1 clients and servers that parse the date value MUST accept
+ all three formats (for compatibility with HTTP/1.0), though they MUST
+ only generate the RFC 1123 format for representing HTTP-date values
+ in header fields. See section 19.3 for further information.
+
+ Note: Recipients of date values are encouraged to be robust in
+ accepting date values that may have been sent by non-HTTP
+ applications, as is sometimes the case when retrieving or posting
+ messages via proxies/gateways to SMTP or NNTP.
+
+
+
+Fielding, et al. Standards Track [Page 20]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ All HTTP date/time stamps MUST be represented in Greenwich Mean Time
+ (GMT), without exception. For the purposes of HTTP, GMT is exactly
+ equal to UTC (Coordinated Universal Time). This is indicated in the
+ first two formats by the inclusion of "GMT" as the three-letter
+ abbreviation for time zone, and MUST be assumed when reading the
+ asctime format. HTTP-date is case sensitive and MUST NOT include
+ additional LWS beyond that specifically included as SP in the
+ grammar.
+
+ HTTP-date = rfc1123-date | rfc850-date | asctime-date
+ rfc1123-date = wkday "," SP date1 SP time SP "GMT"
+ rfc850-date = weekday "," SP date2 SP time SP "GMT"
+ asctime-date = wkday SP date3 SP time SP 4DIGIT
+ date1 = 2DIGIT SP month SP 4DIGIT
+ ; day month year (e.g., 02 Jun 1982)
+ date2 = 2DIGIT "-" month "-" 2DIGIT
+ ; day-month-year (e.g., 02-Jun-82)
+ date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
+ ; month day (e.g., Jun 2)
+ time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+ ; 00:00:00 - 23:59:59
+ wkday = "Mon" | "Tue" | "Wed"
+ | "Thu" | "Fri" | "Sat" | "Sun"
+ weekday = "Monday" | "Tuesday" | "Wednesday"
+ | "Thursday" | "Friday" | "Saturday" | "Sunday"
+ month = "Jan" | "Feb" | "Mar" | "Apr"
+ | "May" | "Jun" | "Jul" | "Aug"
+ | "Sep" | "Oct" | "Nov" | "Dec"
+
+ Note: HTTP requirements for the date/time stamp format apply only
+ to their usage within the protocol stream. Clients and servers are
+ not required to use these formats for user presentation, request
+ logging, etc.
+
+3.3.2 Delta Seconds
+
+ Some HTTP header fields allow a time value to be specified as an
+ integer number of seconds, represented in decimal, after the time
+ that the message was received.
+
+ delta-seconds = 1*DIGIT
+
+3.4 Character Sets
+
+ HTTP uses the same definition of the term "character set" as that
+ described for MIME:
+
+
+
+
+
+Fielding, et al. Standards Track [Page 21]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The term "character set" is used in this document to refer to a
+ method used with one or more tables to convert a sequence of octets
+ into a sequence of characters. Note that unconditional conversion in
+ the other direction is not required, in that not all characters may
+ be available in a given character set and a character set may provide
+ more than one sequence of octets to represent a particular character.
+ This definition is intended to allow various kinds of character
+ encoding, from simple single-table mappings such as US-ASCII to
+ complex table switching methods such as those that use ISO-2022's
+ techniques. However, the definition associated with a MIME character
+ set name MUST fully specify the mapping to be performed from octets
+ to characters. In particular, use of external profiling information
+ to determine the exact mapping is not permitted.
+
+ Note: This use of the term "character set" is more commonly
+ referred to as a "character encoding." However, since HTTP and
+ MIME share the same registry, it is important that the terminology
+ also be shared.
+
+ HTTP character sets are identified by case-insensitive tokens. The
+ complete set of tokens is defined by the IANA Character Set registry
+ [19].
+
+ charset = token
+
+ Although HTTP allows an arbitrary token to be used as a charset
+ value, any token that has a predefined value within the IANA
+ Character Set registry [19] MUST represent the character set defined
+ by that registry. Applications SHOULD limit their use of character
+ sets to those defined by the IANA registry.
+
+ Implementors should be aware of IETF character set requirements [38]
+ [41].
+
+3.4.1 Missing Charset
+
+ Some HTTP/1.0 software has interpreted a Content-Type header without
+ charset parameter incorrectly to mean "recipient should guess."
+ Senders wishing to defeat this behavior MAY include a charset
+ parameter even when the charset is ISO-8859-1 and SHOULD do so when
+ it is known that it will not confuse the recipient.
+
+ Unfortunately, some older HTTP/1.0 clients did not deal properly with
+ an explicit charset parameter. HTTP/1.1 recipients MUST respect the
+ charset label provided by the sender; and those user agents that have
+ a provision to "guess" a charset MUST use the charset from the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 22]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ content-type field if they support that charset, rather than the
+ recipient's preference, when initially displaying a document. See
+ section 3.7.1.
+
+3.5 Content Codings
+
+ Content coding values indicate an encoding transformation that has
+ been or can be applied to an entity. Content codings are primarily
+ used to allow a document to be compressed or otherwise usefully
+ transformed without losing the identity of its underlying media type
+ and without loss of information. Frequently, the entity is stored in
+ coded form, transmitted directly, and only decoded by the recipient.
+
+ content-coding = token
+
+ All content-coding values are case-insensitive. HTTP/1.1 uses
+ content-coding values in the Accept-Encoding (section 14.3) and
+ Content-Encoding (section 14.11) header fields. Although the value
+ describes the content-coding, what is more important is that it
+ indicates what decoding mechanism will be required to remove the
+ encoding.
+
+ The Internet Assigned Numbers Authority (IANA) acts as a registry for
+ content-coding value tokens. Initially, the registry contains the
+ following tokens:
+
+ gzip An encoding format produced by the file compression program
+ "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a
+ Lempel-Ziv coding (LZ77) with a 32 bit CRC.
+
+ compress
+ The encoding format produced by the common UNIX file compression
+ program "compress". This format is an adaptive Lempel-Ziv-Welch
+ coding (LZW).
+
+ Use of program names for the identification of encoding formats
+ is not desirable and is discouraged for future encodings. Their
+ use here is representative of historical practice, not good
+ design. For compatibility with previous implementations of HTTP,
+ applications SHOULD consider "x-gzip" and "x-compress" to be
+ equivalent to "gzip" and "compress" respectively.
+
+ deflate
+ The "zlib" format defined in RFC 1950 [31] in combination with
+ the "deflate" compression mechanism described in RFC 1951 [29].
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 23]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ identity
+ The default (identity) encoding; the use of no transformation
+ whatsoever. This content-coding is used only in the Accept-
+ Encoding header, and SHOULD NOT be used in the Content-Encoding
+ header.
+
+ New content-coding value tokens SHOULD be registered; to allow
+ interoperability between clients and servers, specifications of the
+ content coding algorithms needed to implement a new value SHOULD be
+ publicly available and adequate for independent implementation, and
+ conform to the purpose of content coding defined in this section.
+
+3.6 Transfer Codings
+
+ Transfer-coding values are used to indicate an encoding
+ transformation that has been, can be, or may need to be applied to an
+ entity-body in order to ensure "safe transport" through the network.
+ This differs from a content coding in that the transfer-coding is a
+ property of the message, not of the original entity.
+
+ transfer-coding = "chunked" | transfer-extension
+ transfer-extension = token *( ";" parameter )
+
+ Parameters are in the form of attribute/value pairs.
+
+ parameter = attribute "=" value
+ attribute = token
+ value = token | quoted-string
+
+ All transfer-coding values are case-insensitive. HTTP/1.1 uses
+ transfer-coding values in the TE header field (section 14.39) and in
+ the Transfer-Encoding header field (section 14.41).
+
+ Whenever a transfer-coding is applied to a message-body, the set of
+ transfer-codings MUST include "chunked", unless the message is
+ terminated by closing the connection. When the "chunked" transfer-
+ coding is used, it MUST be the last transfer-coding applied to the
+ message-body. The "chunked" transfer-coding MUST NOT be applied more
+ than once to a message-body. These rules allow the recipient to
+ determine the transfer-length of the message (section 4.4).
+
+ Transfer-codings are analogous to the Content-Transfer-Encoding
+ values of MIME [7], which were designed to enable safe transport of
+ binary data over a 7-bit transport service. However, safe transport
+ has a different focus for an 8bit-clean transfer protocol. In HTTP,
+ the only unsafe characteristic of message-bodies is the difficulty in
+ determining the exact body length (section 7.2.2), or the desire to
+ encrypt data over a shared transport.
+
+
+
+Fielding, et al. Standards Track [Page 24]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Internet Assigned Numbers Authority (IANA) acts as a registry for
+ transfer-coding value tokens. Initially, the registry contains the
+ following tokens: "chunked" (section 3.6.1), "identity" (section
+ 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate"
+ (section 3.5).
+
+ New transfer-coding value tokens SHOULD be registered in the same way
+ as new content-coding value tokens (section 3.5).
+
+ A server which receives an entity-body with a transfer-coding it does
+ not understand SHOULD return 501 (Unimplemented), and close the
+ connection. A server MUST NOT send transfer-codings to an HTTP/1.0
+ client.
+
+3.6.1 Chunked Transfer Coding
+
+ The chunked encoding modifies the body of a message in order to
+ transfer it as a series of chunks, each with its own size indicator,
+ followed by an OPTIONAL trailer containing entity-header fields. This
+ allows dynamically produced content to be transferred along with the
+ information necessary for the recipient to verify that it has
+ received the full message.
+
+ Chunked-Body = *chunk
+ last-chunk
+ trailer
+ CRLF
+
+ chunk = chunk-size [ chunk-extension ] CRLF
+ chunk-data CRLF
+ chunk-size = 1*HEX
+ last-chunk = 1*("0") [ chunk-extension ] CRLF
+
+ chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
+ chunk-ext-name = token
+ chunk-ext-val = token | quoted-string
+ chunk-data = chunk-size(OCTET)
+ trailer = *(entity-header CRLF)
+
+ The chunk-size field is a string of hex digits indicating the size of
+ the chunk. The chunked encoding is ended by any chunk whose size is
+ zero, followed by the trailer, which is terminated by an empty line.
+
+ The trailer allows the sender to include additional HTTP header
+ fields at the end of the message. The Trailer header field can be
+ used to indicate which header fields are included in a trailer (see
+ section 14.40).
+
+
+
+
+Fielding, et al. Standards Track [Page 25]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A server using chunked transfer-coding in a response MUST NOT use the
+ trailer for any header fields unless at least one of the following is
+ true:
+
+ a)the request included a TE header field that indicates "trailers" is
+ acceptable in the transfer-coding of the response, as described in
+ section 14.39; or,
+
+ b)the server is the origin server for the response, the trailer
+ fields consist entirely of optional metadata, and the recipient
+ could use the message (in a manner acceptable to the origin server)
+ without receiving this metadata. In other words, the origin server
+ is willing to accept the possibility that the trailer fields might
+ be silently discarded along the path to the client.
+
+ This requirement prevents an interoperability failure when the
+ message is being received by an HTTP/1.1 (or later) proxy and
+ forwarded to an HTTP/1.0 recipient. It avoids a situation where
+ compliance with the protocol would have necessitated a possibly
+ infinite buffer on the proxy.
+
+ An example process for decoding a Chunked-Body is presented in
+ appendix 19.4.6.
+
+ All HTTP/1.1 applications MUST be able to receive and decode the
+ "chunked" transfer-coding, and MUST ignore chunk-extension extensions
+ they do not understand.
+
+3.7 Media Types
+
+ HTTP uses Internet Media Types [17] in the Content-Type (section
+ 14.17) and Accept (section 14.1) header fields in order to provide
+ open and extensible data typing and type negotiation.
+
+ media-type = type "/" subtype *( ";" parameter )
+ type = token
+ subtype = token
+
+ Parameters MAY follow the type/subtype in the form of attribute/value
+ pairs (as defined in section 3.6).
+
+ The type, subtype, and parameter attribute names are case-
+ insensitive. Parameter values might or might not be case-sensitive,
+ depending on the semantics of the parameter name. Linear white space
+ (LWS) MUST NOT be used between the type and subtype, nor between an
+ attribute and its value. The presence or absence of a parameter might
+ be significant to the processing of a media-type, depending on its
+ definition within the media type registry.
+
+
+
+Fielding, et al. Standards Track [Page 26]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note that some older HTTP applications do not recognize media type
+ parameters. When sending data to older HTTP applications,
+ implementations SHOULD only use media type parameters when they are
+ required by that type/subtype definition.
+
+ Media-type values are registered with the Internet Assigned Number
+ Authority (IANA [19]). The media type registration process is
+ outlined in RFC 1590 [17]. Use of non-registered media types is
+ discouraged.
+
+3.7.1 Canonicalization and Text Defaults
+
+ Internet media types are registered with a canonical form. An
+ entity-body transferred via HTTP messages MUST be represented in the
+ appropriate canonical form prior to its transmission except for
+ "text" types, as defined in the next paragraph.
+
+ When in canonical form, media subtypes of the "text" type use CRLF as
+ the text line break. HTTP relaxes this requirement and allows the
+ transport of text media with plain CR or LF alone representing a line
+ break when it is done consistently for an entire entity-body. HTTP
+ applications MUST accept CRLF, bare CR, and bare LF as being
+ representative of a line break in text media received via HTTP. In
+ addition, if the text is represented in a character set that does not
+ use octets 13 and 10 for CR and LF respectively, as is the case for
+ some multi-byte character sets, HTTP allows the use of whatever octet
+ sequences are defined by that character set to represent the
+ equivalent of CR and LF for line breaks. This flexibility regarding
+ line breaks applies only to text media in the entity-body; a bare CR
+ or LF MUST NOT be substituted for CRLF within any of the HTTP control
+ structures (such as header fields and multipart boundaries).
+
+ If an entity-body is encoded with a content-coding, the underlying
+ data MUST be in a form defined above prior to being encoded.
+
+ The "charset" parameter is used with some media types to define the
+ character set (section 3.4) of the data. When no explicit charset
+ parameter is provided by the sender, media subtypes of the "text"
+ type are defined to have a default charset value of "ISO-8859-1" when
+ received via HTTP. Data in character sets other than "ISO-8859-1" or
+ its subsets MUST be labeled with an appropriate charset value. See
+ section 3.4.1 for compatibility problems.
+
+3.7.2 Multipart Types
+
+ MIME provides for a number of "multipart" types -- encapsulations of
+ one or more entities within a single message-body. All multipart
+ types share a common syntax, as defined in section 5.1.1 of RFC 2046
+
+
+
+Fielding, et al. Standards Track [Page 27]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [40], and MUST include a boundary parameter as part of the media type
+ value. The message body is itself a protocol element and MUST
+ therefore use only CRLF to represent line breaks between body-parts.
+ Unlike in RFC 2046, the epilogue of any multipart message MUST be
+ empty; HTTP applications MUST NOT transmit the epilogue (even if the
+ original multipart contains an epilogue). These restrictions exist in
+ order to preserve the self-delimiting nature of a multipart message-
+ body, wherein the "end" of the message-body is indicated by the
+ ending multipart boundary.
+
+ In general, HTTP treats a multipart message-body no differently than
+ any other media type: strictly as payload. The one exception is the
+ "multipart/byteranges" type (appendix 19.2) when it appears in a 206
+ (Partial Content) response, which will be interpreted by some HTTP
+ caching mechanisms as described in sections 13.5.4 and 14.16. In all
+ other cases, an HTTP user agent SHOULD follow the same or similar
+ behavior as a MIME user agent would upon receipt of a multipart type.
+ The MIME header fields within each body-part of a multipart message-
+ body do not have any significance to HTTP beyond that defined by
+ their MIME semantics.
+
+ In general, an HTTP user agent SHOULD follow the same or similar
+ behavior as a MIME user agent would upon receipt of a multipart type.
+ If an application receives an unrecognized multipart subtype, the
+ application MUST treat it as being equivalent to "multipart/mixed".
+
+ Note: The "multipart/form-data" type has been specifically defined
+ for carrying form data suitable for processing via the POST
+ request method, as described in RFC 1867 [15].
+
+3.8 Product Tokens
+
+ Product tokens are used to allow communicating applications to
+ identify themselves by software name and version. Most fields using
+ product tokens also allow sub-products which form a significant part
+ of the application to be listed, separated by white space. By
+ convention, the products are listed in order of their significance
+ for identifying the application.
+
+ product = token ["/" product-version]
+ product-version = token
+
+ Examples:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+ Server: Apache/0.8.4
+
+
+
+
+
+Fielding, et al. Standards Track [Page 28]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Product tokens SHOULD be short and to the point. They MUST NOT be
+ used for advertising or other non-essential information. Although any
+ token character MAY appear in a product-version, this token SHOULD
+ only be used for a version identifier (i.e., successive versions of
+ the same product SHOULD only differ in the product-version portion of
+ the product value).
+
+3.9 Quality Values
+
+ HTTP content negotiation (section 12) uses short "floating point"
+ numbers to indicate the relative importance ("weight") of various
+ negotiable parameters. A weight is normalized to a real number in
+ the range 0 through 1, where 0 is the minimum and 1 the maximum
+ value. If a parameter has a quality value of 0, then content with
+ this parameter is `not acceptable' for the client. HTTP/1.1
+ applications MUST NOT generate more than three digits after the
+ decimal point. User configuration of these values SHOULD also be
+ limited in this fashion.
+
+ qvalue = ( "0" [ "." 0*3DIGIT ] )
+ | ( "1" [ "." 0*3("0") ] )
+
+ "Quality values" is a misnomer, since these values merely represent
+ relative degradation in desired quality.
+
+3.10 Language Tags
+
+ A language tag identifies a natural language spoken, written, or
+ otherwise conveyed by human beings for communication of information
+ to other human beings. Computer languages are explicitly excluded.
+ HTTP uses language tags within the Accept-Language and Content-
+ Language fields.
+
+ The syntax and registry of HTTP language tags is the same as that
+ defined by RFC 1766 [1]. In summary, a language tag is composed of 1
+ or more parts: A primary language tag and a possibly empty series of
+ subtags:
+
+ language-tag = primary-tag *( "-" subtag )
+ primary-tag = 1*8ALPHA
+ subtag = 1*8ALPHA
+
+ White space is not allowed within the tag and all tags are case-
+ insensitive. The name space of language tags is administered by the
+ IANA. Example tags include:
+
+ en, en-US, en-cockney, i-cherokee, x-pig-latin
+
+
+
+
+Fielding, et al. Standards Track [Page 29]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ where any two-letter primary-tag is an ISO-639 language abbreviation
+ and any two-letter initial subtag is an ISO-3166 country code. (The
+ last three tags above are not registered tags; all but the last are
+ examples of tags which could be registered in future.)
+
+3.11 Entity Tags
+
+ Entity tags are used for comparing two or more entities from the same
+ requested resource. HTTP/1.1 uses entity tags in the ETag (section
+ 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and
+ If-Range (section 14.27) header fields. The definition of how they
+ are used and compared as cache validators is in section 13.3.3. An
+ entity tag consists of an opaque quoted string, possibly prefixed by
+ a weakness indicator.
+
+ entity-tag = [ weak ] opaque-tag
+ weak = "W/"
+ opaque-tag = quoted-string
+
+ A "strong entity tag" MAY be shared by two entities of a resource
+ only if they are equivalent by octet equality.
+
+ A "weak entity tag," indicated by the "W/" prefix, MAY be shared by
+ two entities of a resource only if the entities are equivalent and
+ could be substituted for each other with no significant change in
+ semantics. A weak entity tag can only be used for weak comparison.
+
+ An entity tag MUST be unique across all versions of all entities
+ associated with a particular resource. A given entity tag value MAY
+ be used for entities obtained by requests on different URIs. The use
+ of the same entity tag value in conjunction with entities obtained by
+ requests on different URIs does not imply the equivalence of those
+ entities.
+
+3.12 Range Units
+
+ HTTP/1.1 allows a client to request that only part (a range of) the
+ response entity be included within the response. HTTP/1.1 uses range
+ units in the Range (section 14.35) and Content-Range (section 14.16)
+ header fields. An entity can be broken down into subranges according
+ to various structural units.
+
+ range-unit = bytes-unit | other-range-unit
+ bytes-unit = "bytes"
+ other-range-unit = token
+
+ The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
+ implementations MAY ignore ranges specified using other units.
+
+
+
+Fielding, et al. Standards Track [Page 30]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 has been designed to allow implementations of applications
+ that do not depend on knowledge of ranges.
+
+4 HTTP Message
+
+4.1 Message Types
+
+ HTTP messages consist of requests from client to server and responses
+ from server to client.
+
+ HTTP-message = Request | Response ; HTTP/1.1 messages
+
+ Request (section 5) and Response (section 6) messages use the generic
+ message format of RFC 822 [9] for transferring entities (the payload
+ of the message). Both types of message consist of a start-line, zero
+ or more header fields (also known as "headers"), an empty line (i.e.,
+ a line with nothing preceding the CRLF) indicating the end of the
+ header fields, and possibly a message-body.
+
+ generic-message = start-line
+ *(message-header CRLF)
+ CRLF
+ [ message-body ]
+ start-line = Request-Line | Status-Line
+
+ In the interest of robustness, servers SHOULD ignore any empty
+ line(s) received where a Request-Line is expected. In other words, if
+ the server is reading the protocol stream at the beginning of a
+ message and receives a CRLF first, it should ignore the CRLF.
+
+ Certain buggy HTTP/1.0 client implementations generate extra CRLF's
+ after a POST request. To restate what is explicitly forbidden by the
+ BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an
+ extra CRLF.
+
+4.2 Message Headers
+
+ HTTP header fields, which include general-header (section 4.5),
+ request-header (section 5.3), response-header (section 6.2), and
+ entity-header (section 7.1) fields, follow the same generic format as
+ that given in Section 3.1 of RFC 822 [9]. Each header field consists
+ of a name followed by a colon (":") and the field value. Field names
+ are case-insensitive. The field value MAY be preceded by any amount
+ of LWS, though a single SP is preferred. Header fields can be
+ extended over multiple lines by preceding each extra line with at
+ least one SP or HT. Applications ought to follow "common form", where
+ one is known or indicated, when generating HTTP constructs, since
+ there might exist some implementations that fail to accept anything
+
+
+
+Fielding, et al. Standards Track [Page 31]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ beyond the common forms.
+
+ message-header = field-name ":" [ field-value ]
+ field-name = token
+ field-value = *( field-content | LWS )
+ field-content = <the OCTETs making up the field-value
+ and consisting of either *TEXT or combinations
+ of token, separators, and quoted-string>
+
+ The field-content does not include any leading or trailing LWS:
+ linear white space occurring before the first non-whitespace
+ character of the field-value or after the last non-whitespace
+ character of the field-value. Such leading or trailing LWS MAY be
+ removed without changing the semantics of the field value. Any LWS
+ that occurs between field-content MAY be replaced with a single SP
+ before interpreting the field value or forwarding the message
+ downstream.
+
+ The order in which header fields with differing field names are
+ received is not significant. However, it is "good practice" to send
+ general-header fields first, followed by request-header or response-
+ header fields, and ending with the entity-header fields.
+
+ Multiple message-header fields with the same field-name MAY be
+ present in a message if and only if the entire field-value for that
+ header field is defined as a comma-separated list [i.e., #(values)].
+ It MUST be possible to combine the multiple header fields into one
+ "field-name: field-value" pair, without changing the semantics of the
+ message, by appending each subsequent field-value to the first, each
+ separated by a comma. The order in which header fields with the same
+ field-name are received is therefore significant to the
+ interpretation of the combined field value, and thus a proxy MUST NOT
+ change the order of these field values when a message is forwarded.
+
+4.3 Message Body
+
+ The message-body (if any) of an HTTP message is used to carry the
+ entity-body associated with the request or response. The message-body
+ differs from the entity-body only when a transfer-coding has been
+ applied, as indicated by the Transfer-Encoding header field (section
+ 14.41).
+
+ message-body = entity-body
+ | <entity-body encoded as per Transfer-Encoding>
+
+ Transfer-Encoding MUST be used to indicate any transfer-codings
+ applied by an application to ensure safe and proper transfer of the
+ message. Transfer-Encoding is a property of the message, not of the
+
+
+
+Fielding, et al. Standards Track [Page 32]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ entity, and thus MAY be added or removed by any application along the
+ request/response chain. (However, section 3.6 places restrictions on
+ when certain transfer-codings may be used.)
+
+ The rules for when a message-body is allowed in a message differ for
+ requests and responses.
+
+ The presence of a message-body in a request is signaled by the
+ inclusion of a Content-Length or Transfer-Encoding header field in
+ the request's message-headers. A message-body MUST NOT be included in
+ a request if the specification of the request method (section 5.1.1)
+ does not allow sending an entity-body in requests. A server SHOULD
+ read and forward a message-body on any request; if the request method
+ does not include defined semantics for an entity-body, then the
+ message-body SHOULD be ignored when handling the request.
+
+ For response messages, whether or not a message-body is included with
+ a message is dependent on both the request method and the response
+ status code (section 6.1.1). All responses to the HEAD request method
+ MUST NOT include a message-body, even though the presence of entity-
+ header fields might lead one to believe they do. All 1xx
+ (informational), 204 (no content), and 304 (not modified) responses
+ MUST NOT include a message-body. All other responses do include a
+ message-body, although it MAY be of zero length.
+
+4.4 Message Length
+
+ The transfer-length of a message is the length of the message-body as
+ it appears in the message; that is, after any transfer-codings have
+ been applied. When a message-body is included with a message, the
+ transfer-length of that body is determined by one of the following
+ (in order of precedence):
+
+ 1.Any response message which "MUST NOT" include a message-body (such
+ as the 1xx, 204, and 304 responses and any response to a HEAD
+ request) is always terminated by the first empty line after the
+ header fields, regardless of the entity-header fields present in
+ the message.
+
+ 2.If a Transfer-Encoding header field (section 14.41) is present and
+ has any value other than "identity", then the transfer-length is
+ defined by use of the "chunked" transfer-coding (section 3.6),
+ unless the message is terminated by closing the connection.
+
+ 3.If a Content-Length header field (section 14.13) is present, its
+ decimal value in OCTETs represents both the entity-length and the
+ transfer-length. The Content-Length header field MUST NOT be sent
+ if these two lengths are different (i.e., if a Transfer-Encoding
+
+
+
+Fielding, et al. Standards Track [Page 33]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ header field is present). If a message is received with both a
+ Transfer-Encoding header field and a Content-Length header field,
+ the latter MUST be ignored.
+
+ 4.If the message uses the media type "multipart/byteranges", and the
+ ransfer-length is not otherwise specified, then this self-
+ elimiting media type defines the transfer-length. This media type
+ UST NOT be used unless the sender knows that the recipient can arse
+ it; the presence in a request of a Range header with ultiple byte-
+ range specifiers from a 1.1 client implies that the lient can parse
+ multipart/byteranges responses.
+
+ A range header might be forwarded by a 1.0 proxy that does not
+ understand multipart/byteranges; in this case the server MUST
+ delimit the message using methods defined in items 1,3 or 5 of
+ this section.
+
+ 5.By the server closing the connection. (Closing the connection
+ cannot be used to indicate the end of a request body, since that
+ would leave no possibility for the server to send back a response.)
+
+ For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
+ containing a message-body MUST include a valid Content-Length header
+ field unless the server is known to be HTTP/1.1 compliant. If a
+ request contains a message-body and a Content-Length is not given,
+ the server SHOULD respond with 400 (bad request) if it cannot
+ determine the length of the message, or with 411 (length required) if
+ it wishes to insist on receiving a valid Content-Length.
+
+ All HTTP/1.1 applications that receive entities MUST accept the
+ "chunked" transfer-coding (section 3.6), thus allowing this mechanism
+ to be used for messages when the message length cannot be determined
+ in advance.
+
+ Messages MUST NOT include both a Content-Length header field and a
+ non-identity transfer-coding. If the message does include a non-
+ identity transfer-coding, the Content-Length MUST be ignored.
+
+ When a Content-Length is given in a message where a message-body is
+ allowed, its field value MUST exactly match the number of OCTETs in
+ the message-body. HTTP/1.1 user agents MUST notify the user when an
+ invalid length is received and detected.
+
+4.5 General Header Fields
+
+ There are a few header fields which have general applicability for
+ both request and response messages, but which do not apply to the
+ entity being transferred. These header fields apply only to the
+
+
+
+Fielding, et al. Standards Track [Page 34]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ message being transmitted.
+
+ general-header = Cache-Control ; Section 14.9
+ | Connection ; Section 14.10
+ | Date ; Section 14.18
+ | Pragma ; Section 14.32
+ | Trailer ; Section 14.40
+ | Transfer-Encoding ; Section 14.41
+ | Upgrade ; Section 14.42
+ | Via ; Section 14.45
+ | Warning ; Section 14.46
+
+ General-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields may be given the semantics of general
+ header fields if all parties in the communication recognize them to
+ be general-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+5 Request
+
+ A request message from a client to a server includes, within the
+ first line of that message, the method to be applied to the resource,
+ the identifier of the resource, and the protocol version in use.
+
+ Request = Request-Line ; Section 5.1
+ *(( general-header ; Section 4.5
+ | request-header ; Section 5.3
+ | entity-header ) CRLF) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 4.3
+
+5.1 Request-Line
+
+ The Request-Line begins with a method token, followed by the
+ Request-URI and the protocol version, and ending with CRLF. The
+ elements are separated by SP characters. No CR or LF is allowed
+ except in the final CRLF sequence.
+
+ Request-Line = Method SP Request-URI SP HTTP-Version CRLF
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 35]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+5.1.1 Method
+
+ The Method token indicates the method to be performed on the
+ resource identified by the Request-URI. The method is case-sensitive.
+
+ Method = "OPTIONS" ; Section 9.2
+ | "GET" ; Section 9.3
+ | "HEAD" ; Section 9.4
+ | "POST" ; Section 9.5
+ | "PUT" ; Section 9.6
+ | "DELETE" ; Section 9.7
+ | "TRACE" ; Section 9.8
+ | "CONNECT" ; Section 9.9
+ | extension-method
+ extension-method = token
+
+ The list of methods allowed by a resource can be specified in an
+ Allow header field (section 14.7). The return code of the response
+ always notifies the client whether a method is currently allowed on a
+ resource, since the set of allowed methods can change dynamically. An
+ origin server SHOULD return the status code 405 (Method Not Allowed)
+ if the method is known by the origin server but not allowed for the
+ requested resource, and 501 (Not Implemented) if the method is
+ unrecognized or not implemented by the origin server. The methods GET
+ and HEAD MUST be supported by all general-purpose servers. All other
+ methods are OPTIONAL; however, if the above methods are implemented,
+ they MUST be implemented with the same semantics as those specified
+ in section 9.
+
+5.1.2 Request-URI
+
+ The Request-URI is a Uniform Resource Identifier (section 3.2) and
+ identifies the resource upon which to apply the request.
+
+ Request-URI = "*" | absoluteURI | abs_path | authority
+
+ The four options for Request-URI are dependent on the nature of the
+ request. The asterisk "*" means that the request does not apply to a
+ particular resource, but to the server itself, and is only allowed
+ when the method used does not necessarily apply to a resource. One
+ example would be
+
+ OPTIONS * HTTP/1.1
+
+ The absoluteURI form is REQUIRED when the request is being made to a
+ proxy. The proxy is requested to forward the request or service it
+ from a valid cache, and return the response. Note that the proxy MAY
+ forward the request on to another proxy or directly to the server
+
+
+
+Fielding, et al. Standards Track [Page 36]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ specified by the absoluteURI. In order to avoid request loops, a
+ proxy MUST be able to recognize all of its server names, including
+ any aliases, local variations, and the numeric IP address. An example
+ Request-Line would be:
+
+ GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1
+
+ To allow for transition to absoluteURIs in all requests in future
+ versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI
+ form in requests, even though HTTP/1.1 clients will only generate
+ them in requests to proxies.
+
+ The authority form is only used by the CONNECT method (section 9.9).
+
+ The most common form of Request-URI is that used to identify a
+ resource on an origin server or gateway. In this case the absolute
+ path of the URI MUST be transmitted (see section 3.2.1, abs_path) as
+ the Request-URI, and the network location of the URI (authority) MUST
+ be transmitted in a Host header field. For example, a client wishing
+ to retrieve the resource above directly from the origin server would
+ create a TCP connection to port 80 of the host "www.w3.org" and send
+ the lines:
+
+ GET /pub/WWW/TheProject.html HTTP/1.1
+ Host: www.w3.org
+
+ followed by the remainder of the Request. Note that the absolute path
+ cannot be empty; if none is present in the original URI, it MUST be
+ given as "/" (the server root).
+
+ The Request-URI is transmitted in the format specified in section
+ 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding
+ [42], the origin server MUST decode the Request-URI in order to
+ properly interpret the request. Servers SHOULD respond to invalid
+ Request-URIs with an appropriate status code.
+
+ A transparent proxy MUST NOT rewrite the "abs_path" part of the
+ received Request-URI when forwarding it to the next inbound server,
+ except as noted above to replace a null abs_path with "/".
+
+ Note: The "no rewrite" rule prevents the proxy from changing the
+ meaning of the request when the origin server is improperly using
+ a non-reserved URI character for a reserved purpose. Implementors
+ should be aware that some pre-HTTP/1.1 proxies have been known to
+ rewrite the Request-URI.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 37]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+5.2 The Resource Identified by a Request
+
+ The exact resource identified by an Internet request is determined by
+ examining both the Request-URI and the Host header field.
+
+ An origin server that does not allow resources to differ by the
+ requested host MAY ignore the Host header field value when
+ determining the resource identified by an HTTP/1.1 request. (But see
+ section 19.6.1.1 for other requirements on Host support in HTTP/1.1.)
+
+ An origin server that does differentiate resources based on the host
+ requested (sometimes referred to as virtual hosts or vanity host
+ names) MUST use the following rules for determining the requested
+ resource on an HTTP/1.1 request:
+
+ 1. If Request-URI is an absoluteURI, the host is part of the
+ Request-URI. Any Host header field value in the request MUST be
+ ignored.
+
+ 2. If the Request-URI is not an absoluteURI, and the request includes
+ a Host header field, the host is determined by the Host header
+ field value.
+
+ 3. If the host as determined by rule 1 or 2 is not a valid host on
+ the server, the response MUST be a 400 (Bad Request) error message.
+
+ Recipients of an HTTP/1.0 request that lacks a Host header field MAY
+ attempt to use heuristics (e.g., examination of the URI path for
+ something unique to a particular host) in order to determine what
+ exact resource is being requested.
+
+5.3 Request Header Fields
+
+ The request-header fields allow the client to pass additional
+ information about the request, and about the client itself, to the
+ server. These fields act as request modifiers, with semantics
+ equivalent to the parameters on a programming language method
+ invocation.
+
+ request-header = Accept ; Section 14.1
+ | Accept-Charset ; Section 14.2
+ | Accept-Encoding ; Section 14.3
+ | Accept-Language ; Section 14.4
+ | Authorization ; Section 14.8
+ | Expect ; Section 14.20
+ | From ; Section 14.22
+ | Host ; Section 14.23
+ | If-Match ; Section 14.24
+
+
+
+Fielding, et al. Standards Track [Page 38]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | If-Modified-Since ; Section 14.25
+ | If-None-Match ; Section 14.26
+ | If-Range ; Section 14.27
+ | If-Unmodified-Since ; Section 14.28
+ | Max-Forwards ; Section 14.31
+ | Proxy-Authorization ; Section 14.34
+ | Range ; Section 14.35
+ | Referer ; Section 14.36
+ | TE ; Section 14.39
+ | User-Agent ; Section 14.43
+
+ Request-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of request-
+ header fields if all parties in the communication recognize them to
+ be request-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+6 Response
+
+ After receiving and interpreting a request message, a server responds
+ with an HTTP response message.
+
+ Response = Status-Line ; Section 6.1
+ *(( general-header ; Section 4.5
+ | response-header ; Section 6.2
+ | entity-header ) CRLF) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 7.2
+
+6.1 Status-Line
+
+ The first line of a Response message is the Status-Line, consisting
+ of the protocol version followed by a numeric status code and its
+ associated textual phrase, with each element separated by SP
+ characters. No CR or LF is allowed except in the final CRLF sequence.
+
+ Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
+
+6.1.1 Status Code and Reason Phrase
+
+ The Status-Code element is a 3-digit integer result code of the
+ attempt to understand and satisfy the request. These codes are fully
+ defined in section 10. The Reason-Phrase is intended to give a short
+ textual description of the Status-Code. The Status-Code is intended
+ for use by automata and the Reason-Phrase is intended for the human
+ user. The client is not required to examine or display the Reason-
+ Phrase.
+
+
+
+Fielding, et al. Standards Track [Page 39]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The first digit of the Status-Code defines the class of response. The
+ last two digits do not have any categorization role. There are 5
+ values for the first digit:
+
+ - 1xx: Informational - Request received, continuing process
+
+ - 2xx: Success - The action was successfully received,
+ understood, and accepted
+
+ - 3xx: Redirection - Further action must be taken in order to
+ complete the request
+
+ - 4xx: Client Error - The request contains bad syntax or cannot
+ be fulfilled
+
+ - 5xx: Server Error - The server failed to fulfill an apparently
+ valid request
+
+ The individual values of the numeric status codes defined for
+ HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
+ presented below. The reason phrases listed here are only
+ recommendations -- they MAY be replaced by local equivalents without
+ affecting the protocol.
+
+ Status-Code =
+ "100" ; Section 10.1.1: Continue
+ | "101" ; Section 10.1.2: Switching Protocols
+ | "200" ; Section 10.2.1: OK
+ | "201" ; Section 10.2.2: Created
+ | "202" ; Section 10.2.3: Accepted
+ | "203" ; Section 10.2.4: Non-Authoritative Information
+ | "204" ; Section 10.2.5: No Content
+ | "205" ; Section 10.2.6: Reset Content
+ | "206" ; Section 10.2.7: Partial Content
+ | "300" ; Section 10.3.1: Multiple Choices
+ | "301" ; Section 10.3.2: Moved Permanently
+ | "302" ; Section 10.3.3: Found
+ | "303" ; Section 10.3.4: See Other
+ | "304" ; Section 10.3.5: Not Modified
+ | "305" ; Section 10.3.6: Use Proxy
+ | "307" ; Section 10.3.8: Temporary Redirect
+ | "400" ; Section 10.4.1: Bad Request
+ | "401" ; Section 10.4.2: Unauthorized
+ | "402" ; Section 10.4.3: Payment Required
+ | "403" ; Section 10.4.4: Forbidden
+ | "404" ; Section 10.4.5: Not Found
+ | "405" ; Section 10.4.6: Method Not Allowed
+ | "406" ; Section 10.4.7: Not Acceptable
+
+
+
+Fielding, et al. Standards Track [Page 40]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | "407" ; Section 10.4.8: Proxy Authentication Required
+ | "408" ; Section 10.4.9: Request Time-out
+ | "409" ; Section 10.4.10: Conflict
+ | "410" ; Section 10.4.11: Gone
+ | "411" ; Section 10.4.12: Length Required
+ | "412" ; Section 10.4.13: Precondition Failed
+ | "413" ; Section 10.4.14: Request Entity Too Large
+ | "414" ; Section 10.4.15: Request-URI Too Large
+ | "415" ; Section 10.4.16: Unsupported Media Type
+ | "416" ; Section 10.4.17: Requested range not satisfiable
+ | "417" ; Section 10.4.18: Expectation Failed
+ | "500" ; Section 10.5.1: Internal Server Error
+ | "501" ; Section 10.5.2: Not Implemented
+ | "502" ; Section 10.5.3: Bad Gateway
+ | "503" ; Section 10.5.4: Service Unavailable
+ | "504" ; Section 10.5.5: Gateway Time-out
+ | "505" ; Section 10.5.6: HTTP Version not supported
+ | extension-code
+
+ extension-code = 3DIGIT
+ Reason-Phrase = *<TEXT, excluding CR, LF>
+
+ HTTP status codes are extensible. HTTP applications are not required
+ to understand the meaning of all registered status codes, though such
+ understanding is obviously desirable. However, applications MUST
+ understand the class of any status code, as indicated by the first
+ digit, and treat any unrecognized response as being equivalent to the
+ x00 status code of that class, with the exception that an
+ unrecognized response MUST NOT be cached. For example, if an
+ unrecognized status code of 431 is received by the client, it can
+ safely assume that there was something wrong with its request and
+ treat the response as if it had received a 400 status code. In such
+ cases, user agents SHOULD present to the user the entity returned
+ with the response, since that entity is likely to include human-
+ readable information which will explain the unusual status.
+
+6.2 Response Header Fields
+
+ The response-header fields allow the server to pass additional
+ information about the response which cannot be placed in the Status-
+ Line. These header fields give information about the server and about
+ further access to the resource identified by the Request-URI.
+
+ response-header = Accept-Ranges ; Section 14.5
+ | Age ; Section 14.6
+ | ETag ; Section 14.19
+ | Location ; Section 14.30
+ | Proxy-Authenticate ; Section 14.33
+
+
+
+Fielding, et al. Standards Track [Page 41]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | Retry-After ; Section 14.37
+ | Server ; Section 14.38
+ | Vary ; Section 14.44
+ | WWW-Authenticate ; Section 14.47
+
+ Response-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of response-
+ header fields if all parties in the communication recognize them to
+ be response-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+7 Entity
+
+ Request and Response messages MAY transfer an entity if not otherwise
+ restricted by the request method or response status code. An entity
+ consists of entity-header fields and an entity-body, although some
+ responses will only include the entity-headers.
+
+ In this section, both sender and recipient refer to either the client
+ or the server, depending on who sends and who receives the entity.
+
+7.1 Entity Header Fields
+
+ Entity-header fields define metainformation about the entity-body or,
+ if no body is present, about the resource identified by the request.
+ Some of this metainformation is OPTIONAL; some might be REQUIRED by
+ portions of this specification.
+
+ entity-header = Allow ; Section 14.7
+ | Content-Encoding ; Section 14.11
+ | Content-Language ; Section 14.12
+ | Content-Length ; Section 14.13
+ | Content-Location ; Section 14.14
+ | Content-MD5 ; Section 14.15
+ | Content-Range ; Section 14.16
+ | Content-Type ; Section 14.17
+ | Expires ; Section 14.21
+ | Last-Modified ; Section 14.29
+ | extension-header
+
+ extension-header = message-header
+
+ The extension-header mechanism allows additional entity-header fields
+ to be defined without changing the protocol, but these fields cannot
+ be assumed to be recognizable by the recipient. Unrecognized header
+ fields SHOULD be ignored by the recipient and MUST be forwarded by
+ transparent proxies.
+
+
+
+Fielding, et al. Standards Track [Page 42]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+7.2 Entity Body
+
+ The entity-body (if any) sent with an HTTP request or response is in
+ a format and encoding defined by the entity-header fields.
+
+ entity-body = *OCTET
+
+ An entity-body is only present in a message when a message-body is
+ present, as described in section 4.3. The entity-body is obtained
+ from the message-body by decoding any Transfer-Encoding that might
+ have been applied to ensure safe and proper transfer of the message.
+
+7.2.1 Type
+
+ When an entity-body is included with a message, the data type of that
+ body is determined via the header fields Content-Type and Content-
+ Encoding. These define a two-layer, ordered encoding model:
+
+ entity-body := Content-Encoding( Content-Type( data ) )
+
+ Content-Type specifies the media type of the underlying data.
+ Content-Encoding may be used to indicate any additional content
+ codings applied to the data, usually for the purpose of data
+ compression, that are a property of the requested resource. There is
+ no default encoding.
+
+ Any HTTP/1.1 message containing an entity-body SHOULD include a
+ Content-Type header field defining the media type of that body. If
+ and only if the media type is not given by a Content-Type field, the
+ recipient MAY attempt to guess the media type via inspection of its
+ content and/or the name extension(s) of the URI used to identify the
+ resource. If the media type remains unknown, the recipient SHOULD
+ treat it as type "application/octet-stream".
+
+7.2.2 Entity Length
+
+ The entity-length of a message is the length of the message-body
+ before any transfer-codings have been applied. Section 4.4 defines
+ how the transfer-length of a message-body is determined.
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 43]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8 Connections
+
+8.1 Persistent Connections
+
+8.1.1 Purpose
+
+ Prior to persistent connections, a separate TCP connection was
+ established to fetch each URL, increasing the load on HTTP servers
+ and causing congestion on the Internet. The use of inline images and
+ other associated data often require a client to make multiple
+ requests of the same server in a short amount of time. Analysis of
+ these performance problems and results from a prototype
+ implementation are available [26] [30]. Implementation experience and
+ measurements of actual HTTP/1.1 (RFC 2068) implementations show good
+ results [39]. Alternatives have also been explored, for example,
+ T/TCP [27].
+
+ Persistent HTTP connections have a number of advantages:
+
+ - By opening and closing fewer TCP connections, CPU time is saved
+ in routers and hosts (clients, servers, proxies, gateways,
+ tunnels, or caches), and memory used for TCP protocol control
+ blocks can be saved in hosts.
+
+ - HTTP requests and responses can be pipelined on a connection.
+ Pipelining allows a client to make multiple requests without
+ waiting for each response, allowing a single TCP connection to
+ be used much more efficiently, with much lower elapsed time.
+
+ - Network congestion is reduced by reducing the number of packets
+ caused by TCP opens, and by allowing TCP sufficient time to
+ determine the congestion state of the network.
+
+ - Latency on subsequent requests is reduced since there is no time
+ spent in TCP's connection opening handshake.
+
+ - HTTP can evolve more gracefully, since errors can be reported
+ without the penalty of closing the TCP connection. Clients using
+ future versions of HTTP might optimistically try a new feature,
+ but if communicating with an older server, retry with old
+ semantics after an error is reported.
+
+ HTTP implementations SHOULD implement persistent connections.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 44]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.1.2 Overall Operation
+
+ A significant difference between HTTP/1.1 and earlier versions of
+ HTTP is that persistent connections are the default behavior of any
+ HTTP connection. That is, unless otherwise indicated, the client
+ SHOULD assume that the server will maintain a persistent connection,
+ even after error responses from the server.
+
+ Persistent connections provide a mechanism by which a client and a
+ server can signal the close of a TCP connection. This signaling takes
+ place using the Connection header field (section 14.10). Once a close
+ has been signaled, the client MUST NOT send any more requests on that
+ connection.
+
+8.1.2.1 Negotiation
+
+ An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to
+ maintain a persistent connection unless a Connection header including
+ the connection-token "close" was sent in the request. If the server
+ chooses to close the connection immediately after sending the
+ response, it SHOULD send a Connection header including the
+ connection-token close.
+
+ An HTTP/1.1 client MAY expect a connection to remain open, but would
+ decide to keep it open based on whether the response from a server
+ contains a Connection header with the connection-token close. In case
+ the client does not want to maintain a connection for more than that
+ request, it SHOULD send a Connection header including the
+ connection-token close.
+
+ If either the client or the server sends the close token in the
+ Connection header, that request becomes the last one for the
+ connection.
+
+ Clients and servers SHOULD NOT assume that a persistent connection is
+ maintained for HTTP versions less than 1.1 unless it is explicitly
+ signaled. See section 19.6.2 for more information on backward
+ compatibility with HTTP/1.0 clients.
+
+ In order to remain persistent, all messages on the connection MUST
+ have a self-defined message length (i.e., one not defined by closure
+ of the connection), as described in section 4.4.
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 45]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.1.2.2 Pipelining
+
+ A client that supports persistent connections MAY "pipeline" its
+ requests (i.e., send multiple requests without waiting for each
+ response). A server MUST send its responses to those requests in the
+ same order that the requests were received.
+
+ Clients which assume persistent connections and pipeline immediately
+ after connection establishment SHOULD be prepared to retry their
+ connection if the first pipelined attempt fails. If a client does
+ such a retry, it MUST NOT pipeline before it knows the connection is
+ persistent. Clients MUST also be prepared to resend their requests if
+ the server closes the connection before sending all of the
+ corresponding responses.
+
+ Clients SHOULD NOT pipeline requests using non-idempotent methods or
+ non-idempotent sequences of methods (see section 9.1.2). Otherwise, a
+ premature termination of the transport connection could lead to
+ indeterminate results. A client wishing to send a non-idempotent
+ request SHOULD wait to send that request until it has received the
+ response status for the previous request.
+
+8.1.3 Proxy Servers
+
+ It is especially important that proxies correctly implement the
+ properties of the Connection header field as specified in section
+ 14.10.
+
+ The proxy server MUST signal persistent connections separately with
+ its clients and the origin servers (or other proxy servers) that it
+ connects to. Each persistent connection applies to only one transport
+ link.
+
+ A proxy server MUST NOT establish a HTTP/1.1 persistent connection
+ with an HTTP/1.0 client (but see RFC 2068 [33] for information and
+ discussion of the problems with the Keep-Alive header implemented by
+ many HTTP/1.0 clients).
+
+8.1.4 Practical Considerations
+
+ Servers will usually have some time-out value beyond which they will
+ no longer maintain an inactive connection. Proxy servers might make
+ this a higher value since it is likely that the client will be making
+ more connections through the same server. The use of persistent
+ connections places no requirements on the length (or existence) of
+ this time-out for either the client or the server.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 46]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ When a client or server wishes to time-out it SHOULD issue a graceful
+ close on the transport connection. Clients and servers SHOULD both
+ constantly watch for the other side of the transport close, and
+ respond to it as appropriate. If a client or server does not detect
+ the other side's close promptly it could cause unnecessary resource
+ drain on the network.
+
+ A client, server, or proxy MAY close the transport connection at any
+ time. For example, a client might have started to send a new request
+ at the same time that the server has decided to close the "idle"
+ connection. From the server's point of view, the connection is being
+ closed while it was idle, but from the client's point of view, a
+ request is in progress.
+
+ This means that clients, servers, and proxies MUST be able to recover
+ from asynchronous close events. Client software SHOULD reopen the
+ transport connection and retransmit the aborted sequence of requests
+ without user interaction so long as the request sequence is
+ idempotent (see section 9.1.2). Non-idempotent methods or sequences
+ MUST NOT be automatically retried, although user agents MAY offer a
+ human operator the choice of retrying the request(s). Confirmation by
+ user-agent software with semantic understanding of the application
+ MAY substitute for user confirmation. The automatic retry SHOULD NOT
+ be repeated if the second sequence of requests fails.
+
+ Servers SHOULD always respond to at least one request per connection,
+ if at all possible. Servers SHOULD NOT close a connection in the
+ middle of transmitting a response, unless a network or client failure
+ is suspected.
+
+ Clients that use persistent connections SHOULD limit the number of
+ simultaneous connections that they maintain to a given server. A
+ single-user client SHOULD NOT maintain more than 2 connections with
+ any server or proxy. A proxy SHOULD use up to 2*N connections to
+ another server or proxy, where N is the number of simultaneously
+ active users. These guidelines are intended to improve HTTP response
+ times and avoid congestion.
+
+8.2 Message Transmission Requirements
+
+8.2.1 Persistent Connections and Flow Control
+
+ HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's
+ flow control mechanisms to resolve temporary overloads, rather than
+ terminating connections with the expectation that clients will retry.
+ The latter technique can exacerbate network congestion.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 47]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.2.2 Monitoring Connections for Error Status Messages
+
+ An HTTP/1.1 (or later) client sending a message-body SHOULD monitor
+ the network connection for an error status while it is transmitting
+ the request. If the client sees an error status, it SHOULD
+ immediately cease transmitting the body. If the body is being sent
+ using a "chunked" encoding (section 3.6), a zero length chunk and
+ empty trailer MAY be used to prematurely mark the end of the message.
+ If the body was preceded by a Content-Length header, the client MUST
+ close the connection.
+
+8.2.3 Use of the 100 (Continue) Status
+
+ The purpose of the 100 (Continue) status (see section 10.1.1) is to
+ allow a client that is sending a request message with a request body
+ to determine if the origin server is willing to accept the request
+ (based on the request headers) before the client sends the request
+ body. In some cases, it might either be inappropriate or highly
+ inefficient for the client to send the body if the server will reject
+ the message without looking at the body.
+
+ Requirements for HTTP/1.1 clients:
+
+ - If a client will wait for a 100 (Continue) response before
+ sending the request body, it MUST send an Expect request-header
+ field (section 14.20) with the "100-continue" expectation.
+
+ - A client MUST NOT send an Expect request-header field (section
+ 14.20) with the "100-continue" expectation if it does not intend
+ to send a request body.
+
+ Because of the presence of older implementations, the protocol allows
+ ambiguous situations in which a client may send "Expect: 100-
+ continue" without receiving either a 417 (Expectation Failed) status
+ or a 100 (Continue) status. Therefore, when a client sends this
+ header field to an origin server (possibly via a proxy) from which it
+ has never seen a 100 (Continue) status, the client SHOULD NOT wait
+ for an indefinite period before sending the request body.
+
+ Requirements for HTTP/1.1 origin servers:
+
+ - Upon receiving a request which includes an Expect request-header
+ field with the "100-continue" expectation, an origin server MUST
+ either respond with 100 (Continue) status and continue to read
+ from the input stream, or respond with a final status code. The
+ origin server MUST NOT wait for the request body before sending
+ the 100 (Continue) response. If it responds with a final status
+ code, it MAY close the transport connection or it MAY continue
+
+
+
+Fielding, et al. Standards Track [Page 48]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ to read and discard the rest of the request. It MUST NOT
+ perform the requested method if it returns a final status code.
+
+ - An origin server SHOULD NOT send a 100 (Continue) response if
+ the request message does not include an Expect request-header
+ field with the "100-continue" expectation, and MUST NOT send a
+ 100 (Continue) response if such a request comes from an HTTP/1.0
+ (or earlier) client. There is an exception to this rule: for
+ compatibility with RFC 2068, a server MAY send a 100 (Continue)
+ status in response to an HTTP/1.1 PUT or POST request that does
+ not include an Expect request-header field with the "100-
+ continue" expectation. This exception, the purpose of which is
+ to minimize any client processing delays associated with an
+ undeclared wait for 100 (Continue) status, applies only to
+ HTTP/1.1 requests, and not to requests with any other HTTP-
+ version value.
+
+ - An origin server MAY omit a 100 (Continue) response if it has
+ already received some or all of the request body for the
+ corresponding request.
+
+ - An origin server that sends a 100 (Continue) response MUST
+ ultimately send a final status code, once the request body is
+ received and processed, unless it terminates the transport
+ connection prematurely.
+
+ - If an origin server receives a request that does not include an
+ Expect request-header field with the "100-continue" expectation,
+ the request includes a request body, and the server responds
+ with a final status code before reading the entire request body
+ from the transport connection, then the server SHOULD NOT close
+ the transport connection until it has read the entire request,
+ or until the client closes the connection. Otherwise, the client
+ might not reliably receive the response message. However, this
+ requirement is not be construed as preventing a server from
+ defending itself against denial-of-service attacks, or from
+ badly broken client implementations.
+
+ Requirements for HTTP/1.1 proxies:
+
+ - If a proxy receives a request that includes an Expect request-
+ header field with the "100-continue" expectation, and the proxy
+ either knows that the next-hop server complies with HTTP/1.1 or
+ higher, or does not know the HTTP version of the next-hop
+ server, it MUST forward the request, including the Expect header
+ field.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 49]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If the proxy knows that the version of the next-hop server is
+ HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST
+ respond with a 417 (Expectation Failed) status.
+
+ - Proxies SHOULD maintain a cache recording the HTTP version
+ numbers received from recently-referenced next-hop servers.
+
+ - A proxy MUST NOT forward a 100 (Continue) response if the
+ request message was received from an HTTP/1.0 (or earlier)
+ client and did not include an Expect request-header field with
+ the "100-continue" expectation. This requirement overrides the
+ general rule for forwarding of 1xx responses (see section 10.1).
+
+8.2.4 Client Behavior if Server Prematurely Closes Connection
+
+ If an HTTP/1.1 client sends a request which includes a request body,
+ but which does not include an Expect request-header field with the
+ "100-continue" expectation, and if the client is not directly
+ connected to an HTTP/1.1 origin server, and if the client sees the
+ connection close before receiving any status from the server, the
+ client SHOULD retry the request. If the client does retry this
+ request, it MAY use the following "binary exponential backoff"
+ algorithm to be assured of obtaining a reliable response:
+
+ 1. Initiate a new connection to the server
+
+ 2. Transmit the request-headers
+
+ 3. Initialize a variable R to the estimated round-trip time to the
+ server (e.g., based on the time it took to establish the
+ connection), or to a constant value of 5 seconds if the round-
+ trip time is not available.
+
+ 4. Compute T = R * (2**N), where N is the number of previous
+ retries of this request.
+
+ 5. Wait either for an error response from the server, or for T
+ seconds (whichever comes first)
+
+ 6. If no error response is received, after T seconds transmit the
+ body of the request.
+
+ 7. If client sees that the connection is closed prematurely,
+ repeat from step 1 until the request is accepted, an error
+ response is received, or the user becomes impatient and
+ terminates the retry process.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 50]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If at any point an error status is received, the client
+
+ - SHOULD NOT continue and
+
+ - SHOULD close the connection if it has not completed sending the
+ request message.
+
+9 Method Definitions
+
+ The set of common methods for HTTP/1.1 is defined below. Although
+ this set can be expanded, additional methods cannot be assumed to
+ share the same semantics for separately extended clients and servers.
+
+ The Host request-header field (section 14.23) MUST accompany all
+ HTTP/1.1 requests.
+
+9.1 Safe and Idempotent Methods
+
+9.1.1 Safe Methods
+
+ Implementors should be aware that the software represents the user in
+ their interactions over the Internet, and should be careful to allow
+ the user to be aware of any actions they might take which may have an
+ unexpected significance to themselves or others.
+
+ In particular, the convention has been established that the GET and
+ HEAD methods SHOULD NOT have the significance of taking an action
+ other than retrieval. These methods ought to be considered "safe".
+ This allows user agents to represent other methods, such as POST, PUT
+ and DELETE, in a special way, so that the user is made aware of the
+ fact that a possibly unsafe action is being requested.
+
+ Naturally, it is not possible to ensure that the server does not
+ generate side-effects as a result of performing a GET request; in
+ fact, some dynamic resources consider that a feature. The important
+ distinction here is that the user did not request the side-effects,
+ so therefore cannot be held accountable for them.
+
+9.1.2 Idempotent Methods
+
+ Methods can also have the property of "idempotence" in that (aside
+ from error or expiration issues) the side-effects of N > 0 identical
+ requests is the same as for a single request. The methods GET, HEAD,
+ PUT and DELETE share this property. Also, the methods OPTIONS and
+ TRACE SHOULD NOT have side effects, and so are inherently idempotent.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 51]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ However, it is possible that a sequence of several requests is non-
+ idempotent, even if all of the methods executed in that sequence are
+ idempotent. (A sequence is idempotent if a single execution of the
+ entire sequence always yields a result that is not changed by a
+ reexecution of all, or part, of that sequence.) For example, a
+ sequence is non-idempotent if its result depends on a value that is
+ later modified in the same sequence.
+
+ A sequence that never has side effects is idempotent, by definition
+ (provided that no concurrent operations are being executed on the
+ same set of resources).
+
+9.2 OPTIONS
+
+ The OPTIONS method represents a request for information about the
+ communication options available on the request/response chain
+ identified by the Request-URI. This method allows the client to
+ determine the options and/or requirements associated with a resource,
+ or the capabilities of a server, without implying a resource action
+ or initiating a resource retrieval.
+
+ Responses to this method are not cacheable.
+
+ If the OPTIONS request includes an entity-body (as indicated by the
+ presence of Content-Length or Transfer-Encoding), then the media type
+ MUST be indicated by a Content-Type field. Although this
+ specification does not define any use for such a body, future
+ extensions to HTTP might use the OPTIONS body to make more detailed
+ queries on the server. A server that does not support such an
+ extension MAY discard the request body.
+
+ If the Request-URI is an asterisk ("*"), the OPTIONS request is
+ intended to apply to the server in general rather than to a specific
+ resource. Since a server's communication options typically depend on
+ the resource, the "*" request is only useful as a "ping" or "no-op"
+ type of method; it does nothing beyond allowing the client to test
+ the capabilities of the server. For example, this can be used to test
+ a proxy for HTTP/1.1 compliance (or lack thereof).
+
+ If the Request-URI is not an asterisk, the OPTIONS request applies
+ only to the options that are available when communicating with that
+ resource.
+
+ A 200 response SHOULD include any header fields that indicate
+ optional features implemented by the server and applicable to that
+ resource (e.g., Allow), possibly including extensions not defined by
+ this specification. The response body, if any, SHOULD also include
+ information about the communication options. The format for such a
+
+
+
+Fielding, et al. Standards Track [Page 52]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ body is not defined by this specification, but might be defined by
+ future extensions to HTTP. Content negotiation MAY be used to select
+ the appropriate response format. If no response body is included, the
+ response MUST include a Content-Length field with a field-value of
+ "0".
+
+ The Max-Forwards request-header field MAY be used to target a
+ specific proxy in the request chain. When a proxy receives an OPTIONS
+ request on an absoluteURI for which request forwarding is permitted,
+ the proxy MUST check for a Max-Forwards field. If the Max-Forwards
+ field-value is zero ("0"), the proxy MUST NOT forward the message;
+ instead, the proxy SHOULD respond with its own communication options.
+ If the Max-Forwards field-value is an integer greater than zero, the
+ proxy MUST decrement the field-value when it forwards the request. If
+ no Max-Forwards field is present in the request, then the forwarded
+ request MUST NOT include a Max-Forwards field.
+
+9.3 GET
+
+ The GET method means retrieve whatever information (in the form of an
+ entity) is identified by the Request-URI. If the Request-URI refers
+ to a data-producing process, it is the produced data which shall be
+ returned as the entity in the response and not the source text of the
+ process, unless that text happens to be the output of the process.
+
+ The semantics of the GET method change to a "conditional GET" if the
+ request message includes an If-Modified-Since, If-Unmodified-Since,
+ If-Match, If-None-Match, or If-Range header field. A conditional GET
+ method requests that the entity be transferred only under the
+ circumstances described by the conditional header field(s). The
+ conditional GET method is intended to reduce unnecessary network
+ usage by allowing cached entities to be refreshed without requiring
+ multiple requests or transferring data already held by the client.
+
+ The semantics of the GET method change to a "partial GET" if the
+ request message includes a Range header field. A partial GET requests
+ that only part of the entity be transferred, as described in section
+ 14.35. The partial GET method is intended to reduce unnecessary
+ network usage by allowing partially-retrieved entities to be
+ completed without transferring data already held by the client.
+
+ The response to a GET request is cacheable if and only if it meets
+ the requirements for HTTP caching described in section 13.
+
+ See section 15.1.3 for security considerations when used for forms.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 53]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+9.4 HEAD
+
+ The HEAD method is identical to GET except that the server MUST NOT
+ return a message-body in the response. The metainformation contained
+ in the HTTP headers in response to a HEAD request SHOULD be identical
+ to the information sent in response to a GET request. This method can
+ be used for obtaining metainformation about the entity implied by the
+ request without transferring the entity-body itself. This method is
+ often used for testing hypertext links for validity, accessibility,
+ and recent modification.
+
+ The response to a HEAD request MAY be cacheable in the sense that the
+ information contained in the response MAY be used to update a
+ previously cached entity from that resource. If the new field values
+ indicate that the cached entity differs from the current entity (as
+ would be indicated by a change in Content-Length, Content-MD5, ETag
+ or Last-Modified), then the cache MUST treat the cache entry as
+ stale.
+
+9.5 POST
+
+ The POST method is used to request that the origin server accept the
+ entity enclosed in the request as a new subordinate of the resource
+ identified by the Request-URI in the Request-Line. POST is designed
+ to allow a uniform method to cover the following functions:
+
+ - Annotation of existing resources;
+
+ - Posting a message to a bulletin board, newsgroup, mailing list,
+ or similar group of articles;
+
+ - Providing a block of data, such as the result of submitting a
+ form, to a data-handling process;
+
+ - Extending a database through an append operation.
+
+ The actual function performed by the POST method is determined by the
+ server and is usually dependent on the Request-URI. The posted entity
+ is subordinate to that URI in the same way that a file is subordinate
+ to a directory containing it, a news article is subordinate to a
+ newsgroup to which it is posted, or a record is subordinate to a
+ database.
+
+ The action performed by the POST method might not result in a
+ resource that can be identified by a URI. In this case, either 200
+ (OK) or 204 (No Content) is the appropriate response status,
+ depending on whether or not the response includes an entity that
+ describes the result.
+
+
+
+Fielding, et al. Standards Track [Page 54]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If a resource has been created on the origin server, the response
+ SHOULD be 201 (Created) and contain an entity which describes the
+ status of the request and refers to the new resource, and a Location
+ header (see section 14.30).
+
+ Responses to this method are not cacheable, unless the response
+ includes appropriate Cache-Control or Expires header fields. However,
+ the 303 (See Other) response can be used to direct the user agent to
+ retrieve a cacheable resource.
+
+ POST requests MUST obey the message transmission requirements set out
+ in section 8.2.
+
+ See section 15.1.3 for security considerations.
+
+9.6 PUT
+
+ The PUT method requests that the enclosed entity be stored under the
+ supplied Request-URI. If the Request-URI refers to an already
+ existing resource, the enclosed entity SHOULD be considered as a
+ modified version of the one residing on the origin server. If the
+ Request-URI does not point to an existing resource, and that URI is
+ capable of being defined as a new resource by the requesting user
+ agent, the origin server can create the resource with that URI. If a
+ new resource is created, the origin server MUST inform the user agent
+ via the 201 (Created) response. If an existing resource is modified,
+ either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
+ to indicate successful completion of the request. If the resource
+ could not be created or modified with the Request-URI, an appropriate
+ error response SHOULD be given that reflects the nature of the
+ problem. The recipient of the entity MUST NOT ignore any Content-*
+ (e.g. Content-Range) headers that it does not understand or implement
+ and MUST return a 501 (Not Implemented) response in such cases.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries SHOULD be
+ treated as stale. Responses to this method are not cacheable.
+
+ The fundamental difference between the POST and PUT requests is
+ reflected in the different meaning of the Request-URI. The URI in a
+ POST request identifies the resource that will handle the enclosed
+ entity. That resource might be a data-accepting process, a gateway to
+ some other protocol, or a separate entity that accepts annotations.
+ In contrast, the URI in a PUT request identifies the entity enclosed
+ with the request -- the user agent knows what URI is intended and the
+ server MUST NOT attempt to apply the request to some other resource.
+ If the server desires that the request be applied to a different URI,
+
+
+
+
+Fielding, et al. Standards Track [Page 55]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ it MUST send a 301 (Moved Permanently) response; the user agent MAY
+ then make its own decision regarding whether or not to redirect the
+ request.
+
+ A single resource MAY be identified by many different URIs. For
+ example, an article might have a URI for identifying "the current
+ version" which is separate from the URI identifying each particular
+ version. In this case, a PUT request on a general URI might result in
+ several other URIs being defined by the origin server.
+
+ HTTP/1.1 does not define how a PUT method affects the state of an
+ origin server.
+
+ PUT requests MUST obey the message transmission requirements set out
+ in section 8.2.
+
+ Unless otherwise specified for a particular entity-header, the
+ entity-headers in the PUT request SHOULD be applied to the resource
+ created or modified by the PUT.
+
+9.7 DELETE
+
+ The DELETE method requests that the origin server delete the resource
+ identified by the Request-URI. This method MAY be overridden by human
+ intervention (or other means) on the origin server. The client cannot
+ be guaranteed that the operation has been carried out, even if the
+ status code returned from the origin server indicates that the action
+ has been completed successfully. However, the server SHOULD NOT
+ indicate success unless, at the time the response is given, it
+ intends to delete the resource or move it to an inaccessible
+ location.
+
+ A successful response SHOULD be 200 (OK) if the response includes an
+ entity describing the status, 202 (Accepted) if the action has not
+ yet been enacted, or 204 (No Content) if the action has been enacted
+ but the response does not include an entity.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries SHOULD be
+ treated as stale. Responses to this method are not cacheable.
+
+9.8 TRACE
+
+ The TRACE method is used to invoke a remote, application-layer loop-
+ back of the request message. The final recipient of the request
+ SHOULD reflect the message received back to the client as the
+ entity-body of a 200 (OK) response. The final recipient is either the
+
+
+
+
+Fielding, et al. Standards Track [Page 56]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ origin server or the first proxy or gateway to receive a Max-Forwards
+ value of zero (0) in the request (see section 14.31). A TRACE request
+ MUST NOT include an entity.
+
+ TRACE allows the client to see what is being received at the other
+ end of the request chain and use that data for testing or diagnostic
+ information. The value of the Via header field (section 14.45) is of
+ particular interest, since it acts as a trace of the request chain.
+ Use of the Max-Forwards header field allows the client to limit the
+ length of the request chain, which is useful for testing a chain of
+ proxies forwarding messages in an infinite loop.
+
+ If the request is valid, the response SHOULD contain the entire
+ request message in the entity-body, with a Content-Type of
+ "message/http". Responses to this method MUST NOT be cached.
+
+9.9 CONNECT
+
+ This specification reserves the method name CONNECT for use with a
+ proxy that can dynamically switch to being a tunnel (e.g. SSL
+ tunneling [44]).
+
+10 Status Code Definitions
+
+ Each Status-Code is described below, including a description of which
+ method(s) it can follow and any metainformation required in the
+ response.
+
+10.1 Informational 1xx
+
+ This class of status code indicates a provisional response,
+ consisting only of the Status-Line and optional headers, and is
+ terminated by an empty line. There are no required headers for this
+ class of status code. Since HTTP/1.0 did not define any 1xx status
+ codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client
+ except under experimental conditions.
+
+ A client MUST be prepared to accept one or more 1xx status responses
+ prior to a regular response, even if the client does not expect a 100
+ (Continue) status message. Unexpected 1xx status responses MAY be
+ ignored by a user agent.
+
+ Proxies MUST forward 1xx responses, unless the connection between the
+ proxy and its client has been closed, or unless the proxy itself
+ requested the generation of the 1xx response. (For example, if a
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 57]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ proxy adds a "Expect: 100-continue" field when it forwards a request,
+ then it need not forward the corresponding 100 (Continue)
+ response(s).)
+
+10.1.1 100 Continue
+
+ The client SHOULD continue with its request. This interim response is
+ used to inform the client that the initial part of the request has
+ been received and has not yet been rejected by the server. The client
+ SHOULD continue by sending the remainder of the request or, if the
+ request has already been completed, ignore this response. The server
+ MUST send a final response after the request has been completed. See
+ section 8.2.3 for detailed discussion of the use and handling of this
+ status code.
+
+10.1.2 101 Switching Protocols
+
+ The server understands and is willing to comply with the client's
+ request, via the Upgrade message header field (section 14.42), for a
+ change in the application protocol being used on this connection. The
+ server will switch protocols to those defined by the response's
+ Upgrade header field immediately after the empty line which
+ terminates the 101 response.
+
+ The protocol SHOULD be switched only when it is advantageous to do
+ so. For example, switching to a newer version of HTTP is advantageous
+ over older versions, and switching to a real-time, synchronous
+ protocol might be advantageous when delivering resources that use
+ such features.
+
+10.2 Successful 2xx
+
+ This class of status code indicates that the client's request was
+ successfully received, understood, and accepted.
+
+10.2.1 200 OK
+
+ The request has succeeded. The information returned with the response
+ is dependent on the method used in the request, for example:
+
+ GET an entity corresponding to the requested resource is sent in
+ the response;
+
+ HEAD the entity-header fields corresponding to the requested
+ resource are sent in the response without any message-body;
+
+ POST an entity describing or containing the result of the action;
+
+
+
+
+Fielding, et al. Standards Track [Page 58]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ TRACE an entity containing the request message as received by the
+ end server.
+
+10.2.2 201 Created
+
+ The request has been fulfilled and resulted in a new resource being
+ created. The newly created resource can be referenced by the URI(s)
+ returned in the entity of the response, with the most specific URI
+ for the resource given by a Location header field. The response
+ SHOULD include an entity containing a list of resource
+ characteristics and location(s) from which the user or user agent can
+ choose the one most appropriate. The entity format is specified by
+ the media type given in the Content-Type header field. The origin
+ server MUST create the resource before returning the 201 status code.
+ If the action cannot be carried out immediately, the server SHOULD
+ respond with 202 (Accepted) response instead.
+
+ A 201 response MAY contain an ETag response header field indicating
+ the current value of the entity tag for the requested variant just
+ created, see section 14.19.
+
+10.2.3 202 Accepted
+
+ The request has been accepted for processing, but the processing has
+ not been completed. The request might or might not eventually be
+ acted upon, as it might be disallowed when processing actually takes
+ place. There is no facility for re-sending a status code from an
+ asynchronous operation such as this.
+
+ The 202 response is intentionally non-committal. Its purpose is to
+ allow a server to accept a request for some other process (perhaps a
+ batch-oriented process that is only run once per day) without
+ requiring that the user agent's connection to the server persist
+ until the process is completed. The entity returned with this
+ response SHOULD include an indication of the request's current status
+ and either a pointer to a status monitor or some estimate of when the
+ user can expect the request to be fulfilled.
+
+10.2.4 203 Non-Authoritative Information
+
+ The returned metainformation in the entity-header is not the
+ definitive set as available from the origin server, but is gathered
+ from a local or a third-party copy. The set presented MAY be a subset
+ or superset of the original version. For example, including local
+ annotation information about the resource might result in a superset
+ of the metainformation known by the origin server. Use of this
+ response code is not required and is only appropriate when the
+ response would otherwise be 200 (OK).
+
+
+
+Fielding, et al. Standards Track [Page 59]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.2.5 204 No Content
+
+ The server has fulfilled the request but does not need to return an
+ entity-body, and might want to return updated metainformation. The
+ response MAY include new or updated metainformation in the form of
+ entity-headers, which if present SHOULD be associated with the
+ requested variant.
+
+ If the client is a user agent, it SHOULD NOT change its document view
+ from that which caused the request to be sent. This response is
+ primarily intended to allow input for actions to take place without
+ causing a change to the user agent's active document view, although
+ any new or updated metainformation SHOULD be applied to the document
+ currently in the user agent's active view.
+
+ The 204 response MUST NOT include a message-body, and thus is always
+ terminated by the first empty line after the header fields.
+
+10.2.6 205 Reset Content
+
+ The server has fulfilled the request and the user agent SHOULD reset
+ the document view which caused the request to be sent. This response
+ is primarily intended to allow input for actions to take place via
+ user input, followed by a clearing of the form in which the input is
+ given so that the user can easily initiate another input action. The
+ response MUST NOT include an entity.
+
+10.2.7 206 Partial Content
+
+ The server has fulfilled the partial GET request for the resource.
+ The request MUST have included a Range header field (section 14.35)
+ indicating the desired range, and MAY have included an If-Range
+ header field (section 14.27) to make the request conditional.
+
+ The response MUST include the following header fields:
+
+ - Either a Content-Range header field (section 14.16) indicating
+ the range included with this response, or a multipart/byteranges
+ Content-Type including Content-Range fields for each part. If a
+ Content-Length header field is present in the response, its
+ value MUST match the actual number of OCTETs transmitted in the
+ message-body.
+
+ - Date
+
+ - ETag and/or Content-Location, if the header would have been sent
+ in a 200 response to the same request
+
+
+
+
+Fielding, et al. Standards Track [Page 60]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - Expires, Cache-Control, and/or Vary, if the field-value might
+ differ from that sent in any previous response for the same
+ variant
+
+ If the 206 response is the result of an If-Range request that used a
+ strong cache validator (see section 13.3.3), the response SHOULD NOT
+ include other entity-headers. If the response is the result of an
+ If-Range request that used a weak validator, the response MUST NOT
+ include other entity-headers; this prevents inconsistencies between
+ cached entity-bodies and updated headers. Otherwise, the response
+ MUST include all of the entity-headers that would have been returned
+ with a 200 (OK) response to the same request.
+
+ A cache MUST NOT combine a 206 response with other previously cached
+ content if the ETag or Last-Modified headers do not match exactly,
+ see 13.5.4.
+
+ A cache that does not support the Range and Content-Range headers
+ MUST NOT cache 206 (Partial) responses.
+
+10.3 Redirection 3xx
+
+ This class of status code indicates that further action needs to be
+ taken by the user agent in order to fulfill the request. The action
+ required MAY be carried out by the user agent without interaction
+ with the user if and only if the method used in the second request is
+ GET or HEAD. A client SHOULD detect infinite redirection loops, since
+ such loops generate network traffic for each redirection.
+
+ Note: previous versions of this specification recommended a
+ maximum of five redirections. Content developers should be aware
+ that there might be clients that implement such a fixed
+ limitation.
+
+10.3.1 300 Multiple Choices
+
+ The requested resource corresponds to any one of a set of
+ representations, each with its own specific location, and agent-
+ driven negotiation information (section 12) is being provided so that
+ the user (or user agent) can select a preferred representation and
+ redirect its request to that location.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of resource characteristics and location(s) from
+ which the user or user agent can choose the one most appropriate. The
+ entity format is specified by the media type given in the Content-
+ Type header field. Depending upon the format and the capabilities of
+
+
+
+
+Fielding, et al. Standards Track [Page 61]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the user agent, selection of the most appropriate choice MAY be
+ performed automatically. However, this specification does not define
+ any standard for such automatic selection.
+
+ If the server has a preferred choice of representation, it SHOULD
+ include the specific URI for that representation in the Location
+ field; user agents MAY use the Location field value for automatic
+ redirection. This response is cacheable unless indicated otherwise.
+
+10.3.2 301 Moved Permanently
+
+ The requested resource has been assigned a new permanent URI and any
+ future references to this resource SHOULD use one of the returned
+ URIs. Clients with link editing capabilities ought to automatically
+ re-link references to the Request-URI to one or more of the new
+ references returned by the server, where possible. This response is
+ cacheable unless indicated otherwise.
+
+ The new permanent URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+ If the 301 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: When automatically redirecting a POST request after
+ receiving a 301 status code, some existing HTTP/1.0 user agents
+ will erroneously change it into a GET request.
+
+10.3.3 302 Found
+
+ The requested resource resides temporarily under a different URI.
+ Since the redirection might be altered on occasion, the client SHOULD
+ continue to use the Request-URI for future requests. This response
+ is only cacheable if indicated by a Cache-Control or Expires header
+ field.
+
+ The temporary URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 62]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the 302 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: RFC 1945 and RFC 2068 specify that the client is not allowed
+ to change the method on the redirected request. However, most
+ existing user agent implementations treat 302 as if it were a 303
+ response, performing a GET on the Location field-value regardless
+ of the original request method. The status codes 303 and 307 have
+ been added for servers that wish to make unambiguously clear which
+ kind of reaction is expected of the client.
+
+10.3.4 303 See Other
+
+ The response to the request can be found under a different URI and
+ SHOULD be retrieved using a GET method on that resource. This method
+ exists primarily to allow the output of a POST-activated script to
+ redirect the user agent to a selected resource. The new URI is not a
+ substitute reference for the originally requested resource. The 303
+ response MUST NOT be cached, but the response to the second
+ (redirected) request might be cacheable.
+
+ The different URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+ Note: Many pre-HTTP/1.1 user agents do not understand the 303
+ status. When interoperability with such clients is a concern, the
+ 302 status code may be used instead, since most user agents react
+ to a 302 response as described here for 303.
+
+10.3.5 304 Not Modified
+
+ If the client has performed a conditional GET request and access is
+ allowed, but the document has not been modified, the server SHOULD
+ respond with this status code. The 304 response MUST NOT contain a
+ message-body, and thus is always terminated by the first empty line
+ after the header fields.
+
+ The response MUST include the following header fields:
+
+ - Date, unless its omission is required by section 14.18.1
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 63]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If a clockless origin server obeys these rules, and proxies and
+ clients add their own Date to any response received without one (as
+ already specified by [RFC 2068], section 14.19), caches will operate
+ correctly.
+
+ - ETag and/or Content-Location, if the header would have been sent
+ in a 200 response to the same request
+
+ - Expires, Cache-Control, and/or Vary, if the field-value might
+ differ from that sent in any previous response for the same
+ variant
+
+ If the conditional GET used a strong cache validator (see section
+ 13.3.3), the response SHOULD NOT include other entity-headers.
+ Otherwise (i.e., the conditional GET used a weak validator), the
+ response MUST NOT include other entity-headers; this prevents
+ inconsistencies between cached entity-bodies and updated headers.
+
+ If a 304 response indicates an entity not currently cached, then the
+ cache MUST disregard the response and repeat the request without the
+ conditional.
+
+ If a cache uses a received 304 response to update a cache entry, the
+ cache MUST update the entry to reflect any new field values given in
+ the response.
+
+10.3.6 305 Use Proxy
+
+ The requested resource MUST be accessed through the proxy given by
+ the Location field. The Location field gives the URI of the proxy.
+ The recipient is expected to repeat this single request via the
+ proxy. 305 responses MUST only be generated by origin servers.
+
+ Note: RFC 2068 was not clear that 305 was intended to redirect a
+ single request, and to be generated by origin servers only. Not
+ observing these limitations has significant security consequences.
+
+10.3.7 306 (Unused)
+
+ The 306 status code was used in a previous version of the
+ specification, is no longer used, and the code is reserved.
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 64]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.3.8 307 Temporary Redirect
+
+ The requested resource resides temporarily under a different URI.
+ Since the redirection MAY be altered on occasion, the client SHOULD
+ continue to use the Request-URI for future requests. This response
+ is only cacheable if indicated by a Cache-Control or Expires header
+ field.
+
+ The temporary URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s) , since many pre-HTTP/1.1 user agents do not
+ understand the 307 status. Therefore, the note SHOULD contain the
+ information necessary for a user to repeat the original request on
+ the new URI.
+
+ If the 307 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+10.4 Client Error 4xx
+
+ The 4xx class of status code is intended for cases in which the
+ client seems to have erred. Except when responding to a HEAD request,
+ the server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. These status codes are applicable to any request method.
+ User agents SHOULD display any included entity to the user.
+
+ If the client is sending data, a server implementation using TCP
+ SHOULD be careful to ensure that the client acknowledges receipt of
+ the packet(s) containing the response, before the server closes the
+ input connection. If the client continues sending data to the server
+ after the close, the server's TCP stack will send a reset packet to
+ the client, which may erase the client's unacknowledged input buffers
+ before they can be read and interpreted by the HTTP application.
+
+10.4.1 400 Bad Request
+
+ The request could not be understood by the server due to malformed
+ syntax. The client SHOULD NOT repeat the request without
+ modifications.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 65]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.2 401 Unauthorized
+
+ The request requires user authentication. The response MUST include a
+ WWW-Authenticate header field (section 14.47) containing a challenge
+ applicable to the requested resource. The client MAY repeat the
+ request with a suitable Authorization header field (section 14.8). If
+ the request already included Authorization credentials, then the 401
+ response indicates that authorization has been refused for those
+ credentials. If the 401 response contains the same challenge as the
+ prior response, and the user agent has already attempted
+ authentication at least once, then the user SHOULD be presented the
+ entity that was given in the response, since that entity might
+ include relevant diagnostic information. HTTP access authentication
+ is explained in "HTTP Authentication: Basic and Digest Access
+ Authentication" [43].
+
+10.4.3 402 Payment Required
+
+ This code is reserved for future use.
+
+10.4.4 403 Forbidden
+
+ The server understood the request, but is refusing to fulfill it.
+ Authorization will not help and the request SHOULD NOT be repeated.
+ If the request method was not HEAD and the server wishes to make
+ public why the request has not been fulfilled, it SHOULD describe the
+ reason for the refusal in the entity. If the server does not wish to
+ make this information available to the client, the status code 404
+ (Not Found) can be used instead.
+
+10.4.5 404 Not Found
+
+ The server has not found anything matching the Request-URI. No
+ indication is given of whether the condition is temporary or
+ permanent. The 410 (Gone) status code SHOULD be used if the server
+ knows, through some internally configurable mechanism, that an old
+ resource is permanently unavailable and has no forwarding address.
+ This status code is commonly used when the server does not wish to
+ reveal exactly why the request has been refused, or when no other
+ response is applicable.
+
+10.4.6 405 Method Not Allowed
+
+ The method specified in the Request-Line is not allowed for the
+ resource identified by the Request-URI. The response MUST include an
+ Allow header containing a list of valid methods for the requested
+ resource.
+
+
+
+
+Fielding, et al. Standards Track [Page 66]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.7 406 Not Acceptable
+
+ The resource identified by the request is only capable of generating
+ response entities which have content characteristics not acceptable
+ according to the accept headers sent in the request.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of available entity characteristics and location(s)
+ from which the user or user agent can choose the one most
+ appropriate. The entity format is specified by the media type given
+ in the Content-Type header field. Depending upon the format and the
+ capabilities of the user agent, selection of the most appropriate
+ choice MAY be performed automatically. However, this specification
+ does not define any standard for such automatic selection.
+
+ Note: HTTP/1.1 servers are allowed to return responses which are
+ not acceptable according to the accept headers sent in the
+ request. In some cases, this may even be preferable to sending a
+ 406 response. User agents are encouraged to inspect the headers of
+ an incoming response to determine if it is acceptable.
+
+ If the response could be unacceptable, a user agent SHOULD
+ temporarily stop receipt of more data and query the user for a
+ decision on further actions.
+
+10.4.8 407 Proxy Authentication Required
+
+ This code is similar to 401 (Unauthorized), but indicates that the
+ client must first authenticate itself with the proxy. The proxy MUST
+ return a Proxy-Authenticate header field (section 14.33) containing a
+ challenge applicable to the proxy for the requested resource. The
+ client MAY repeat the request with a suitable Proxy-Authorization
+ header field (section 14.34). HTTP access authentication is explained
+ in "HTTP Authentication: Basic and Digest Access Authentication"
+ [43].
+
+10.4.9 408 Request Timeout
+
+ The client did not produce a request within the time that the server
+ was prepared to wait. The client MAY repeat the request without
+ modifications at any later time.
+
+10.4.10 409 Conflict
+
+ The request could not be completed due to a conflict with the current
+ state of the resource. This code is only allowed in situations where
+ it is expected that the user might be able to resolve the conflict
+ and resubmit the request. The response body SHOULD include enough
+
+
+
+Fielding, et al. Standards Track [Page 67]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ information for the user to recognize the source of the conflict.
+ Ideally, the response entity would include enough information for the
+ user or user agent to fix the problem; however, that might not be
+ possible and is not required.
+
+ Conflicts are most likely to occur in response to a PUT request. For
+ example, if versioning were being used and the entity being PUT
+ included changes to a resource which conflict with those made by an
+ earlier (third-party) request, the server might use the 409 response
+ to indicate that it can't complete the request. In this case, the
+ response entity would likely contain a list of the differences
+ between the two versions in a format defined by the response
+ Content-Type.
+
+10.4.11 410 Gone
+
+ The requested resource is no longer available at the server and no
+ forwarding address is known. This condition is expected to be
+ considered permanent. Clients with link editing capabilities SHOULD
+ delete references to the Request-URI after user approval. If the
+ server does not know, or has no facility to determine, whether or not
+ the condition is permanent, the status code 404 (Not Found) SHOULD be
+ used instead. This response is cacheable unless indicated otherwise.
+
+ The 410 response is primarily intended to assist the task of web
+ maintenance by notifying the recipient that the resource is
+ intentionally unavailable and that the server owners desire that
+ remote links to that resource be removed. Such an event is common for
+ limited-time, promotional services and for resources belonging to
+ individuals no longer working at the server's site. It is not
+ necessary to mark all permanently unavailable resources as "gone" or
+ to keep the mark for any length of time -- that is left to the
+ discretion of the server owner.
+
+10.4.12 411 Length Required
+
+ The server refuses to accept the request without a defined Content-
+ Length. The client MAY repeat the request if it adds a valid
+ Content-Length header field containing the length of the message-body
+ in the request message.
+
+10.4.13 412 Precondition Failed
+
+ The precondition given in one or more of the request-header fields
+ evaluated to false when it was tested on the server. This response
+ code allows the client to place preconditions on the current resource
+ metainformation (header field data) and thus prevent the requested
+ method from being applied to a resource other than the one intended.
+
+
+
+Fielding, et al. Standards Track [Page 68]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.14 413 Request Entity Too Large
+
+ The server is refusing to process a request because the request
+ entity is larger than the server is willing or able to process. The
+ server MAY close the connection to prevent the client from continuing
+ the request.
+
+ If the condition is temporary, the server SHOULD include a Retry-
+ After header field to indicate that it is temporary and after what
+ time the client MAY try again.
+
+10.4.15 414 Request-URI Too Long
+
+ The server is refusing to service the request because the Request-URI
+ is longer than the server is willing to interpret. This rare
+ condition is only likely to occur when a client has improperly
+ converted a POST request to a GET request with long query
+ information, when the client has descended into a URI "black hole" of
+ redirection (e.g., a redirected URI prefix that points to a suffix of
+ itself), or when the server is under attack by a client attempting to
+ exploit security holes present in some servers using fixed-length
+ buffers for reading or manipulating the Request-URI.
+
+10.4.16 415 Unsupported Media Type
+
+ The server is refusing to service the request because the entity of
+ the request is in a format not supported by the requested resource
+ for the requested method.
+
+10.4.17 416 Requested Range Not Satisfiable
+
+ A server SHOULD return a response with this status code if a request
+ included a Range request-header field (section 14.35), and none of
+ the range-specifier values in this field overlap the current extent
+ of the selected resource, and the request did not include an If-Range
+ request-header field. (For byte-ranges, this means that the first-
+ byte-pos of all of the byte-range-spec values were greater than the
+ current length of the selected resource.)
+
+ When this status code is returned for a byte-range request, the
+ response SHOULD include a Content-Range entity-header field
+ specifying the current length of the selected resource (see section
+ 14.16). This response MUST NOT use the multipart/byteranges content-
+ type.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 69]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.18 417 Expectation Failed
+
+ The expectation given in an Expect request-header field (see section
+ 14.20) could not be met by this server, or, if the server is a proxy,
+ the server has unambiguous evidence that the request could not be met
+ by the next-hop server.
+
+10.5 Server Error 5xx
+
+ Response status codes beginning with the digit "5" indicate cases in
+ which the server is aware that it has erred or is incapable of
+ performing the request. Except when responding to a HEAD request, the
+ server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. User agents SHOULD display any included entity to the
+ user. These response codes are applicable to any request method.
+
+10.5.1 500 Internal Server Error
+
+ The server encountered an unexpected condition which prevented it
+ from fulfilling the request.
+
+10.5.2 501 Not Implemented
+
+ The server does not support the functionality required to fulfill the
+ request. This is the appropriate response when the server does not
+ recognize the request method and is not capable of supporting it for
+ any resource.
+
+10.5.3 502 Bad Gateway
+
+ The server, while acting as a gateway or proxy, received an invalid
+ response from the upstream server it accessed in attempting to
+ fulfill the request.
+
+10.5.4 503 Service Unavailable
+
+ The server is currently unable to handle the request due to a
+ temporary overloading or maintenance of the server. The implication
+ is that this is a temporary condition which will be alleviated after
+ some delay. If known, the length of the delay MAY be indicated in a
+ Retry-After header. If no Retry-After is given, the client SHOULD
+ handle the response as it would for a 500 response.
+
+ Note: The existence of the 503 status code does not imply that a
+ server must use it when becoming overloaded. Some servers may wish
+ to simply refuse the connection.
+
+
+
+
+Fielding, et al. Standards Track [Page 70]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.5.5 504 Gateway Timeout
+
+ The server, while acting as a gateway or proxy, did not receive a
+ timely response from the upstream server specified by the URI (e.g.
+ HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed
+ to access in attempting to complete the request.
+
+ Note: Note to implementors: some deployed proxies are known to
+ return 400 or 500 when DNS lookups time out.
+
+10.5.6 505 HTTP Version Not Supported
+
+ The server does not support, or refuses to support, the HTTP protocol
+ version that was used in the request message. The server is
+ indicating that it is unable or unwilling to complete the request
+ using the same major version as the client, as described in section
+ 3.1, other than with this error message. The response SHOULD contain
+ an entity describing why that version is not supported and what other
+ protocols are supported by that server.
+
+11 Access Authentication
+
+ HTTP provides several OPTIONAL challenge-response authentication
+ mechanisms which can be used by a server to challenge a client
+ request and by a client to provide authentication information. The
+ general framework for access authentication, and the specification of
+ "basic" and "digest" authentication, are specified in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. This
+ specification adopts the definitions of "challenge" and "credentials"
+ from that specification.
+
+12 Content Negotiation
+
+ Most HTTP responses include an entity which contains information for
+ interpretation by a human user. Naturally, it is desirable to supply
+ the user with the "best available" entity corresponding to the
+ request. Unfortunately for servers and caches, not all users have the
+ same preferences for what is "best," and not all user agents are
+ equally capable of rendering all entity types. For that reason, HTTP
+ has provisions for several mechanisms for "content negotiation" --
+ the process of selecting the best representation for a given response
+ when there are multiple representations available.
+
+ Note: This is not called "format negotiation" because the
+ alternate representations may be of the same media type, but use
+ different capabilities of that type, be in different languages,
+ etc.
+
+
+
+
+Fielding, et al. Standards Track [Page 71]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Any response containing an entity-body MAY be subject to negotiation,
+ including error responses.
+
+ There are two kinds of content negotiation which are possible in
+ HTTP: server-driven and agent-driven negotiation. These two kinds of
+ negotiation are orthogonal and thus may be used separately or in
+ combination. One method of combination, referred to as transparent
+ negotiation, occurs when a cache uses the agent-driven negotiation
+ information provided by the origin server in order to provide
+ server-driven negotiation for subsequent requests.
+
+12.1 Server-driven Negotiation
+
+ If the selection of the best representation for a response is made by
+ an algorithm located at the server, it is called server-driven
+ negotiation. Selection is based on the available representations of
+ the response (the dimensions over which it can vary; e.g. language,
+ content-coding, etc.) and the contents of particular header fields in
+ the request message or on other information pertaining to the request
+ (such as the network address of the client).
+
+ Server-driven negotiation is advantageous when the algorithm for
+ selecting from among the available representations is difficult to
+ describe to the user agent, or when the server desires to send its
+ "best guess" to the client along with the first response (hoping to
+ avoid the round-trip delay of a subsequent request if the "best
+ guess" is good enough for the user). In order to improve the server's
+ guess, the user agent MAY include request header fields (Accept,
+ Accept-Language, Accept-Encoding, etc.) which describe its
+ preferences for such a response.
+
+ Server-driven negotiation has disadvantages:
+
+ 1. It is impossible for the server to accurately determine what
+ might be "best" for any given user, since that would require
+ complete knowledge of both the capabilities of the user agent
+ and the intended use for the response (e.g., does the user want
+ to view it on screen or print it on paper?).
+
+ 2. Having the user agent describe its capabilities in every
+ request can be both very inefficient (given that only a small
+ percentage of responses have multiple representations) and a
+ potential violation of the user's privacy.
+
+ 3. It complicates the implementation of an origin server and the
+ algorithms for generating responses to a request.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 72]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 4. It may limit a public cache's ability to use the same response
+ for multiple user's requests.
+
+ HTTP/1.1 includes the following request-header fields for enabling
+ server-driven negotiation through description of user agent
+ capabilities and user preferences: Accept (section 14.1), Accept-
+ Charset (section 14.2), Accept-Encoding (section 14.3), Accept-
+ Language (section 14.4), and User-Agent (section 14.43). However, an
+ origin server is not limited to these dimensions and MAY vary the
+ response based on any aspect of the request, including information
+ outside the request-header fields or within extension header fields
+ not defined by this specification.
+
+ The Vary header field can be used to express the parameters the
+ server uses to select a representation that is subject to server-
+ driven negotiation. See section 13.6 for use of the Vary header field
+ by caches and section 14.44 for use of the Vary header field by
+ servers.
+
+12.2 Agent-driven Negotiation
+
+ With agent-driven negotiation, selection of the best representation
+ for a response is performed by the user agent after receiving an
+ initial response from the origin server. Selection is based on a list
+ of the available representations of the response included within the
+ header fields or entity-body of the initial response, with each
+ representation identified by its own URI. Selection from among the
+ representations may be performed automatically (if the user agent is
+ capable of doing so) or manually by the user selecting from a
+ generated (possibly hypertext) menu.
+
+ Agent-driven negotiation is advantageous when the response would vary
+ over commonly-used dimensions (such as type, language, or encoding),
+ when the origin server is unable to determine a user agent's
+ capabilities from examining the request, and generally when public
+ caches are used to distribute server load and reduce network usage.
+
+ Agent-driven negotiation suffers from the disadvantage of needing a
+ second request to obtain the best alternate representation. This
+ second request is only efficient when caching is used. In addition,
+ this specification does not define any mechanism for supporting
+ automatic selection, though it also does not prevent any such
+ mechanism from being developed as an extension and used within
+ HTTP/1.1.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 73]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable)
+ status codes for enabling agent-driven negotiation when the server is
+ unwilling or unable to provide a varying response using server-driven
+ negotiation.
+
+12.3 Transparent Negotiation
+
+ Transparent negotiation is a combination of both server-driven and
+ agent-driven negotiation. When a cache is supplied with a form of the
+ list of available representations of the response (as in agent-driven
+ negotiation) and the dimensions of variance are completely understood
+ by the cache, then the cache becomes capable of performing server-
+ driven negotiation on behalf of the origin server for subsequent
+ requests on that resource.
+
+ Transparent negotiation has the advantage of distributing the
+ negotiation work that would otherwise be required of the origin
+ server and also removing the second request delay of agent-driven
+ negotiation when the cache is able to correctly guess the right
+ response.
+
+ This specification does not define any mechanism for transparent
+ negotiation, though it also does not prevent any such mechanism from
+ being developed as an extension that could be used within HTTP/1.1.
+
+13 Caching in HTTP
+
+ HTTP is typically used for distributed information systems, where
+ performance can be improved by the use of response caches. The
+ HTTP/1.1 protocol includes a number of elements intended to make
+ caching work as well as possible. Because these elements are
+ inextricable from other aspects of the protocol, and because they
+ interact with each other, it is useful to describe the basic caching
+ design of HTTP separately from the detailed descriptions of methods,
+ headers, response codes, etc.
+
+ Caching would be useless if it did not significantly improve
+ performance. The goal of caching in HTTP/1.1 is to eliminate the need
+ to send requests in many cases, and to eliminate the need to send
+ full responses in many other cases. The former reduces the number of
+ network round-trips required for many operations; we use an
+ "expiration" mechanism for this purpose (see section 13.2). The
+ latter reduces network bandwidth requirements; we use a "validation"
+ mechanism for this purpose (see section 13.3).
+
+ Requirements for performance, availability, and disconnected
+ operation require us to be able to relax the goal of semantic
+ transparency. The HTTP/1.1 protocol allows origin servers, caches,
+
+
+
+Fielding, et al. Standards Track [Page 74]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ and clients to explicitly reduce transparency when necessary.
+ However, because non-transparent operation may confuse non-expert
+ users, and might be incompatible with certain server applications
+ (such as those for ordering merchandise), the protocol requires that
+ transparency be relaxed
+
+ - only by an explicit protocol-level request when relaxed by
+ client or origin server
+
+ - only with an explicit warning to the end user when relaxed by
+ cache or client
+
+ Therefore, the HTTP/1.1 protocol provides these important elements:
+
+ 1. Protocol features that provide full semantic transparency when
+ this is required by all parties.
+
+ 2. Protocol features that allow an origin server or user agent to
+ explicitly request and control non-transparent operation.
+
+ 3. Protocol features that allow a cache to attach warnings to
+ responses that do not preserve the requested approximation of
+ semantic transparency.
+
+ A basic principle is that it must be possible for the clients to
+ detect any potential relaxation of semantic transparency.
+
+ Note: The server, cache, or client implementor might be faced with
+ design decisions not explicitly discussed in this specification.
+ If a decision might affect semantic transparency, the implementor
+ ought to err on the side of maintaining transparency unless a
+ careful and complete analysis shows significant benefits in
+ breaking transparency.
+
+13.1.1 Cache Correctness
+
+ A correct cache MUST respond to a request with the most up-to-date
+ response held by the cache that is appropriate to the request (see
+ sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
+ conditions:
+
+ 1. It has been checked for equivalence with what the origin server
+ would have returned by revalidating the response with the
+ origin server (section 13.3);
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 75]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 2. It is "fresh enough" (see section 13.2). In the default case,
+ this means it meets the least restrictive freshness requirement
+ of the client, origin server, and cache (see section 14.9); if
+ the origin server so specifies, it is the freshness requirement
+ of the origin server alone.
+
+ If a stored response is not "fresh enough" by the most
+ restrictive freshness requirement of both the client and the
+ origin server, in carefully considered circumstances the cache
+ MAY still return the response with the appropriate Warning
+ header (see section 13.1.5 and 14.46), unless such a response
+ is prohibited (e.g., by a "no-store" cache-directive, or by a
+ "no-cache" cache-request-directive; see section 14.9).
+
+ 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect),
+ or error (4xx or 5xx) response message.
+
+ If the cache can not communicate with the origin server, then a
+ correct cache SHOULD respond as above if the response can be
+ correctly served from the cache; if not it MUST return an error or
+ warning indicating that there was a communication failure.
+
+ If a cache receives a response (either an entire response, or a 304
+ (Not Modified) response) that it would normally forward to the
+ requesting client, and the received response is no longer fresh, the
+ cache SHOULD forward it to the requesting client without adding a new
+ Warning (but without removing any existing Warning headers). A cache
+ SHOULD NOT attempt to revalidate a response simply because that
+ response became stale in transit; this might lead to an infinite
+ loop. A user agent that receives a stale response without a Warning
+ MAY display a warning indication to the user.
+
+13.1.2 Warnings
+
+ Whenever a cache returns a response that is neither first-hand nor
+ "fresh enough" (in the sense of condition 2 in section 13.1.1), it
+ MUST attach a warning to that effect, using a Warning general-header.
+ The Warning header and the currently defined warnings are described
+ in section 14.46. The warning allows clients to take appropriate
+ action.
+
+ Warnings MAY be used for other purposes, both cache-related and
+ otherwise. The use of a warning, rather than an error status code,
+ distinguish these responses from true failures.
+
+ Warnings are assigned three digit warn-codes. The first digit
+ indicates whether the Warning MUST or MUST NOT be deleted from a
+ stored cache entry after a successful revalidation:
+
+
+
+Fielding, et al. Standards Track [Page 76]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1xx Warnings that describe the freshness or revalidation status of
+ the response, and so MUST be deleted after a successful
+ revalidation. 1XX warn-codes MAY be generated by a cache only when
+ validating a cached entry. It MUST NOT be generated by clients.
+
+ 2xx Warnings that describe some aspect of the entity body or entity
+ headers that is not rectified by a revalidation (for example, a
+ lossy compression of the entity bodies) and which MUST NOT be
+ deleted after a successful revalidation.
+
+ See section 14.46 for the definitions of the codes themselves.
+
+ HTTP/1.0 caches will cache all Warnings in responses, without
+ deleting the ones in the first category. Warnings in responses that
+ are passed to HTTP/1.0 caches carry an extra warning-date field,
+ which prevents a future HTTP/1.1 recipient from believing an
+ erroneously cached Warning.
+
+ Warnings also carry a warning text. The text MAY be in any
+ appropriate natural language (perhaps based on the client's Accept
+ headers), and include an OPTIONAL indication of what character set is
+ used.
+
+ Multiple warnings MAY be attached to a response (either by the origin
+ server or by a cache), including multiple warnings with the same code
+ number. For example, a server might provide the same warning with
+ texts in both English and Basque.
+
+ When multiple warnings are attached to a response, it might not be
+ practical or reasonable to display all of them to the user. This
+ version of HTTP does not specify strict priority rules for deciding
+ which warnings to display and in what order, but does suggest some
+ heuristics.
+
+13.1.3 Cache-control Mechanisms
+
+ The basic cache mechanisms in HTTP/1.1 (server-specified expiration
+ times and validators) are implicit directives to caches. In some
+ cases, a server or client might need to provide explicit directives
+ to the HTTP caches. We use the Cache-Control header for this purpose.
+
+ The Cache-Control header allows a client or server to transmit a
+ variety of directives in either requests or responses. These
+ directives typically override the default caching algorithms. As a
+ general rule, if there is any apparent conflict between header
+ values, the most restrictive interpretation is applied (that is, the
+ one that is most likely to preserve semantic transparency). However,
+
+
+
+
+Fielding, et al. Standards Track [Page 77]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ in some cases, cache-control directives are explicitly specified as
+ weakening the approximation of semantic transparency (for example,
+ "max-stale" or "public").
+
+ The cache-control directives are described in detail in section 14.9.
+
+13.1.4 Explicit User Agent Warnings
+
+ Many user agents make it possible for users to override the basic
+ caching mechanisms. For example, the user agent might allow the user
+ to specify that cached entities (even explicitly stale ones) are
+ never validated. Or the user agent might habitually add "Cache-
+ Control: max-stale=3600" to every request. The user agent SHOULD NOT
+ default to either non-transparent behavior, or behavior that results
+ in abnormally ineffective caching, but MAY be explicitly configured
+ to do so by an explicit action of the user.
+
+ If the user has overridden the basic caching mechanisms, the user
+ agent SHOULD explicitly indicate to the user whenever this results in
+ the display of information that might not meet the server's
+ transparency requirements (in particular, if the displayed entity is
+ known to be stale). Since the protocol normally allows the user agent
+ to determine if responses are stale or not, this indication need only
+ be displayed when this actually happens. The indication need not be a
+ dialog box; it could be an icon (for example, a picture of a rotting
+ fish) or some other indicator.
+
+ If the user has overridden the caching mechanisms in a way that would
+ abnormally reduce the effectiveness of caches, the user agent SHOULD
+ continually indicate this state to the user (for example, by a
+ display of a picture of currency in flames) so that the user does not
+ inadvertently consume excess resources or suffer from excessive
+ latency.
+
+13.1.5 Exceptions to the Rules and Warnings
+
+ In some cases, the operator of a cache MAY choose to configure it to
+ return stale responses even when not requested by clients. This
+ decision ought not be made lightly, but may be necessary for reasons
+ of availability or performance, especially when the cache is poorly
+ connected to the origin server. Whenever a cache returns a stale
+ response, it MUST mark it as such (using a Warning header) enabling
+ the client software to alert the user that there might be a potential
+ problem.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 78]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ It also allows the user agent to take steps to obtain a first-hand or
+ fresh response. For this reason, a cache SHOULD NOT return a stale
+ response if the client explicitly requests a first-hand or fresh one,
+ unless it is impossible to comply for technical or policy reasons.
+
+13.1.6 Client-controlled Behavior
+
+ While the origin server (and to a lesser extent, intermediate caches,
+ by their contribution to the age of a response) are the primary
+ source of expiration information, in some cases the client might need
+ to control a cache's decision about whether to return a cached
+ response without validating it. Clients do this using several
+ directives of the Cache-Control header.
+
+ A client's request MAY specify the maximum age it is willing to
+ accept of an unvalidated response; specifying a value of zero forces
+ the cache(s) to revalidate all responses. A client MAY also specify
+ the minimum time remaining before a response expires. Both of these
+ options increase constraints on the behavior of caches, and so cannot
+ further relax the cache's approximation of semantic transparency.
+
+ A client MAY also specify that it will accept stale responses, up to
+ some maximum amount of staleness. This loosens the constraints on the
+ caches, and so might violate the origin server's specified
+ constraints on semantic transparency, but might be necessary to
+ support disconnected operation, or high availability in the face of
+ poor connectivity.
+
+13.2 Expiration Model
+
+13.2.1 Server-Specified Expiration
+
+ HTTP caching works best when caches can entirely avoid making
+ requests to the origin server. The primary mechanism for avoiding
+ requests is for an origin server to provide an explicit expiration
+ time in the future, indicating that a response MAY be used to satisfy
+ subsequent requests. In other words, a cache can return a fresh
+ response without first contacting the server.
+
+ Our expectation is that servers will assign future explicit
+ expiration times to responses in the belief that the entity is not
+ likely to change, in a semantically significant way, before the
+ expiration time is reached. This normally preserves semantic
+ transparency, as long as the server's expiration times are carefully
+ chosen.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 79]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The expiration mechanism applies only to responses taken from a cache
+ and not to first-hand responses forwarded immediately to the
+ requesting client.
+
+ If an origin server wishes to force a semantically transparent cache
+ to validate every request, it MAY assign an explicit expiration time
+ in the past. This means that the response is always stale, and so the
+ cache SHOULD validate it before using it for subsequent requests. See
+ section 14.9.4 for a more restrictive way to force revalidation.
+
+ If an origin server wishes to force any HTTP/1.1 cache, no matter how
+ it is configured, to validate every request, it SHOULD use the "must-
+ revalidate" cache-control directive (see section 14.9).
+
+ Servers specify explicit expiration times using either the Expires
+ header, or the max-age directive of the Cache-Control header.
+
+ An expiration time cannot be used to force a user agent to refresh
+ its display or reload a resource; its semantics apply only to caching
+ mechanisms, and such mechanisms need only check a resource's
+ expiration status when a new request for that resource is initiated.
+ See section 13.13 for an explanation of the difference between caches
+ and history mechanisms.
+
+13.2.2 Heuristic Expiration
+
+ Since origin servers do not always provide explicit expiration times,
+ HTTP caches typically assign heuristic expiration times, employing
+ algorithms that use other header values (such as the Last-Modified
+ time) to estimate a plausible expiration time. The HTTP/1.1
+ specification does not provide specific algorithms, but does impose
+ worst-case constraints on their results. Since heuristic expiration
+ times might compromise semantic transparency, they ought to used
+ cautiously, and we encourage origin servers to provide explicit
+ expiration times as much as possible.
+
+13.2.3 Age Calculations
+
+ In order to know if a cached entry is fresh, a cache needs to know if
+ its age exceeds its freshness lifetime. We discuss how to calculate
+ the latter in section 13.2.4; this section describes how to calculate
+ the age of a response or cache entry.
+
+ In this discussion, we use the term "now" to mean "the current value
+ of the clock at the host performing the calculation." Hosts that use
+ HTTP, but especially hosts running origin servers and caches, SHOULD
+ use NTP [28] or some similar protocol to synchronize their clocks to
+ a globally accurate time standard.
+
+
+
+Fielding, et al. Standards Track [Page 80]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 requires origin servers to send a Date header, if possible,
+ with every response, giving the time at which the response was
+ generated (see section 14.18). We use the term "date_value" to denote
+ the value of the Date header, in a form appropriate for arithmetic
+ operations.
+
+ HTTP/1.1 uses the Age response-header to convey the estimated age of
+ the response message when obtained from a cache. The Age field value
+ is the cache's estimate of the amount of time since the response was
+ generated or revalidated by the origin server.
+
+ In essence, the Age value is the sum of the time that the response
+ has been resident in each of the caches along the path from the
+ origin server, plus the amount of time it has been in transit along
+ network paths.
+
+ We use the term "age_value" to denote the value of the Age header, in
+ a form appropriate for arithmetic operations.
+
+ A response's age can be calculated in two entirely independent ways:
+
+ 1. now minus date_value, if the local clock is reasonably well
+ synchronized to the origin server's clock. If the result is
+ negative, the result is replaced by zero.
+
+ 2. age_value, if all of the caches along the response path
+ implement HTTP/1.1.
+
+ Given that we have two independent ways to compute the age of a
+ response when it is received, we can combine these as
+
+ corrected_received_age = max(now - date_value, age_value)
+
+ and as long as we have either nearly synchronized clocks or all-
+ HTTP/1.1 paths, one gets a reliable (conservative) result.
+
+ Because of network-imposed delays, some significant interval might
+ pass between the time that a server generates a response and the time
+ it is received at the next outbound cache or client. If uncorrected,
+ this delay could result in improperly low ages.
+
+ Because the request that resulted in the returned Age value must have
+ been initiated prior to that Age value's generation, we can correct
+ for delays imposed by the network by recording the time at which the
+ request was initiated. Then, when an Age value is received, it MUST
+ be interpreted relative to the time the request was initiated, not
+
+
+
+
+
+Fielding, et al. Standards Track [Page 81]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the time that the response was received. This algorithm results in
+ conservative behavior no matter how much delay is experienced. So, we
+ compute:
+
+ corrected_initial_age = corrected_received_age
+ + (now - request_time)
+
+ where "request_time" is the time (according to the local clock) when
+ the request that elicited this response was sent.
+
+ Summary of age calculation algorithm, when a cache receives a
+ response:
+
+ /*
+ * age_value
+ * is the value of Age: header received by the cache with
+ * this response.
+ * date_value
+ * is the value of the origin server's Date: header
+ * request_time
+ * is the (local) time when the cache made the request
+ * that resulted in this cached response
+ * response_time
+ * is the (local) time when the cache received the
+ * response
+ * now
+ * is the current (local) time
+ */
+
+ apparent_age = max(0, response_time - date_value);
+ corrected_received_age = max(apparent_age, age_value);
+ response_delay = response_time - request_time;
+ corrected_initial_age = corrected_received_age + response_delay;
+ resident_time = now - response_time;
+ current_age = corrected_initial_age + resident_time;
+
+ The current_age of a cache entry is calculated by adding the amount
+ of time (in seconds) since the cache entry was last validated by the
+ origin server to the corrected_initial_age. When a response is
+ generated from a cache entry, the cache MUST include a single Age
+ header field in the response with a value equal to the cache entry's
+ current_age.
+
+ The presence of an Age header field in a response implies that a
+ response is not first-hand. However, the converse is not true, since
+ the lack of an Age header field in a response does not imply that the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 82]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ response is first-hand unless all caches along the request path are
+ compliant with HTTP/1.1 (i.e., older HTTP caches did not implement
+ the Age header field).
+
+13.2.4 Expiration Calculations
+
+ In order to decide whether a response is fresh or stale, we need to
+ compare its freshness lifetime to its age. The age is calculated as
+ described in section 13.2.3; this section describes how to calculate
+ the freshness lifetime, and to determine if a response has expired.
+ In the discussion below, the values can be represented in any form
+ appropriate for arithmetic operations.
+
+ We use the term "expires_value" to denote the value of the Expires
+ header. We use the term "max_age_value" to denote an appropriate
+ value of the number of seconds carried by the "max-age" directive of
+ the Cache-Control header in a response (see section 14.9.3).
+
+ The max-age directive takes priority over Expires, so if max-age is
+ present in a response, the calculation is simply:
+
+ freshness_lifetime = max_age_value
+
+ Otherwise, if Expires is present in the response, the calculation is:
+
+ freshness_lifetime = expires_value - date_value
+
+ Note that neither of these calculations is vulnerable to clock skew,
+ since all of the information comes from the origin server.
+
+ If none of Expires, Cache-Control: max-age, or Cache-Control: s-
+ maxage (see section 14.9.3) appears in the response, and the response
+ does not include other restrictions on caching, the cache MAY compute
+ a freshness lifetime using a heuristic. The cache MUST attach Warning
+ 113 to any response whose age is more than 24 hours if such warning
+ has not already been added.
+
+ Also, if the response does have a Last-Modified time, the heuristic
+ expiration value SHOULD be no more than some fraction of the interval
+ since that time. A typical setting of this fraction might be 10%.
+
+ The calculation to determine if a response has expired is quite
+ simple:
+
+ response_is_fresh = (freshness_lifetime > current_age)
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 83]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.2.5 Disambiguating Expiration Values
+
+ Because expiration values are assigned optimistically, it is possible
+ for two caches to contain fresh values for the same resource that are
+ different.
+
+ If a client performing a retrieval receives a non-first-hand response
+ for a request that was already fresh in its own cache, and the Date
+ header in its existing cache entry is newer than the Date on the new
+ response, then the client MAY ignore the response. If so, it MAY
+ retry the request with a "Cache-Control: max-age=0" directive (see
+ section 14.9), to force a check with the origin server.
+
+ If a cache has two fresh responses for the same representation with
+ different validators, it MUST use the one with the more recent Date
+ header. This situation might arise because the cache is pooling
+ responses from other caches, or because a client has asked for a
+ reload or a revalidation of an apparently fresh cache entry.
+
+13.2.6 Disambiguating Multiple Responses
+
+ Because a client might be receiving responses via multiple paths, so
+ that some responses flow through one set of caches and other
+ responses flow through a different set of caches, a client might
+ receive responses in an order different from that in which the origin
+ server sent them. We would like the client to use the most recently
+ generated response, even if older responses are still apparently
+ fresh.
+
+ Neither the entity tag nor the expiration value can impose an
+ ordering on responses, since it is possible that a later response
+ intentionally carries an earlier expiration time. The Date values are
+ ordered to a granularity of one second.
+
+ When a client tries to revalidate a cache entry, and the response it
+ receives contains a Date header that appears to be older than the one
+ for the existing entry, then the client SHOULD repeat the request
+ unconditionally, and include
+
+ Cache-Control: max-age=0
+
+ to force any intermediate caches to validate their copies directly
+ with the origin server, or
+
+ Cache-Control: no-cache
+
+ to force any intermediate caches to obtain a new copy from the origin
+ server.
+
+
+
+Fielding, et al. Standards Track [Page 84]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the Date values are equal, then the client MAY use either response
+ (or MAY, if it is being extremely prudent, request a new response).
+ Servers MUST NOT depend on clients being able to choose
+ deterministically between responses generated during the same second,
+ if their expiration times overlap.
+
+13.3 Validation Model
+
+ When a cache has a stale entry that it would like to use as a
+ response to a client's request, it first has to check with the origin
+ server (or possibly an intermediate cache with a fresh response) to
+ see if its cached entry is still usable. We call this "validating"
+ the cache entry. Since we do not want to have to pay the overhead of
+ retransmitting the full response if the cached entry is good, and we
+ do not want to pay the overhead of an extra round trip if the cached
+ entry is invalid, the HTTP/1.1 protocol supports the use of
+ conditional methods.
+
+ The key protocol features for supporting conditional methods are
+ those concerned with "cache validators." When an origin server
+ generates a full response, it attaches some sort of validator to it,
+ which is kept with the cache entry. When a client (user agent or
+ proxy cache) makes a conditional request for a resource for which it
+ has a cache entry, it includes the associated validator in the
+ request.
+
+ The server then checks that validator against the current validator
+ for the entity, and, if they match (see section 13.3.3), it responds
+ with a special status code (usually, 304 (Not Modified)) and no
+ entity-body. Otherwise, it returns a full response (including
+ entity-body). Thus, we avoid transmitting the full response if the
+ validator matches, and we avoid an extra round trip if it does not
+ match.
+
+ In HTTP/1.1, a conditional request looks exactly the same as a normal
+ request for the same resource, except that it carries a special
+ header (which includes the validator) that implicitly turns the
+ method (usually, GET) into a conditional.
+
+ The protocol includes both positive and negative senses of cache-
+ validating conditions. That is, it is possible to request either that
+ a method be performed if and only if a validator matches or if and
+ only if no validators match.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 85]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note: a response that lacks a validator may still be cached, and
+ served from cache until it expires, unless this is explicitly
+ prohibited by a cache-control directive. However, a cache cannot
+ do a conditional retrieval if it does not have a validator for the
+ entity, which means it will not be refreshable after it expires.
+
+13.3.1 Last-Modified Dates
+
+ The Last-Modified entity-header field value is often used as a cache
+ validator. In simple terms, a cache entry is considered to be valid
+ if the entity has not been modified since the Last-Modified value.
+
+13.3.2 Entity Tag Cache Validators
+
+ The ETag response-header field value, an entity tag, provides for an
+ "opaque" cache validator. This might allow more reliable validation
+ in situations where it is inconvenient to store modification dates,
+ where the one-second resolution of HTTP date values is not
+ sufficient, or where the origin server wishes to avoid certain
+ paradoxes that might arise from the use of modification dates.
+
+ Entity Tags are described in section 3.11. The headers used with
+ entity tags are described in sections 14.19, 14.24, 14.26 and 14.44.
+
+13.3.3 Weak and Strong Validators
+
+ Since both origin servers and caches will compare two validators to
+ decide if they represent the same or different entities, one normally
+ would expect that if the entity (the entity-body or any entity-
+ headers) changes in any way, then the associated validator would
+ change as well. If this is true, then we call this validator a
+ "strong validator."
+
+ However, there might be cases when a server prefers to change the
+ validator only on semantically significant changes, and not when
+ insignificant aspects of the entity change. A validator that does not
+ always change when the resource changes is a "weak validator."
+
+ Entity tags are normally "strong validators," but the protocol
+ provides a mechanism to tag an entity tag as "weak." One can think of
+ a strong validator as one that changes whenever the bits of an entity
+ changes, while a weak value changes whenever the meaning of an entity
+ changes. Alternatively, one can think of a strong validator as part
+ of an identifier for a specific entity, while a weak validator is
+ part of an identifier for a set of semantically equivalent entities.
+
+ Note: One example of a strong validator is an integer that is
+ incremented in stable storage every time an entity is changed.
+
+
+
+Fielding, et al. Standards Track [Page 86]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An entity's modification time, if represented with one-second
+ resolution, could be a weak validator, since it is possible that
+ the resource might be modified twice during a single second.
+
+ Support for weak validators is optional. However, weak validators
+ allow for more efficient caching of equivalent objects; for
+ example, a hit counter on a site is probably good enough if it is
+ updated every few days or weeks, and any value during that period
+ is likely "good enough" to be equivalent.
+
+ A "use" of a validator is either when a client generates a request
+ and includes the validator in a validating header field, or when a
+ server compares two validators.
+
+ Strong validators are usable in any context. Weak validators are only
+ usable in contexts that do not depend on exact equality of an entity.
+ For example, either kind is usable for a conditional GET of a full
+ entity. However, only a strong validator is usable for a sub-range
+ retrieval, since otherwise the client might end up with an internally
+ inconsistent entity.
+
+ Clients MAY issue simple (non-subrange) GET requests with either weak
+ validators or strong validators. Clients MUST NOT use weak validators
+ in other forms of request.
+
+ The only function that the HTTP/1.1 protocol defines on validators is
+ comparison. There are two validator comparison functions, depending
+ on whether the comparison context allows the use of weak validators
+ or not:
+
+ - The strong comparison function: in order to be considered equal,
+ both validators MUST be identical in every way, and both MUST
+ NOT be weak.
+
+ - The weak comparison function: in order to be considered equal,
+ both validators MUST be identical in every way, but either or
+ both of them MAY be tagged as "weak" without affecting the
+ result.
+
+ An entity tag is strong unless it is explicitly tagged as weak.
+ Section 3.11 gives the syntax for entity tags.
+
+ A Last-Modified time, when used as a validator in a request, is
+ implicitly weak unless it is possible to deduce that it is strong,
+ using the following rules:
+
+ - The validator is being compared by an origin server to the
+ actual current validator for the entity and,
+
+
+
+Fielding, et al. Standards Track [Page 87]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - That origin server reliably knows that the associated entity did
+ not change twice during the second covered by the presented
+ validator.
+
+ or
+
+ - The validator is about to be used by a client in an If-
+ Modified-Since or If-Unmodified-Since header, because the client
+ has a cache entry for the associated entity, and
+
+ - That cache entry includes a Date value, which gives the time
+ when the origin server sent the original response, and
+
+ - The presented Last-Modified time is at least 60 seconds before
+ the Date value.
+
+ or
+
+ - The validator is being compared by an intermediate cache to the
+ validator stored in its cache entry for the entity, and
+
+ - That cache entry includes a Date value, which gives the time
+ when the origin server sent the original response, and
+
+ - The presented Last-Modified time is at least 60 seconds before
+ the Date value.
+
+ This method relies on the fact that if two different responses were
+ sent by the origin server during the same second, but both had the
+ same Last-Modified time, then at least one of those responses would
+ have a Date value equal to its Last-Modified time. The arbitrary 60-
+ second limit guards against the possibility that the Date and Last-
+ Modified values are generated from different clocks, or at somewhat
+ different times during the preparation of the response. An
+ implementation MAY use a value larger than 60 seconds, if it is
+ believed that 60 seconds is too short.
+
+ If a client wishes to perform a sub-range retrieval on a value for
+ which it has only a Last-Modified time and no opaque validator, it
+ MAY do this only if the Last-Modified time is strong in the sense
+ described here.
+
+ A cache or origin server receiving a conditional request, other than
+ a full-body GET request, MUST use the strong comparison function to
+ evaluate the condition.
+
+ These rules allow HTTP/1.1 caches and clients to safely perform sub-
+ range retrievals on values that have been obtained from HTTP/1.0
+
+
+
+Fielding, et al. Standards Track [Page 88]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ servers.
+
+13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates
+
+ We adopt a set of rules and recommendations for origin servers,
+ clients, and caches regarding when various validator types ought to
+ be used, and for what purposes.
+
+ HTTP/1.1 origin servers:
+
+ - SHOULD send an entity tag validator unless it is not feasible to
+ generate one.
+
+ - MAY send a weak entity tag instead of a strong entity tag, if
+ performance considerations support the use of weak entity tags,
+ or if it is unfeasible to send a strong entity tag.
+
+ - SHOULD send a Last-Modified value if it is feasible to send one,
+ unless the risk of a breakdown in semantic transparency that
+ could result from using this date in an If-Modified-Since header
+ would lead to serious problems.
+
+ In other words, the preferred behavior for an HTTP/1.1 origin server
+ is to send both a strong entity tag and a Last-Modified value.
+
+ In order to be legal, a strong entity tag MUST change whenever the
+ associated entity value changes in any way. A weak entity tag SHOULD
+ change whenever the associated entity changes in a semantically
+ significant way.
+
+ Note: in order to provide semantically transparent caching, an
+ origin server must avoid reusing a specific strong entity tag
+ value for two different entities, or reusing a specific weak
+ entity tag value for two semantically different entities. Cache
+ entries might persist for arbitrarily long periods, regardless of
+ expiration times, so it might be inappropriate to expect that a
+ cache will never again attempt to validate an entry using a
+ validator that it obtained at some point in the past.
+
+ HTTP/1.1 clients:
+
+ - If an entity tag has been provided by the origin server, MUST
+ use that entity tag in any cache-conditional request (using If-
+ Match or If-None-Match).
+
+ - If only a Last-Modified value has been provided by the origin
+ server, SHOULD use that value in non-subrange cache-conditional
+ requests (using If-Modified-Since).
+
+
+
+Fielding, et al. Standards Track [Page 89]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If only a Last-Modified value has been provided by an HTTP/1.0
+ origin server, MAY use that value in subrange cache-conditional
+ requests (using If-Unmodified-Since:). The user agent SHOULD
+ provide a way to disable this, in case of difficulty.
+
+ - If both an entity tag and a Last-Modified value have been
+ provided by the origin server, SHOULD use both validators in
+ cache-conditional requests. This allows both HTTP/1.0 and
+ HTTP/1.1 caches to respond appropriately.
+
+ An HTTP/1.1 origin server, upon receiving a conditional request that
+ includes both a Last-Modified date (e.g., in an If-Modified-Since or
+ If-Unmodified-Since header field) and one or more entity tags (e.g.,
+ in an If-Match, If-None-Match, or If-Range header field) as cache
+ validators, MUST NOT return a response status of 304 (Not Modified)
+ unless doing so is consistent with all of the conditional header
+ fields in the request.
+
+ An HTTP/1.1 caching proxy, upon receiving a conditional request that
+ includes both a Last-Modified date and one or more entity tags as
+ cache validators, MUST NOT return a locally cached response to the
+ client unless that cached response is consistent with all of the
+ conditional header fields in the request.
+
+ Note: The general principle behind these rules is that HTTP/1.1
+ servers and clients should transmit as much non-redundant
+ information as is available in their responses and requests.
+ HTTP/1.1 systems receiving this information will make the most
+ conservative assumptions about the validators they receive.
+
+ HTTP/1.0 clients and caches will ignore entity tags. Generally,
+ last-modified values received or used by these systems will
+ support transparent and efficient caching, and so HTTP/1.1 origin
+ servers should provide Last-Modified values. In those rare cases
+ where the use of a Last-Modified value as a validator by an
+ HTTP/1.0 system could result in a serious problem, then HTTP/1.1
+ origin servers should not provide one.
+
+13.3.5 Non-validating Conditionals
+
+ The principle behind entity tags is that only the service author
+ knows the semantics of a resource well enough to select an
+ appropriate cache validation mechanism, and the specification of any
+ validator comparison function more complex than byte-equality would
+ open up a can of worms. Thus, comparisons of any other headers
+ (except Last-Modified, for compatibility with HTTP/1.0) are never
+ used for purposes of validating a cache entry.
+
+
+
+
+Fielding, et al. Standards Track [Page 90]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.4 Response Cacheability
+
+ Unless specifically constrained by a cache-control (section 14.9)
+ directive, a caching system MAY always store a successful response
+ (see section 13.8) as a cache entry, MAY return it without validation
+ if it is fresh, and MAY return it after successful validation. If
+ there is neither a cache validator nor an explicit expiration time
+ associated with a response, we do not expect it to be cached, but
+ certain caches MAY violate this expectation (for example, when little
+ or no network connectivity is available). A client can usually detect
+ that such a response was taken from a cache by comparing the Date
+ header to the current time.
+
+ Note: some HTTP/1.0 caches are known to violate this expectation
+ without providing any Warning.
+
+ However, in some cases it might be inappropriate for a cache to
+ retain an entity, or to return it in response to a subsequent
+ request. This might be because absolute semantic transparency is
+ deemed necessary by the service author, or because of security or
+ privacy considerations. Certain cache-control directives are
+ therefore provided so that the server can indicate that certain
+ resource entities, or portions thereof, are not to be cached
+ regardless of other considerations.
+
+ Note that section 14.8 normally prevents a shared cache from saving
+ and returning a response to a previous request if that request
+ included an Authorization header.
+
+ A response received with a status code of 200, 203, 206, 300, 301 or
+ 410 MAY be stored by a cache and used in reply to a subsequent
+ request, subject to the expiration mechanism, unless a cache-control
+ directive prohibits caching. However, a cache that does not support
+ the Range and Content-Range headers MUST NOT cache 206 (Partial
+ Content) responses.
+
+ A response received with any other status code (e.g. status codes 302
+ and 307) MUST NOT be returned in a reply to a subsequent request
+ unless there are cache-control directives or another header(s) that
+ explicitly allow it. For example, these include the following: an
+ Expires header (section 14.21); a "max-age", "s-maxage", "must-
+ revalidate", "proxy-revalidate", "public" or "private" cache-control
+ directive (section 14.9).
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 91]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5 Constructing Responses From Caches
+
+ The purpose of an HTTP cache is to store information received in
+ response to requests for use in responding to future requests. In
+ many cases, a cache simply returns the appropriate parts of a
+ response to the requester. However, if the cache holds a cache entry
+ based on a previous response, it might have to combine parts of a new
+ response with what is held in the cache entry.
+
+13.5.1 End-to-end and Hop-by-hop Headers
+
+ For the purpose of defining the behavior of caches and non-caching
+ proxies, we divide HTTP headers into two categories:
+
+ - End-to-end headers, which are transmitted to the ultimate
+ recipient of a request or response. End-to-end headers in
+ responses MUST be stored as part of a cache entry and MUST be
+ transmitted in any response formed from a cache entry.
+
+ - Hop-by-hop headers, which are meaningful only for a single
+ transport-level connection, and are not stored by caches or
+ forwarded by proxies.
+
+ The following HTTP/1.1 headers are hop-by-hop headers:
+
+ - Connection
+ - Keep-Alive
+ - Proxy-Authenticate
+ - Proxy-Authorization
+ - TE
+ - Trailers
+ - Transfer-Encoding
+ - Upgrade
+
+ All other headers defined by HTTP/1.1 are end-to-end headers.
+
+ Other hop-by-hop headers MUST be listed in a Connection header,
+ (section 14.10) to be introduced into HTTP/1.1 (or later).
+
+13.5.2 Non-modifiable Headers
+
+ Some features of the HTTP/1.1 protocol, such as Digest
+ Authentication, depend on the value of certain end-to-end headers. A
+ transparent proxy SHOULD NOT modify an end-to-end header unless the
+ definition of that header requires or specifically allows that.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 92]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A transparent proxy MUST NOT modify any of the following fields in a
+ request or response, and it MUST NOT add any of these fields if not
+ already present:
+
+ - Content-Location
+
+ - Content-MD5
+
+ - ETag
+
+ - Last-Modified
+
+ A transparent proxy MUST NOT modify any of the following fields in a
+ response:
+
+ - Expires
+
+ but it MAY add any of these fields if not already present. If an
+ Expires header is added, it MUST be given a field-value identical to
+ that of the Date header in that response.
+
+ A proxy MUST NOT modify or add any of the following fields in a
+ message that contains the no-transform cache-control directive, or in
+ any request:
+
+ - Content-Encoding
+
+ - Content-Range
+
+ - Content-Type
+
+ A non-transparent proxy MAY modify or add these fields to a message
+ that does not include no-transform, but if it does so, it MUST add a
+ Warning 214 (Transformation applied) if one does not already appear
+ in the message (see section 14.46).
+
+ Warning: unnecessary modification of end-to-end headers might
+ cause authentication failures if stronger authentication
+ mechanisms are introduced in later versions of HTTP. Such
+ authentication mechanisms MAY rely on the values of header fields
+ not listed here.
+
+ The Content-Length field of a request or response is added or deleted
+ according to the rules in section 4.4. A transparent proxy MUST
+ preserve the entity-length (section 7.2.2) of the entity-body,
+ although it MAY change the transfer-length (section 4.4).
+
+
+
+
+
+Fielding, et al. Standards Track [Page 93]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5.3 Combining Headers
+
+ When a cache makes a validating request to a server, and the server
+ provides a 304 (Not Modified) response or a 206 (Partial Content)
+ response, the cache then constructs a response to send to the
+ requesting client.
+
+ If the status code is 304 (Not Modified), the cache uses the entity-
+ body stored in the cache entry as the entity-body of this outgoing
+ response. If the status code is 206 (Partial Content) and the ETag or
+ Last-Modified headers match exactly, the cache MAY combine the
+ contents stored in the cache entry with the new contents received in
+ the response and use the result as the entity-body of this outgoing
+ response, (see 13.5.4).
+
+ The end-to-end headers stored in the cache entry are used for the
+ constructed response, except that
+
+ - any stored Warning headers with warn-code 1xx (see section
+ 14.46) MUST be deleted from the cache entry and the forwarded
+ response.
+
+ - any stored Warning headers with warn-code 2xx MUST be retained
+ in the cache entry and the forwarded response.
+
+ - any end-to-end headers provided in the 304 or 206 response MUST
+ replace the corresponding headers from the cache entry.
+
+ Unless the cache decides to remove the cache entry, it MUST also
+ replace the end-to-end headers stored with the cache entry with
+ corresponding headers received in the incoming response, except for
+ Warning headers as described immediately above. If a header field-
+ name in the incoming response matches more than one header in the
+ cache entry, all such old headers MUST be replaced.
+
+ In other words, the set of end-to-end headers received in the
+ incoming response overrides all corresponding end-to-end headers
+ stored with the cache entry (except for stored Warning headers with
+ warn-code 1xx, which are deleted even if not overridden).
+
+ Note: this rule allows an origin server to use a 304 (Not
+ Modified) or a 206 (Partial Content) response to update any header
+ associated with a previous response for the same entity or sub-
+ ranges thereof, although it might not always be meaningful or
+ correct to do so. This rule does not allow an origin server to use
+ a 304 (Not Modified) or a 206 (Partial Content) response to
+ entirely delete a header that it had provided with a previous
+ response.
+
+
+
+Fielding, et al. Standards Track [Page 94]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5.4 Combining Byte Ranges
+
+ A response might transfer only a subrange of the bytes of an entity-
+ body, either because the request included one or more Range
+ specifications, or because a connection was broken prematurely. After
+ several such transfers, a cache might have received several ranges of
+ the same entity-body.
+
+ If a cache has a stored non-empty set of subranges for an entity, and
+ an incoming response transfers another subrange, the cache MAY
+ combine the new subrange with the existing set if both the following
+ conditions are met:
+
+ - Both the incoming response and the cache entry have a cache
+ validator.
+
+ - The two cache validators match using the strong comparison
+ function (see section 13.3.3).
+
+ If either requirement is not met, the cache MUST use only the most
+ recent partial response (based on the Date values transmitted with
+ every response, and using the incoming response if these values are
+ equal or missing), and MUST discard the other partial information.
+
+13.6 Caching Negotiated Responses
+
+ Use of server-driven content negotiation (section 12.1), as indicated
+ by the presence of a Vary header field in a response, alters the
+ conditions and procedure by which a cache can use the response for
+ subsequent requests. See section 14.44 for use of the Vary header
+ field by servers.
+
+ A server SHOULD use the Vary header field to inform a cache of what
+ request-header fields were used to select among multiple
+ representations of a cacheable response subject to server-driven
+ negotiation. The set of header fields named by the Vary field value
+ is known as the "selecting" request-headers.
+
+ When the cache receives a subsequent request whose Request-URI
+ specifies one or more cache entries including a Vary header field,
+ the cache MUST NOT use such a cache entry to construct a response to
+ the new request unless all of the selecting request-headers present
+ in the new request match the corresponding stored request-headers in
+ the original request.
+
+ The selecting request-headers from two requests are defined to match
+ if and only if the selecting request-headers in the first request can
+ be transformed to the selecting request-headers in the second request
+
+
+
+Fielding, et al. Standards Track [Page 95]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ by adding or removing linear white space (LWS) at places where this
+ is allowed by the corresponding BNF, and/or combining multiple
+ message-header fields with the same field name following the rules
+ about message headers in section 4.2.
+
+ A Vary header field-value of "*" always fails to match and subsequent
+ requests on that resource can only be properly interpreted by the
+ origin server.
+
+ If the selecting request header fields for the cached entry do not
+ match the selecting request header fields of the new request, then
+ the cache MUST NOT use a cached entry to satisfy the request unless
+ it first relays the new request to the origin server in a conditional
+ request and the server responds with 304 (Not Modified), including an
+ entity tag or Content-Location that indicates the entity to be used.
+
+ If an entity tag was assigned to a cached representation, the
+ forwarded request SHOULD be conditional and include the entity tags
+ in an If-None-Match header field from all its cache entries for the
+ resource. This conveys to the server the set of entities currently
+ held by the cache, so that if any one of these entities matches the
+ requested entity, the server can use the ETag header field in its 304
+ (Not Modified) response to tell the cache which entry is appropriate.
+ If the entity-tag of the new response matches that of an existing
+ entry, the new response SHOULD be used to update the header fields of
+ the existing entry, and the result MUST be returned to the client.
+
+ If any of the existing cache entries contains only partial content
+ for the associated entity, its entity-tag SHOULD NOT be included in
+ the If-None-Match header field unless the request is for a range that
+ would be fully satisfied by that entry.
+
+ If a cache receives a successful response whose Content-Location
+ field matches that of an existing cache entry for the same Request-
+ ]URI, whose entity-tag differs from that of the existing entry, and
+ whose Date is more recent than that of the existing entry, the
+ existing entry SHOULD NOT be returned in response to future requests
+ and SHOULD be deleted from the cache.
+
+13.7 Shared and Non-Shared Caches
+
+ For reasons of security and privacy, it is necessary to make a
+ distinction between "shared" and "non-shared" caches. A non-shared
+ cache is one that is accessible only to a single user. Accessibility
+ in this case SHOULD be enforced by appropriate security mechanisms.
+ All other caches are considered to be "shared." Other sections of
+
+
+
+
+
+Fielding, et al. Standards Track [Page 96]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ this specification place certain constraints on the operation of
+ shared caches in order to prevent loss of privacy or failure of
+ access controls.
+
+13.8 Errors or Incomplete Response Cache Behavior
+
+ A cache that receives an incomplete response (for example, with fewer
+ bytes of data than specified in a Content-Length header) MAY store
+ the response. However, the cache MUST treat this as a partial
+ response. Partial responses MAY be combined as described in section
+ 13.5.4; the result might be a full response or might still be
+ partial. A cache MUST NOT return a partial response to a client
+ without explicitly marking it as such, using the 206 (Partial
+ Content) status code. A cache MUST NOT return a partial response
+ using a status code of 200 (OK).
+
+ If a cache receives a 5xx response while attempting to revalidate an
+ entry, it MAY either forward this response to the requesting client,
+ or act as if the server failed to respond. In the latter case, it MAY
+ return a previously received response unless the cached entry
+ includes the "must-revalidate" cache-control directive (see section
+ 14.9).
+
+13.9 Side Effects of GET and HEAD
+
+ Unless the origin server explicitly prohibits the caching of their
+ responses, the application of GET and HEAD methods to any resources
+ SHOULD NOT have side effects that would lead to erroneous behavior if
+ these responses are taken from a cache. They MAY still have side
+ effects, but a cache is not required to consider such side effects in
+ its caching decisions. Caches are always expected to observe an
+ origin server's explicit restrictions on caching.
+
+ We note one exception to this rule: since some applications have
+ traditionally used GETs and HEADs with query URLs (those containing a
+ "?" in the rel_path part) to perform operations with significant side
+ effects, caches MUST NOT treat responses to such URIs as fresh unless
+ the server provides an explicit expiration time. This specifically
+ means that responses from HTTP/1.0 servers for such URIs SHOULD NOT
+ be taken from a cache. See section 9.1.1 for related information.
+
+13.10 Invalidation After Updates or Deletions
+
+ The effect of certain methods performed on a resource at the origin
+ server might cause one or more existing cache entries to become non-
+ transparently invalid. That is, although they might continue to be
+ "fresh," they do not accurately reflect what the origin server would
+ return for a new request on that resource.
+
+
+
+Fielding, et al. Standards Track [Page 97]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ There is no way for the HTTP protocol to guarantee that all such
+ cache entries are marked invalid. For example, the request that
+ caused the change at the origin server might not have gone through
+ the proxy where a cache entry is stored. However, several rules help
+ reduce the likelihood of erroneous behavior.
+
+ In this section, the phrase "invalidate an entity" means that the
+ cache will either remove all instances of that entity from its
+ storage, or will mark these as "invalid" and in need of a mandatory
+ revalidation before they can be returned in response to a subsequent
+ request.
+
+ Some HTTP methods MUST cause a cache to invalidate an entity. This is
+ either the entity referred to by the Request-URI, or by the Location
+ or Content-Location headers (if present). These methods are:
+
+ - PUT
+
+ - DELETE
+
+ - POST
+
+ In order to prevent denial of service attacks, an invalidation based
+ on the URI in a Location or Content-Location header MUST only be
+ performed if the host part is the same as in the Request-URI.
+
+ A cache that passes through requests for methods it does not
+ understand SHOULD invalidate any entities referred to by the
+ Request-URI.
+
+13.11 Write-Through Mandatory
+
+ All methods that might be expected to cause modifications to the
+ origin server's resources MUST be written through to the origin
+ server. This currently includes all methods except for GET and HEAD.
+ A cache MUST NOT reply to such a request from a client before having
+ transmitted the request to the inbound server, and having received a
+ corresponding response from the inbound server. This does not prevent
+ a proxy cache from sending a 100 (Continue) response before the
+ inbound server has sent its final reply.
+
+ The alternative (known as "write-back" or "copy-back" caching) is not
+ allowed in HTTP/1.1, due to the difficulty of providing consistent
+ updates and the problems arising from server, cache, or network
+ failure prior to write-back.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 98]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.12 Cache Replacement
+
+ If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
+ response is received from a resource while any existing responses for
+ the same resource are cached, the cache SHOULD use the new response
+ to reply to the current request. It MAY insert it into cache storage
+ and MAY, if it meets all other requirements, use it to respond to any
+ future requests that would previously have caused the old response to
+ be returned. If it inserts the new response into cache storage the
+ rules in section 13.5.3 apply.
+
+ Note: a new response that has an older Date header value than
+ existing cached responses is not cacheable.
+
+13.13 History Lists
+
+ User agents often have history mechanisms, such as "Back" buttons and
+ history lists, which can be used to redisplay an entity retrieved
+ earlier in a session.
+
+ History mechanisms and caches are different. In particular history
+ mechanisms SHOULD NOT try to show a semantically transparent view of
+ the current state of a resource. Rather, a history mechanism is meant
+ to show exactly what the user saw at the time when the resource was
+ retrieved.
+
+ By default, an expiration time does not apply to history mechanisms.
+ If the entity is still in storage, a history mechanism SHOULD display
+ it even if the entity has expired, unless the user has specifically
+ configured the agent to refresh expired history documents.
+
+ This is not to be construed to prohibit the history mechanism from
+ telling the user that a view might be stale.
+
+ Note: if history list mechanisms unnecessarily prevent users from
+ viewing stale resources, this will tend to force service authors
+ to avoid using HTTP expiration controls and cache controls when
+ they would otherwise like to. Service authors may consider it
+ important that users not be presented with error messages or
+ warning messages when they use navigation controls (such as BACK)
+ to view previously fetched resources. Even though sometimes such
+ resources ought not to cached, or ought to expire quickly, user
+ interface considerations may force service authors to resort to
+ other means of preventing caching (e.g. "once-only" URLs) in order
+ not to suffer the effects of improperly functioning history
+ mechanisms.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 99]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14 Header Field Definitions
+
+ This section defines the syntax and semantics of all standard
+ HTTP/1.1 header fields. For entity-header fields, both sender and
+ recipient refer to either the client or the server, depending on who
+ sends and who receives the entity.
+
+14.1 Accept
+
+ The Accept request-header field can be used to specify certain media
+ types which are acceptable for the response. Accept headers can be
+ used to indicate that the request is specifically limited to a small
+ set of desired types, as in the case of a request for an in-line
+ image.
+
+ Accept = "Accept" ":"
+ #( media-range [ accept-params ] )
+
+ media-range = ( "*/*"
+ | ( type "/" "*" )
+ | ( type "/" subtype )
+ ) *( ";" parameter )
+ accept-params = ";" "q" "=" qvalue *( accept-extension )
+ accept-extension = ";" token [ "=" ( token | quoted-string ) ]
+
+ The asterisk "*" character is used to group media types into ranges,
+ with "*/*" indicating all media types and "type/*" indicating all
+ subtypes of that type. The media-range MAY include media type
+ parameters that are applicable to that range.
+
+ Each media-range MAY be followed by one or more accept-params,
+ beginning with the "q" parameter for indicating a relative quality
+ factor. The first "q" parameter (if any) separates the media-range
+ parameter(s) from the accept-params. Quality factors allow the user
+ or user agent to indicate the relative degree of preference for that
+ media-range, using the qvalue scale from 0 to 1 (section 3.9). The
+ default value is q=1.
+
+ Note: Use of the "q" parameter name to separate media type
+ parameters from Accept extension parameters is due to historical
+ practice. Although this prevents any media type parameter named
+ "q" from being used with a media range, such an event is believed
+ to be unlikely given the lack of any "q" parameters in the IANA
+ media type registry and the rare usage of any media type
+ parameters in Accept. Future media types are discouraged from
+ registering any parameter named "q".
+
+
+
+
+
+Fielding, et al. Standards Track [Page 100]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The example
+
+ Accept: audio/*; q=0.2, audio/basic
+
+ SHOULD be interpreted as "I prefer audio/basic, but send me any audio
+ type if it is the best available after an 80% mark-down in quality."
+
+ If no Accept header field is present, then it is assumed that the
+ client accepts all media types. If an Accept header field is present,
+ and if the server cannot send a response which is acceptable
+ according to the combined Accept field value, then the server SHOULD
+ send a 406 (not acceptable) response.
+
+ A more elaborate example is
+
+ Accept: text/plain; q=0.5, text/html,
+ text/x-dvi; q=0.8, text/x-c
+
+ Verbally, this would be interpreted as "text/html and text/x-c are
+ the preferred media types, but if they do not exist, then send the
+ text/x-dvi entity, and if that does not exist, send the text/plain
+ entity."
+
+ Media ranges can be overridden by more specific media ranges or
+ specific media types. If more than one media range applies to a given
+ type, the most specific reference has precedence. For example,
+
+ Accept: text/*, text/html, text/html;level=1, */*
+
+ have the following precedence:
+
+ 1) text/html;level=1
+ 2) text/html
+ 3) text/*
+ 4) */*
+
+ The media type quality factor associated with a given type is
+ determined by finding the media range with the highest precedence
+ which matches that type. For example,
+
+ Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
+ text/html;level=2;q=0.4, */*;q=0.5
+
+ would cause the following values to be associated:
+
+ text/html;level=1 = 1
+ text/html = 0.7
+ text/plain = 0.3
+
+
+
+Fielding, et al. Standards Track [Page 101]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ image/jpeg = 0.5
+ text/html;level=2 = 0.4
+ text/html;level=3 = 0.7
+
+ Note: A user agent might be provided with a default set of quality
+ values for certain media ranges. However, unless the user agent is
+ a closed system which cannot interact with other rendering agents,
+ this default set ought to be configurable by the user.
+
+14.2 Accept-Charset
+
+ The Accept-Charset request-header field can be used to indicate what
+ character sets are acceptable for the response. This field allows
+ clients capable of understanding more comprehensive or special-
+ purpose character sets to signal that capability to a server which is
+ capable of representing documents in those character sets.
+
+ Accept-Charset = "Accept-Charset" ":"
+ 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] )
+
+
+ Character set values are described in section 3.4. Each charset MAY
+ be given an associated quality value which represents the user's
+ preference for that charset. The default value is q=1. An example is
+
+ Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
+
+ The special value "*", if present in the Accept-Charset field,
+ matches every character set (including ISO-8859-1) which is not
+ mentioned elsewhere in the Accept-Charset field. If no "*" is present
+ in an Accept-Charset field, then all character sets not explicitly
+ mentioned get a quality value of 0, except for ISO-8859-1, which gets
+ a quality value of 1 if not explicitly mentioned.
+
+ If no Accept-Charset header is present, the default is that any
+ character set is acceptable. If an Accept-Charset header is present,
+ and if the server cannot send a response which is acceptable
+ according to the Accept-Charset header, then the server SHOULD send
+ an error response with the 406 (not acceptable) status code, though
+ the sending of an unacceptable response is also allowed.
+
+14.3 Accept-Encoding
+
+ The Accept-Encoding request-header field is similar to Accept, but
+ restricts the content-codings (section 3.5) that are acceptable in
+ the response.
+
+ Accept-Encoding = "Accept-Encoding" ":"
+
+
+
+Fielding, et al. Standards Track [Page 102]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1#( codings [ ";" "q" "=" qvalue ] )
+ codings = ( content-coding | "*" )
+
+ Examples of its use are:
+
+ Accept-Encoding: compress, gzip
+ Accept-Encoding:
+ Accept-Encoding: *
+ Accept-Encoding: compress;q=0.5, gzip;q=1.0
+ Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
+
+ A server tests whether a content-coding is acceptable, according to
+ an Accept-Encoding field, using these rules:
+
+ 1. If the content-coding is one of the content-codings listed in
+ the Accept-Encoding field, then it is acceptable, unless it is
+ accompanied by a qvalue of 0. (As defined in section 3.9, a
+ qvalue of 0 means "not acceptable.")
+
+ 2. The special "*" symbol in an Accept-Encoding field matches any
+ available content-coding not explicitly listed in the header
+ field.
+
+ 3. If multiple content-codings are acceptable, then the acceptable
+ content-coding with the highest non-zero qvalue is preferred.
+
+ 4. The "identity" content-coding is always acceptable, unless
+ specifically refused because the Accept-Encoding field includes
+ "identity;q=0", or because the field includes "*;q=0" and does
+ not explicitly include the "identity" content-coding. If the
+ Accept-Encoding field-value is empty, then only the "identity"
+ encoding is acceptable.
+
+ If an Accept-Encoding field is present in a request, and if the
+ server cannot send a response which is acceptable according to the
+ Accept-Encoding header, then the server SHOULD send an error response
+ with the 406 (Not Acceptable) status code.
+
+ If no Accept-Encoding field is present in a request, the server MAY
+ assume that the client will accept any content coding. In this case,
+ if "identity" is one of the available content-codings, then the
+ server SHOULD use the "identity" content-coding, unless it has
+ additional information that a different content-coding is meaningful
+ to the client.
+
+ Note: If the request does not include an Accept-Encoding field,
+ and if the "identity" content-coding is unavailable, then
+ content-codings commonly understood by HTTP/1.0 clients (i.e.,
+
+
+
+Fielding, et al. Standards Track [Page 103]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ "gzip" and "compress") are preferred; some older clients
+ improperly display messages sent with other content-codings. The
+ server might also make this decision based on information about
+ the particular user-agent or client.
+
+ Note: Most HTTP/1.0 applications do not recognize or obey qvalues
+ associated with content-codings. This means that qvalues will not
+ work and are not permitted with x-gzip or x-compress.
+
+14.4 Accept-Language
+
+ The Accept-Language request-header field is similar to Accept, but
+ restricts the set of natural languages that are preferred as a
+ response to the request. Language tags are defined in section 3.10.
+
+ Accept-Language = "Accept-Language" ":"
+ 1#( language-range [ ";" "q" "=" qvalue ] )
+ language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
+
+ Each language-range MAY be given an associated quality value which
+ represents an estimate of the user's preference for the languages
+ specified by that range. The quality value defaults to "q=1". For
+ example,
+
+ Accept-Language: da, en-gb;q=0.8, en;q=0.7
+
+ would mean: "I prefer Danish, but will accept British English and
+ other types of English." A language-range matches a language-tag if
+ it exactly equals the tag, or if it exactly equals a prefix of the
+ tag such that the first tag character following the prefix is "-".
+ The special range "*", if present in the Accept-Language field,
+ matches every tag not matched by any other range present in the
+ Accept-Language field.
+
+ Note: This use of a prefix matching rule does not imply that
+ language tags are assigned to languages in such a way that it is
+ always true that if a user understands a language with a certain
+ tag, then this user will also understand all languages with tags
+ for which this tag is a prefix. The prefix rule simply allows the
+ use of prefix tags if this is the case.
+
+ The language quality factor assigned to a language-tag by the
+ Accept-Language field is the quality value of the longest language-
+ range in the field that matches the language-tag. If no language-
+ range in the field matches the tag, the language quality factor
+ assigned is 0. If no Accept-Language header is present in the
+ request, the server
+
+
+
+
+Fielding, et al. Standards Track [Page 104]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ SHOULD assume that all languages are equally acceptable. If an
+ Accept-Language header is present, then all languages which are
+ assigned a quality factor greater than 0 are acceptable.
+
+ It might be contrary to the privacy expectations of the user to send
+ an Accept-Language header with the complete linguistic preferences of
+ the user in every request. For a discussion of this issue, see
+ section 15.1.4.
+
+ As intelligibility is highly dependent on the individual user, it is
+ recommended that client applications make the choice of linguistic
+ preference available to the user. If the choice is not made
+ available, then the Accept-Language header field MUST NOT be given in
+ the request.
+
+ Note: When making the choice of linguistic preference available to
+ the user, we remind implementors of the fact that users are not
+ familiar with the details of language matching as described above,
+ and should provide appropriate guidance. As an example, users
+ might assume that on selecting "en-gb", they will be served any
+ kind of English document if British English is not available. A
+ user agent might suggest in such a case to add "en" to get the
+ best matching behavior.
+
+14.5 Accept-Ranges
+
+ The Accept-Ranges response-header field allows the server to
+ indicate its acceptance of range requests for a resource:
+
+ Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
+ acceptable-ranges = 1#range-unit | "none"
+
+ Origin servers that accept byte-range requests MAY send
+
+ Accept-Ranges: bytes
+
+ but are not required to do so. Clients MAY generate byte-range
+ requests without having received this header for the resource
+ involved. Range units are defined in section 3.12.
+
+ Servers that do not accept any kind of range request for a
+ resource MAY send
+
+ Accept-Ranges: none
+
+ to advise the client not to attempt a range request.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 105]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.6 Age
+
+ The Age response-header field conveys the sender's estimate of the
+ amount of time since the response (or its revalidation) was
+ generated at the origin server. A cached response is "fresh" if
+ its age does not exceed its freshness lifetime. Age values are
+ calculated as specified in section 13.2.3.
+
+ Age = "Age" ":" age-value
+ age-value = delta-seconds
+
+ Age values are non-negative decimal integers, representing time in
+ seconds.
+
+ If a cache receives a value larger than the largest positive
+ integer it can represent, or if any of its age calculations
+ overflows, it MUST transmit an Age header with a value of
+ 2147483648 (2^31). An HTTP/1.1 server that includes a cache MUST
+ include an Age header field in every response generated from its
+ own cache. Caches SHOULD use an arithmetic type of at least 31
+ bits of range.
+
+14.7 Allow
+
+ The Allow entity-header field lists the set of methods supported
+ by the resource identified by the Request-URI. The purpose of this
+ field is strictly to inform the recipient of valid methods
+ associated with the resource. An Allow header field MUST be
+ present in a 405 (Method Not Allowed) response.
+
+ Allow = "Allow" ":" #Method
+
+ Example of use:
+
+ Allow: GET, HEAD, PUT
+
+ This field cannot prevent a client from trying other methods.
+ However, the indications given by the Allow header field value
+ SHOULD be followed. The actual set of allowed methods is defined
+ by the origin server at the time of each request.
+
+ The Allow header field MAY be provided with a PUT request to
+ recommend the methods to be supported by the new or modified
+ resource. The server is not required to support these methods and
+ SHOULD include an Allow header in the response giving the actual
+ supported methods.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 106]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A proxy MUST NOT modify the Allow header field even if it does not
+ understand all the methods specified, since the user agent might
+ have other means of communicating with the origin server.
+
+14.8 Authorization
+
+ A user agent that wishes to authenticate itself with a server--
+ usually, but not necessarily, after receiving a 401 response--does
+ so by including an Authorization request-header field with the
+ request. The Authorization field value consists of credentials
+ containing the authentication information of the user agent for
+ the realm of the resource being requested.
+
+ Authorization = "Authorization" ":" credentials
+
+ HTTP access authentication is described in "HTTP Authentication:
+ Basic and Digest Access Authentication" [43]. If a request is
+ authenticated and a realm specified, the same credentials SHOULD
+ be valid for all other requests within this realm (assuming that
+ the authentication scheme itself does not require otherwise, such
+ as credentials that vary according to a challenge value or using
+ synchronized clocks).
+
+ When a shared cache (see section 13.7) receives a request
+ containing an Authorization field, it MUST NOT return the
+ corresponding response as a reply to any other request, unless one
+ of the following specific exceptions holds:
+
+ 1. If the response includes the "s-maxage" cache-control
+ directive, the cache MAY use that response in replying to a
+ subsequent request. But (if the specified maximum age has
+ passed) a proxy cache MUST first revalidate it with the origin
+ server, using the request-headers from the new request to allow
+ the origin server to authenticate the new request. (This is the
+ defined behavior for s-maxage.) If the response includes "s-
+ maxage=0", the proxy MUST always revalidate it before re-using
+ it.
+
+ 2. If the response includes the "must-revalidate" cache-control
+ directive, the cache MAY use that response in replying to a
+ subsequent request. But if the response is stale, all caches
+ MUST first revalidate it with the origin server, using the
+ request-headers from the new request to allow the origin server
+ to authenticate the new request.
+
+ 3. If the response includes the "public" cache-control directive,
+ it MAY be returned in reply to any subsequent request.
+
+
+
+
+Fielding, et al. Standards Track [Page 107]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.9 Cache-Control
+
+ The Cache-Control general-header field is used to specify directives
+ that MUST be obeyed by all caching mechanisms along the
+ request/response chain. The directives specify behavior intended to
+ prevent caches from adversely interfering with the request or
+ response. These directives typically override the default caching
+ algorithms. Cache directives are unidirectional in that the presence
+ of a directive in a request does not imply that the same directive is
+ to be given in the response.
+
+ Note that HTTP/1.0 caches might not implement Cache-Control and
+ might only implement Pragma: no-cache (see section 14.32).
+
+ Cache directives MUST be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives might be applicable to all recipients along the
+ request/response chain. It is not possible to specify a cache-
+ directive for a specific cache.
+
+ Cache-Control = "Cache-Control" ":" 1#cache-directive
+
+ cache-directive = cache-request-directive
+ | cache-response-directive
+
+ cache-request-directive =
+ "no-cache" ; Section 14.9.1
+ | "no-store" ; Section 14.9.2
+ | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4
+ | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3
+ | "min-fresh" "=" delta-seconds ; Section 14.9.3
+ | "no-transform" ; Section 14.9.5
+ | "only-if-cached" ; Section 14.9.4
+ | cache-extension ; Section 14.9.6
+
+ cache-response-directive =
+ "public" ; Section 14.9.1
+ | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1
+ | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1
+ | "no-store" ; Section 14.9.2
+ | "no-transform" ; Section 14.9.5
+ | "must-revalidate" ; Section 14.9.4
+ | "proxy-revalidate" ; Section 14.9.4
+ | "max-age" "=" delta-seconds ; Section 14.9.3
+ | "s-maxage" "=" delta-seconds ; Section 14.9.3
+ | cache-extension ; Section 14.9.6
+
+ cache-extension = token [ "=" ( token | quoted-string ) ]
+
+
+
+Fielding, et al. Standards Track [Page 108]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ When a directive appears without any 1#field-name parameter, the
+ directive applies to the entire request or response. When such a
+ directive appears with a 1#field-name parameter, it applies only to
+ the named field or fields, and not to the rest of the request or
+ response. This mechanism supports extensibility; implementations of
+ future versions of the HTTP protocol might apply these directives to
+ header fields not defined in HTTP/1.1.
+
+ The cache-control directives can be broken down into these general
+ categories:
+
+ - Restrictions on what are cacheable; these may only be imposed by
+ the origin server.
+
+ - Restrictions on what may be stored by a cache; these may be
+ imposed by either the origin server or the user agent.
+
+ - Modifications of the basic expiration mechanism; these may be
+ imposed by either the origin server or the user agent.
+
+ - Controls over cache revalidation and reload; these may only be
+ imposed by a user agent.
+
+ - Control over transformation of entities.
+
+ - Extensions to the caching system.
+
+14.9.1 What is Cacheable
+
+ By default, a response is cacheable if the requirements of the
+ request method, request header fields, and the response status
+ indicate that it is cacheable. Section 13.4 summarizes these defaults
+ for cacheability. The following Cache-Control response directives
+ allow an origin server to override the default cacheability of a
+ response:
+
+ public
+ Indicates that the response MAY be cached by any cache, even if it
+ would normally be non-cacheable or cacheable only within a non-
+ shared cache. (See also Authorization, section 14.8, for
+ additional details.)
+
+ private
+ Indicates that all or part of the response message is intended for
+ a single user and MUST NOT be cached by a shared cache. This
+ allows an origin server to state that the specified parts of the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 109]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ response are intended for only one user and are not a valid
+ response for requests by other users. A private (non-shared) cache
+ MAY cache the response.
+
+ Note: This usage of the word private only controls where the
+ response may be cached, and cannot ensure the privacy of the
+ message content.
+
+ no-cache
+ If the no-cache directive does not specify a field-name, then a
+ cache MUST NOT use the response to satisfy a subsequent request
+ without successful revalidation with the origin server. This
+ allows an origin server to prevent caching even by caches that
+ have been configured to return stale responses to client requests.
+
+ If the no-cache directive does specify one or more field-names,
+ then a cache MAY use the response to satisfy a subsequent request,
+ subject to any other restrictions on caching. However, the
+ specified field-name(s) MUST NOT be sent in the response to a
+ subsequent request without successful revalidation with the origin
+ server. This allows an origin server to prevent the re-use of
+ certain header fields in a response, while still allowing caching
+ of the rest of the response.
+
+ Note: Most HTTP/1.0 caches will not recognize or obey this
+ directive.
+
+14.9.2 What May be Stored by Caches
+
+ no-store
+ The purpose of the no-store directive is to prevent the
+ inadvertent release or retention of sensitive information (for
+ example, on backup tapes). The no-store directive applies to the
+ entire message, and MAY be sent either in a response or in a
+ request. If sent in a request, a cache MUST NOT store any part of
+ either this request or any response to it. If sent in a response,
+ a cache MUST NOT store any part of either this response or the
+ request that elicited it. This directive applies to both non-
+ shared and shared caches. "MUST NOT store" in this context means
+ that the cache MUST NOT intentionally store the information in
+ non-volatile storage, and MUST make a best-effort attempt to
+ remove the information from volatile storage as promptly as
+ possible after forwarding it.
+
+ Even when this directive is associated with a response, users
+ might explicitly store such a response outside of the caching
+ system (e.g., with a "Save As" dialog). History buffers MAY store
+ such responses as part of their normal operation.
+
+
+
+Fielding, et al. Standards Track [Page 110]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The purpose of this directive is to meet the stated requirements
+ of certain users and service authors who are concerned about
+ accidental releases of information via unanticipated accesses to
+ cache data structures. While the use of this directive might
+ improve privacy in some cases, we caution that it is NOT in any
+ way a reliable or sufficient mechanism for ensuring privacy. In
+ particular, malicious or compromised caches might not recognize or
+ obey this directive, and communications networks might be
+ vulnerable to eavesdropping.
+
+14.9.3 Modifications of the Basic Expiration Mechanism
+
+ The expiration time of an entity MAY be specified by the origin
+ server using the Expires header (see section 14.21). Alternatively,
+ it MAY be specified using the max-age directive in a response. When
+ the max-age cache-control directive is present in a cached response,
+ the response is stale if its current age is greater than the age
+ value given (in seconds) at the time of a new request for that
+ resource. The max-age directive on a response implies that the
+ response is cacheable (i.e., "public") unless some other, more
+ restrictive cache directive is also present.
+
+ If a response includes both an Expires header and a max-age
+ directive, the max-age directive overrides the Expires header, even
+ if the Expires header is more restrictive. This rule allows an origin
+ server to provide, for a given response, a longer expiration time to
+ an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
+ useful if certain HTTP/1.0 caches improperly calculate ages or
+ expiration times, perhaps due to desynchronized clocks.
+
+ Many HTTP/1.0 cache implementations will treat an Expires value that
+ is less than or equal to the response Date value as being equivalent
+ to the Cache-Control response directive "no-cache". If an HTTP/1.1
+ cache receives such a response, and the response does not include a
+ Cache-Control header field, it SHOULD consider the response to be
+ non-cacheable in order to retain compatibility with HTTP/1.0 servers.
+
+ Note: An origin server might wish to use a relatively new HTTP
+ cache control feature, such as the "private" directive, on a
+ network including older caches that do not understand that
+ feature. The origin server will need to combine the new feature
+ with an Expires field whose value is less than or equal to the
+ Date value. This will prevent older caches from improperly
+ caching the response.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 111]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ s-maxage
+ If a response includes an s-maxage directive, then for a shared
+ cache (but not for a private cache), the maximum age specified by
+ this directive overrides the maximum age specified by either the
+ max-age directive or the Expires header. The s-maxage directive
+ also implies the semantics of the proxy-revalidate directive (see
+ section 14.9.4), i.e., that the shared cache must not use the
+ entry after it becomes stale to respond to a subsequent request
+ without first revalidating it with the origin server. The s-
+ maxage directive is always ignored by a private cache.
+
+ Note that most older caches, not compliant with this specification,
+ do not implement any cache-control directives. An origin server
+ wishing to use a cache-control directive that restricts, but does not
+ prevent, caching by an HTTP/1.1-compliant cache MAY exploit the
+ requirement that the max-age directive overrides the Expires header,
+ and the fact that pre-HTTP/1.1-compliant caches do not observe the
+ max-age directive.
+
+ Other directives allow a user agent to modify the basic expiration
+ mechanism. These directives MAY be specified on a request:
+
+ max-age
+ Indicates that the client is willing to accept a response whose
+ age is no greater than the specified time in seconds. Unless max-
+ stale directive is also included, the client is not willing to
+ accept a stale response.
+
+ min-fresh
+ Indicates that the client is willing to accept a response whose
+ freshness lifetime is no less than its current age plus the
+ specified time in seconds. That is, the client wants a response
+ that will still be fresh for at least the specified number of
+ seconds.
+
+ max-stale
+ Indicates that the client is willing to accept a response that has
+ exceeded its expiration time. If max-stale is assigned a value,
+ then the client is willing to accept a response that has exceeded
+ its expiration time by no more than the specified number of
+ seconds. If no value is assigned to max-stale, then the client is
+ willing to accept a stale response of any age.
+
+ If a cache returns a stale response, either because of a max-stale
+ directive on a request, or because the cache is configured to
+ override the expiration time of a response, the cache MUST attach a
+ Warning header to the stale response, using Warning 110 (Response is
+ stale).
+
+
+
+Fielding, et al. Standards Track [Page 112]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A cache MAY be configured to return stale responses without
+ validation, but only if this does not conflict with any "MUST"-level
+ requirements concerning cache validation (e.g., a "must-revalidate"
+ cache-control directive).
+
+ If both the new request and the cached entry include "max-age"
+ directives, then the lesser of the two values is used for determining
+ the freshness of the cached entry for that request.
+
+14.9.4 Cache Revalidation and Reload Controls
+
+ Sometimes a user agent might want or need to insist that a cache
+ revalidate its cache entry with the origin server (and not just with
+ the next cache along the path to the origin server), or to reload its
+ cache entry from the origin server. End-to-end revalidation might be
+ necessary if either the cache or the origin server has overestimated
+ the expiration time of the cached response. End-to-end reload may be
+ necessary if the cache entry has become corrupted for some reason.
+
+ End-to-end revalidation may be requested either when the client does
+ not have its own local cached copy, in which case we call it
+ "unspecified end-to-end revalidation", or when the client does have a
+ local cached copy, in which case we call it "specific end-to-end
+ revalidation."
+
+ The client can specify these three kinds of action using Cache-
+ Control request directives:
+
+ End-to-end reload
+ The request includes a "no-cache" cache-control directive or, for
+ compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field
+ names MUST NOT be included with the no-cache directive in a
+ request. The server MUST NOT use a cached copy when responding to
+ such a request.
+
+ Specific end-to-end revalidation
+ The request includes a "max-age=0" cache-control directive, which
+ forces each cache along the path to the origin server to
+ revalidate its own entry, if any, with the next cache or server.
+ The initial request includes a cache-validating conditional with
+ the client's current validator.
+
+ Unspecified end-to-end revalidation
+ The request includes "max-age=0" cache-control directive, which
+ forces each cache along the path to the origin server to
+ revalidate its own entry, if any, with the next cache or server.
+ The initial request does not include a cache-validating
+
+
+
+
+Fielding, et al. Standards Track [Page 113]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ conditional; the first cache along the path (if any) that holds a
+ cache entry for this resource includes a cache-validating
+ conditional with its current validator.
+
+ max-age
+ When an intermediate cache is forced, by means of a max-age=0
+ directive, to revalidate its own cache entry, and the client has
+ supplied its own validator in the request, the supplied validator
+ might differ from the validator currently stored with the cache
+ entry. In this case, the cache MAY use either validator in making
+ its own request without affecting semantic transparency.
+
+ However, the choice of validator might affect performance. The
+ best approach is for the intermediate cache to use its own
+ validator when making its request. If the server replies with 304
+ (Not Modified), then the cache can return its now validated copy
+ to the client with a 200 (OK) response. If the server replies with
+ a new entity and cache validator, however, the intermediate cache
+ can compare the returned validator with the one provided in the
+ client's request, using the strong comparison function. If the
+ client's validator is equal to the origin server's, then the
+ intermediate cache simply returns 304 (Not Modified). Otherwise,
+ it returns the new entity with a 200 (OK) response.
+
+ If a request includes the no-cache directive, it SHOULD NOT
+ include min-fresh, max-stale, or max-age.
+
+ only-if-cached
+ In some cases, such as times of extremely poor network
+ connectivity, a client may want a cache to return only those
+ responses that it currently has stored, and not to reload or
+ revalidate with the origin server. To do this, the client may
+ include the only-if-cached directive in a request. If it receives
+ this directive, a cache SHOULD either respond using a cached entry
+ that is consistent with the other constraints of the request, or
+ respond with a 504 (Gateway Timeout) status. However, if a group
+ of caches is being operated as a unified system with good internal
+ connectivity, such a request MAY be forwarded within that group of
+ caches.
+
+ must-revalidate
+ Because a cache MAY be configured to ignore a server's specified
+ expiration time, and because a client request MAY include a max-
+ stale directive (which has a similar effect), the protocol also
+ includes a mechanism for the origin server to require revalidation
+ of a cache entry on any subsequent use. When the must-revalidate
+ directive is present in a response received by a cache, that cache
+ MUST NOT use the entry after it becomes stale to respond to a
+
+
+
+Fielding, et al. Standards Track [Page 114]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ subsequent request without first revalidating it with the origin
+ server. (I.e., the cache MUST do an end-to-end revalidation every
+ time, if, based solely on the origin server's Expires or max-age
+ value, the cached response is stale.)
+
+ The must-revalidate directive is necessary to support reliable
+ operation for certain protocol features. In all circumstances an
+ HTTP/1.1 cache MUST obey the must-revalidate directive; in
+ particular, if the cache cannot reach the origin server for any
+ reason, it MUST generate a 504 (Gateway Timeout) response.
+
+ Servers SHOULD send the must-revalidate directive if and only if
+ failure to revalidate a request on the entity could result in
+ incorrect operation, such as a silently unexecuted financial
+ transaction. Recipients MUST NOT take any automated action that
+ violates this directive, and MUST NOT automatically provide an
+ unvalidated copy of the entity if revalidation fails.
+
+ Although this is not recommended, user agents operating under
+ severe connectivity constraints MAY violate this directive but, if
+ so, MUST explicitly warn the user that an unvalidated response has
+ been provided. The warning MUST be provided on each unvalidated
+ access, and SHOULD require explicit user confirmation.
+
+ proxy-revalidate
+ The proxy-revalidate directive has the same meaning as the must-
+ revalidate directive, except that it does not apply to non-shared
+ user agent caches. It can be used on a response to an
+ authenticated request to permit the user's cache to store and
+ later return the response without needing to revalidate it (since
+ it has already been authenticated once by that user), while still
+ requiring proxies that service many users to revalidate each time
+ (in order to make sure that each user has been authenticated).
+ Note that such authenticated responses also need the public cache
+ control directive in order to allow them to be cached at all.
+
+14.9.5 No-Transform Directive
+
+ no-transform
+ Implementors of intermediate caches (proxies) have found it useful
+ to convert the media type of certain entity bodies. A non-
+ transparent proxy might, for example, convert between image
+ formats in order to save cache space or to reduce the amount of
+ traffic on a slow link.
+
+ Serious operational problems occur, however, when these
+ transformations are applied to entity bodies intended for certain
+ kinds of applications. For example, applications for medical
+
+
+
+Fielding, et al. Standards Track [Page 115]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ imaging, scientific data analysis and those using end-to-end
+ authentication, all depend on receiving an entity body that is bit
+ for bit identical to the original entity-body.
+
+ Therefore, if a message includes the no-transform directive, an
+ intermediate cache or proxy MUST NOT change those headers that are
+ listed in section 13.5.2 as being subject to the no-transform
+ directive. This implies that the cache or proxy MUST NOT change
+ any aspect of the entity-body that is specified by these headers,
+ including the value of the entity-body itself.
+
+14.9.6 Cache Control Extensions
+
+ The Cache-Control header field can be extended through the use of one
+ or more cache-extension tokens, each with an optional assigned value.
+ Informational extensions (those which do not require a change in
+ cache behavior) MAY be added without changing the semantics of other
+ directives. Behavioral extensions are designed to work by acting as
+ modifiers to the existing base of cache directives. Both the new
+ directive and the standard directive are supplied, such that
+ applications which do not understand the new directive will default
+ to the behavior specified by the standard directive, and those that
+ understand the new directive will recognize it as modifying the
+ requirements associated with the standard directive. In this way,
+ extensions to the cache-control directives can be made without
+ requiring changes to the base protocol.
+
+ This extension mechanism depends on an HTTP cache obeying all of the
+ cache-control directives defined for its native HTTP-version, obeying
+ certain extensions, and ignoring all directives that it does not
+ understand.
+
+ For example, consider a hypothetical new response directive called
+ community which acts as a modifier to the private directive. We
+ define this new directive to mean that, in addition to any non-shared
+ cache, any cache which is shared only by members of the community
+ named within its value may cache the response. An origin server
+ wishing to allow the UCI community to use an otherwise private
+ response in their shared cache(s) could do so by including
+
+ Cache-Control: private, community="UCI"
+
+ A cache seeing this header field will act correctly even if the cache
+ does not understand the community cache-extension, since it will also
+ see and understand the private directive and thus default to the safe
+ behavior.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 116]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Unrecognized cache-directives MUST be ignored; it is assumed that any
+ cache-directive likely to be unrecognized by an HTTP/1.1 cache will
+ be combined with standard directives (or the response's default
+ cacheability) such that the cache behavior will remain minimally
+ correct even if the cache does not understand the extension(s).
+
+14.10 Connection
+
+ The Connection general-header field allows the sender to specify
+ options that are desired for that particular connection and MUST NOT
+ be communicated by proxies over further connections.
+
+ The Connection header has the following grammar:
+
+ Connection = "Connection" ":" 1#(connection-token)
+ connection-token = token
+
+ HTTP/1.1 proxies MUST parse the Connection header field before a
+ message is forwarded and, for each connection-token in this field,
+ remove any header field(s) from the message with the same name as the
+ connection-token. Connection options are signaled by the presence of
+ a connection-token in the Connection header field, not by any
+ corresponding additional header field(s), since the additional header
+ field may not be sent if there are no parameters associated with that
+ connection option.
+
+ Message headers listed in the Connection header MUST NOT include
+ end-to-end headers, such as Cache-Control.
+
+ HTTP/1.1 defines the "close" connection option for the sender to
+ signal that the connection will be closed after completion of the
+ response. For example,
+
+ Connection: close
+
+ in either the request or the response header fields indicates that
+ the connection SHOULD NOT be considered `persistent' (section 8.1)
+ after the current request/response is complete.
+
+ HTTP/1.1 applications that do not support persistent connections MUST
+ include the "close" connection option in every message.
+
+ A system receiving an HTTP/1.0 (or lower-version) message that
+ includes a Connection header MUST, for each connection-token in this
+ field, remove and ignore any header field(s) from the message with
+ the same name as the connection-token. This protects against mistaken
+ forwarding of such header fields by pre-HTTP/1.1 proxies. See section
+ 19.6.2.
+
+
+
+Fielding, et al. Standards Track [Page 117]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.11 Content-Encoding
+
+ The Content-Encoding entity-header field is used as a modifier to the
+ media-type. When present, its value indicates what additional content
+ codings have been applied to the entity-body, and thus what decoding
+ mechanisms must be applied in order to obtain the media-type
+ referenced by the Content-Type header field. Content-Encoding is
+ primarily used to allow a document to be compressed without losing
+ the identity of its underlying media type.
+
+ Content-Encoding = "Content-Encoding" ":" 1#content-coding
+
+ Content codings are defined in section 3.5. An example of its use is
+
+ Content-Encoding: gzip
+
+ The content-coding is a characteristic of the entity identified by
+ the Request-URI. Typically, the entity-body is stored with this
+ encoding and is only decoded before rendering or analogous usage.
+ However, a non-transparent proxy MAY modify the content-coding if the
+ new coding is known to be acceptable to the recipient, unless the
+ "no-transform" cache-control directive is present in the message.
+
+ If the content-coding of an entity is not "identity", then the
+ response MUST include a Content-Encoding entity-header (section
+ 14.11) that lists the non-identity content-coding(s) used.
+
+ If the content-coding of an entity in a request message is not
+ acceptable to the origin server, the server SHOULD respond with a
+ status code of 415 (Unsupported Media Type).
+
+ If multiple encodings have been applied to an entity, the content
+ codings MUST be listed in the order in which they were applied.
+ Additional information about the encoding parameters MAY be provided
+ by other entity-header fields not defined by this specification.
+
+14.12 Content-Language
+
+ The Content-Language entity-header field describes the natural
+ language(s) of the intended audience for the enclosed entity. Note
+ that this might not be equivalent to all the languages used within
+ the entity-body.
+
+ Content-Language = "Content-Language" ":" 1#language-tag
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 118]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Language tags are defined in section 3.10. The primary purpose of
+ Content-Language is to allow a user to identify and differentiate
+ entities according to the user's own preferred language. Thus, if the
+ body content is intended only for a Danish-literate audience, the
+ appropriate field is
+
+ Content-Language: da
+
+ If no Content-Language is specified, the default is that the content
+ is intended for all language audiences. This might mean that the
+ sender does not consider it to be specific to any natural language,
+ or that the sender does not know for which language it is intended.
+
+ Multiple languages MAY be listed for content that is intended for
+ multiple audiences. For example, a rendition of the "Treaty of
+ Waitangi," presented simultaneously in the original Maori and English
+ versions, would call for
+
+ Content-Language: mi, en
+
+ However, just because multiple languages are present within an entity
+ does not mean that it is intended for multiple linguistic audiences.
+ An example would be a beginner's language primer, such as "A First
+ Lesson in Latin," which is clearly intended to be used by an
+ English-literate audience. In this case, the Content-Language would
+ properly only include "en".
+
+ Content-Language MAY be applied to any media type -- it is not
+ limited to textual documents.
+
+14.13 Content-Length
+
+ The Content-Length entity-header field indicates the size of the
+ entity-body, in decimal number of OCTETs, sent to the recipient or,
+ in the case of the HEAD method, the size of the entity-body that
+ would have been sent had the request been a GET.
+
+ Content-Length = "Content-Length" ":" 1*DIGIT
+
+ An example is
+
+ Content-Length: 3495
+
+ Applications SHOULD use this field to indicate the transfer-length of
+ the message-body, unless this is prohibited by the rules in section
+ 4.4.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 119]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Any Content-Length greater than or equal to zero is a valid value.
+ Section 4.4 describes how to determine the length of a message-body
+ if a Content-Length is not given.
+
+ Note that the meaning of this field is significantly different from
+ the corresponding definition in MIME, where it is an optional field
+ used within the "message/external-body" content-type. In HTTP, it
+ SHOULD be sent whenever the message's length can be determined prior
+ to being transferred, unless this is prohibited by the rules in
+ section 4.4.
+
+14.14 Content-Location
+
+ The Content-Location entity-header field MAY be used to supply the
+ resource location for the entity enclosed in the message when that
+ entity is accessible from a location separate from the requested
+ resource's URI. A server SHOULD provide a Content-Location for the
+ variant corresponding to the response entity; especially in the case
+ where a resource has multiple entities associated with it, and those
+ entities actually have separate locations by which they might be
+ individually accessed, the server SHOULD provide a Content-Location
+ for the particular variant which is returned.
+
+ Content-Location = "Content-Location" ":"
+ ( absoluteURI | relativeURI )
+
+ The value of Content-Location also defines the base URI for the
+ entity.
+
+ The Content-Location value is not a replacement for the original
+ requested URI; it is only a statement of the location of the resource
+ corresponding to this particular entity at the time of the request.
+ Future requests MAY specify the Content-Location URI as the request-
+ URI if the desire is to identify the source of that particular
+ entity.
+
+ A cache cannot assume that an entity with a Content-Location
+ different from the URI used to retrieve it can be used to respond to
+ later requests on that Content-Location URI. However, the Content-
+ Location can be used to differentiate between multiple entities
+ retrieved from a single requested resource, as described in section
+ 13.6.
+
+ If the Content-Location is a relative URI, the relative URI is
+ interpreted relative to the Request-URI.
+
+ The meaning of the Content-Location header in PUT or POST requests is
+ undefined; servers are free to ignore it in those cases.
+
+
+
+Fielding, et al. Standards Track [Page 120]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.15 Content-MD5
+
+ The Content-MD5 entity-header field, as defined in RFC 1864 [23], is
+ an MD5 digest of the entity-body for the purpose of providing an
+ end-to-end message integrity check (MIC) of the entity-body. (Note: a
+ MIC is good for detecting accidental modification of the entity-body
+ in transit, but is not proof against malicious attacks.)
+
+ Content-MD5 = "Content-MD5" ":" md5-digest
+ md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
+
+ The Content-MD5 header field MAY be generated by an origin server or
+ client to function as an integrity check of the entity-body. Only
+ origin servers or clients MAY generate the Content-MD5 header field;
+ proxies and gateways MUST NOT generate it, as this would defeat its
+ value as an end-to-end integrity check. Any recipient of the entity-
+ body, including gateways and proxies, MAY check that the digest value
+ in this header field matches that of the entity-body as received.
+
+ The MD5 digest is computed based on the content of the entity-body,
+ including any content-coding that has been applied, but not including
+ any transfer-encoding applied to the message-body. If the message is
+ received with a transfer-encoding, that encoding MUST be removed
+ prior to checking the Content-MD5 value against the received entity.
+
+ This has the result that the digest is computed on the octets of the
+ entity-body exactly as, and in the order that, they would be sent if
+ no transfer-encoding were being applied.
+
+ HTTP extends RFC 1864 to permit the digest to be computed for MIME
+ composite media-types (e.g., multipart/* and message/rfc822), but
+ this does not change how the digest is computed as defined in the
+ preceding paragraph.
+
+ There are several consequences of this. The entity-body for composite
+ types MAY contain many body-parts, each with its own MIME and HTTP
+ headers (including Content-MD5, Content-Transfer-Encoding, and
+ Content-Encoding headers). If a body-part has a Content-Transfer-
+ Encoding or Content-Encoding header, it is assumed that the content
+ of the body-part has had the encoding applied, and the body-part is
+ included in the Content-MD5 digest as is -- i.e., after the
+ application. The Transfer-Encoding header field is not allowed within
+ body-parts.
+
+ Conversion of all line breaks to CRLF MUST NOT be done before
+ computing or checking the digest: the line break convention used in
+ the text actually transmitted MUST be left unaltered when computing
+ the digest.
+
+
+
+Fielding, et al. Standards Track [Page 121]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note: while the definition of Content-MD5 is exactly the same for
+ HTTP as in RFC 1864 for MIME entity-bodies, there are several ways
+ in which the application of Content-MD5 to HTTP entity-bodies
+ differs from its application to MIME entity-bodies. One is that
+ HTTP, unlike MIME, does not use Content-Transfer-Encoding, and
+ does use Transfer-Encoding and Content-Encoding. Another is that
+ HTTP more frequently uses binary content types than MIME, so it is
+ worth noting that, in such cases, the byte order used to compute
+ the digest is the transmission byte order defined for the type.
+ Lastly, HTTP allows transmission of text types with any of several
+ line break conventions and not just the canonical form using CRLF.
+
+14.16 Content-Range
+
+ The Content-Range entity-header is sent with a partial entity-body to
+ specify where in the full entity-body the partial body should be
+ applied. Range units are defined in section 3.12.
+
+ Content-Range = "Content-Range" ":" content-range-spec
+
+ content-range-spec = byte-content-range-spec
+ byte-content-range-spec = bytes-unit SP
+ byte-range-resp-spec "/"
+ ( instance-length | "*" )
+
+ byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
+ | "*"
+ instance-length = 1*DIGIT
+
+ The header SHOULD indicate the total length of the full entity-body,
+ unless this length is unknown or difficult to determine. The asterisk
+ "*" character means that the instance-length is unknown at the time
+ when the response was generated.
+
+ Unlike byte-ranges-specifier values (see section 14.35.1), a byte-
+ range-resp-spec MUST only specify one range, and MUST contain
+ absolute byte positions for both the first and last byte of the
+ range.
+
+ A byte-content-range-spec with a byte-range-resp-spec whose last-
+ byte-pos value is less than its first-byte-pos value, or whose
+ instance-length value is less than or equal to its last-byte-pos
+ value, is invalid. The recipient of an invalid byte-content-range-
+ spec MUST ignore it and any content transferred along with it.
+
+ A server sending a response with status code 416 (Requested range not
+ satisfiable) SHOULD include a Content-Range field with a byte-range-
+ resp-spec of "*". The instance-length specifies the current length of
+
+
+
+Fielding, et al. Standards Track [Page 122]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the selected resource. A response with status code 206 (Partial
+ Content) MUST NOT include a Content-Range field with a byte-range-
+ resp-spec of "*".
+
+ Examples of byte-content-range-spec values, assuming that the entity
+ contains a total of 1234 bytes:
+
+ . The first 500 bytes:
+ bytes 0-499/1234
+
+ . The second 500 bytes:
+ bytes 500-999/1234
+
+ . All except for the first 500 bytes:
+ bytes 500-1233/1234
+
+ . The last 500 bytes:
+ bytes 734-1233/1234
+
+ When an HTTP message includes the content of a single range (for
+ example, a response to a request for a single range, or to a request
+ for a set of ranges that overlap without any holes), this content is
+ transmitted with a Content-Range header, and a Content-Length header
+ showing the number of bytes actually transferred. For example,
+
+ HTTP/1.1 206 Partial content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-Range: bytes 21010-47021/47022
+ Content-Length: 26012
+ Content-Type: image/gif
+
+ When an HTTP message includes the content of multiple ranges (for
+ example, a response to a request for multiple non-overlapping
+ ranges), these are transmitted as a multipart message. The multipart
+ media type used for this purpose is "multipart/byteranges" as defined
+ in appendix 19.2. See appendix 19.6.3 for a compatibility issue.
+
+ A response to a request for a single range MUST NOT be sent using the
+ multipart/byteranges media type. A response to a request for
+ multiple ranges, whose result is a single range, MAY be sent as a
+ multipart/byteranges media type with one part. A client that cannot
+ decode a multipart/byteranges message MUST NOT ask for multiple
+ byte-ranges in a single request.
+
+ When a client requests multiple byte-ranges in one request, the
+ server SHOULD return them in the order that they appeared in the
+ request.
+
+
+
+Fielding, et al. Standards Track [Page 123]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the server ignores a byte-range-spec because it is syntactically
+ invalid, the server SHOULD treat the request as if the invalid Range
+ header field did not exist. (Normally, this means return a 200
+ response containing the full entity).
+
+ If the server receives a request (other than one including an If-
+ Range request-header field) with an unsatisfiable Range request-
+ header field (that is, all of whose byte-range-spec values have a
+ first-byte-pos value greater than the current length of the selected
+ resource), it SHOULD return a response code of 416 (Requested range
+ not satisfiable) (section 10.4.17).
+
+ Note: clients cannot depend on servers to send a 416 (Requested
+ range not satisfiable) response instead of a 200 (OK) response for
+ an unsatisfiable Range request-header, since not all servers
+ implement this request-header.
+
+14.17 Content-Type
+
+ The Content-Type entity-header field indicates the media type of the
+ entity-body sent to the recipient or, in the case of the HEAD method,
+ the media type that would have been sent had the request been a GET.
+
+ Content-Type = "Content-Type" ":" media-type
+
+ Media types are defined in section 3.7. An example of the field is
+
+ Content-Type: text/html; charset=ISO-8859-4
+
+ Further discussion of methods for identifying the media type of an
+ entity is provided in section 7.2.1.
+
+14.18 Date
+
+ The Date general-header field represents the date and time at which
+ the message was originated, having the same semantics as orig-date in
+ RFC 822. The field value is an HTTP-date, as described in section
+ 3.3.1; it MUST be sent in RFC 1123 [8]-date format.
+
+ Date = "Date" ":" HTTP-date
+
+ An example is
+
+ Date: Tue, 15 Nov 1994 08:12:31 GMT
+
+ Origin servers MUST include a Date header field in all responses,
+ except in these cases:
+
+
+
+
+Fielding, et al. Standards Track [Page 124]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1. If the response status code is 100 (Continue) or 101 (Switching
+ Protocols), the response MAY include a Date header field, at
+ the server's option.
+
+ 2. If the response status code conveys a server error, e.g. 500
+ (Internal Server Error) or 503 (Service Unavailable), and it is
+ inconvenient or impossible to generate a valid Date.
+
+ 3. If the server does not have a clock that can provide a
+ reasonable approximation of the current time, its responses
+ MUST NOT include a Date header field. In this case, the rules
+ in section 14.18.1 MUST be followed.
+
+ A received message that does not have a Date header field MUST be
+ assigned one by the recipient if the message will be cached by that
+ recipient or gatewayed via a protocol which requires a Date. An HTTP
+ implementation without a clock MUST NOT cache responses without
+ revalidating them on every use. An HTTP cache, especially a shared
+ cache, SHOULD use a mechanism, such as NTP [28], to synchronize its
+ clock with a reliable external standard.
+
+ Clients SHOULD only send a Date header field in messages that include
+ an entity-body, as in the case of the PUT and POST requests, and even
+ then it is optional. A client without a clock MUST NOT send a Date
+ header field in a request.
+
+ The HTTP-date sent in a Date header SHOULD NOT represent a date and
+ time subsequent to the generation of the message. It SHOULD represent
+ the best available approximation of the date and time of message
+ generation, unless the implementation has no means of generating a
+ reasonably accurate date and time. In theory, the date ought to
+ represent the moment just before the entity is generated. In
+ practice, the date can be generated at any time during the message
+ origination without affecting its semantic value.
+
+14.18.1 Clockless Origin Server Operation
+
+ Some origin server implementations might not have a clock available.
+ An origin server without a clock MUST NOT assign Expires or Last-
+ Modified values to a response, unless these values were associated
+ with the resource by a system or user with a reliable clock. It MAY
+ assign an Expires value that is known, at or before server
+ configuration time, to be in the past (this allows "pre-expiration"
+ of responses without storing separate Expires values for each
+ resource).
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 125]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.19 ETag
+
+ The ETag response-header field provides the current value of the
+ entity tag for the requested variant. The headers used with entity
+ tags are described in sections 14.24, 14.26 and 14.44. The entity tag
+ MAY be used for comparison with other entities from the same resource
+ (see section 13.3.3).
+
+ ETag = "ETag" ":" entity-tag
+
+ Examples:
+
+ ETag: "xyzzy"
+ ETag: W/"xyzzy"
+ ETag: ""
+
+14.20 Expect
+
+ The Expect request-header field is used to indicate that particular
+ server behaviors are required by the client.
+
+ Expect = "Expect" ":" 1#expectation
+
+ expectation = "100-continue" | expectation-extension
+ expectation-extension = token [ "=" ( token | quoted-string )
+ *expect-params ]
+ expect-params = ";" token [ "=" ( token | quoted-string ) ]
+
+
+ A server that does not understand or is unable to comply with any of
+ the expectation values in the Expect field of a request MUST respond
+ with appropriate error status. The server MUST respond with a 417
+ (Expectation Failed) status if any of the expectations cannot be met
+ or, if there are other problems with the request, some other 4xx
+ status.
+
+ This header field is defined with extensible syntax to allow for
+ future extensions. If a server receives a request containing an
+ Expect field that includes an expectation-extension that it does not
+ support, it MUST respond with a 417 (Expectation Failed) status.
+
+ Comparison of expectation values is case-insensitive for unquoted
+ tokens (including the 100-continue token), and is case-sensitive for
+ quoted-string expectation-extensions.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 126]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST
+ return a 417 (Expectation Failed) status if it receives a request
+ with an expectation that it cannot meet. However, the Expect
+ request-header itself is end-to-end; it MUST be forwarded if the
+ request is forwarded.
+
+ Many older HTTP/1.0 and HTTP/1.1 applications do not understand the
+ Expect header.
+
+ See section 8.2.3 for the use of the 100 (continue) status.
+
+14.21 Expires
+
+ The Expires entity-header field gives the date/time after which the
+ response is considered stale. A stale cache entry may not normally be
+ returned by a cache (either a proxy cache or a user agent cache)
+ unless it is first validated with the origin server (or with an
+ intermediate cache that has a fresh copy of the entity). See section
+ 13.2 for further discussion of the expiration model.
+
+ The presence of an Expires field does not imply that the original
+ resource will change or cease to exist at, before, or after that
+ time.
+
+ The format is an absolute date and time as defined by HTTP-date in
+ section 3.3.1; it MUST be in RFC 1123 date format:
+
+ Expires = "Expires" ":" HTTP-date
+
+ An example of its use is
+
+ Expires: Thu, 01 Dec 1994 16:00:00 GMT
+
+ Note: if a response includes a Cache-Control field with the max-
+ age directive (see section 14.9.3), that directive overrides the
+ Expires field.
+
+ HTTP/1.1 clients and caches MUST treat other invalid date formats,
+ especially including the value "0", as in the past (i.e., "already
+ expired").
+
+ To mark a response as "already expired," an origin server sends an
+ Expires date that is equal to the Date header value. (See the rules
+ for expiration calculations in section 13.2.4.)
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 127]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ To mark a response as "never expires," an origin server sends an
+ Expires date approximately one year from the time the response is
+ sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one
+ year in the future.
+
+ The presence of an Expires header field with a date value of some
+ time in the future on a response that otherwise would by default be
+ non-cacheable indicates that the response is cacheable, unless
+ indicated otherwise by a Cache-Control header field (section 14.9).
+
+14.22 From
+
+ The From request-header field, if given, SHOULD contain an Internet
+ e-mail address for the human user who controls the requesting user
+ agent. The address SHOULD be machine-usable, as defined by "mailbox"
+ in RFC 822 [9] as updated by RFC 1123 [8]:
+
+ From = "From" ":" mailbox
+
+ An example is:
+
+
+ This header field MAY be used for logging purposes and as a means for
+ identifying the source of invalid or unwanted requests. It SHOULD NOT
+ be used as an insecure form of access protection. The interpretation
+ of this field is that the request is being performed on behalf of the
+ person given, who accepts responsibility for the method performed. In
+ particular, robot agents SHOULD include this header so that the
+ person responsible for running the robot can be contacted if problems
+ occur on the receiving end.
+
+ The Internet e-mail address in this field MAY be separate from the
+ Internet host which issued the request. For example, when a request
+ is passed through a proxy the original issuer's address SHOULD be
+ used.
+
+ The client SHOULD NOT send the From header field without the user's
+ approval, as it might conflict with the user's privacy interests or
+ their site's security policy. It is strongly recommended that the
+ user be able to disable, enable, and modify the value of this field
+ at any time prior to a request.
+
+14.23 Host
+
+ The Host request-header field specifies the Internet host and port
+ number of the resource being requested, as obtained from the original
+ URI given by the user or referring resource (generally an HTTP URL,
+
+
+
+Fielding, et al. Standards Track [Page 128]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ as described in section 3.2.2). The Host field value MUST represent
+ the naming authority of the origin server or gateway given by the
+ original URL. This allows the origin server or gateway to
+ differentiate between internally-ambiguous URLs, such as the root "/"
+ URL of a server for multiple host names on a single IP address.
+
+ Host = "Host" ":" host [ ":" port ] ; Section 3.2.2
+
+ A "host" without any trailing port information implies the default
+ port for the service requested (e.g., "80" for an HTTP URL). For
+ example, a request on the origin server for
+ <http://www.w3.org/pub/WWW/> would properly include:
+
+ GET /pub/WWW/ HTTP/1.1
+ Host: www.w3.org
+
+ A client MUST include a Host header field in all HTTP/1.1 request
+ messages . If the requested URI does not include an Internet host
+ name for the service being requested, then the Host header field MUST
+ be given with an empty value. An HTTP/1.1 proxy MUST ensure that any
+ request message it forwards does contain an appropriate Host header
+ field that identifies the service being requested by the proxy. All
+ Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request)
+ status code to any HTTP/1.1 request message which lacks a Host header
+ field.
+
+ See sections 5.2 and 19.6.1.1 for other requirements relating to
+ Host.
+
+14.24 If-Match
+
+ The If-Match request-header field is used with a method to make it
+ conditional. A client that has one or more entities previously
+ obtained from the resource can verify that one of those entities is
+ current by including a list of their associated entity tags in the
+ If-Match header field. Entity tags are defined in section 3.11. The
+ purpose of this feature is to allow efficient updates of cached
+ information with a minimum amount of transaction overhead. It is also
+ used, on updating requests, to prevent inadvertent modification of
+ the wrong version of a resource. As a special case, the value "*"
+ matches any current entity of the resource.
+
+ If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-Match header) on that resource, or if "*" is given
+
+
+
+
+Fielding, et al. Standards Track [Page 129]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ and any current entity exists for that resource, then the server MAY
+ perform the requested method as if the If-Match header field did not
+ exist.
+
+ A server MUST use the strong comparison function (see section 13.3.3)
+ to compare the entity tags in If-Match.
+
+ If none of the entity tags match, or if "*" is given and no current
+ entity exists, the server MUST NOT perform the requested method, and
+ MUST return a 412 (Precondition Failed) response. This behavior is
+ most useful when the client wants to prevent an updating method, such
+ as PUT, from modifying a resource that has changed since the client
+ last retrieved it.
+
+ If the request would, without the If-Match header field, result in
+ anything other than a 2xx or 412 status, then the If-Match header
+ MUST be ignored.
+
+ The meaning of "If-Match: *" is that the method SHOULD be performed
+ if the representation selected by the origin server (or by a cache,
+ possibly using the Vary mechanism, see section 14.44) exists, and
+ MUST NOT be performed if the representation does not exist.
+
+ A request intended to update a resource (e.g., a PUT) MAY include an
+ If-Match header field to signal that the request method MUST NOT be
+ applied if the entity corresponding to the If-Match value (a single
+ entity tag) is no longer a representation of that resource. This
+ allows the user to indicate that they do not wish the request to be
+ successful if the resource has been changed without their knowledge.
+ Examples:
+
+ If-Match: "xyzzy"
+ If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-Match: *
+
+ The result of a request having both an If-Match header field and
+ either an If-None-Match or an If-Modified-Since header fields is
+ undefined by this specification.
+
+14.25 If-Modified-Since
+
+ The If-Modified-Since request-header field is used with a method to
+ make it conditional: if the requested variant has not been modified
+ since the time specified in this field, an entity will not be
+ returned from the server; instead, a 304 (not modified) response will
+ be returned without any message-body.
+
+ If-Modified-Since = "If-Modified-Since" ":" HTTP-date
+
+
+
+Fielding, et al. Standards Track [Page 130]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An example of the field is:
+
+ If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ A GET method with an If-Modified-Since header and no Range header
+ requests that the identified entity be transferred only if it has
+ been modified since the date given by the If-Modified-Since header.
+ The algorithm for determining this includes the following cases:
+
+ a) If the request would normally result in anything other than a
+ 200 (OK) status, or if the passed If-Modified-Since date is
+ invalid, the response is exactly the same as for a normal GET.
+ A date which is later than the server's current time is
+ invalid.
+
+ b) If the variant has been modified since the If-Modified-Since
+ date, the response is exactly the same as for a normal GET.
+
+ c) If the variant has not been modified since a valid If-
+ Modified-Since date, the server SHOULD return a 304 (Not
+ Modified) response.
+
+ The purpose of this feature is to allow efficient updates of cached
+ information with a minimum amount of transaction overhead.
+
+ Note: The Range request-header field modifies the meaning of If-
+ Modified-Since; see section 14.35 for full details.
+
+ Note: If-Modified-Since times are interpreted by the server, whose
+ clock might not be synchronized with the client.
+
+ Note: When handling an If-Modified-Since header field, some
+ servers will use an exact date comparison function, rather than a
+ less-than function, for deciding whether to send a 304 (Not
+ Modified) response. To get best results when sending an If-
+ Modified-Since header field for cache validation, clients are
+ advised to use the exact date string received in a previous Last-
+ Modified header field whenever possible.
+
+ Note: If a client uses an arbitrary date in the If-Modified-Since
+ header instead of a date taken from the Last-Modified header for
+ the same request, the client should be aware of the fact that this
+ date is interpreted in the server's understanding of time. The
+ client should consider unsynchronized clocks and rounding problems
+ due to the different encodings of time between the client and
+ server. This includes the possibility of race conditions if the
+ document has changed between the time it was first requested and
+ the If-Modified-Since date of a subsequent request, and the
+
+
+
+Fielding, et al. Standards Track [Page 131]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ possibility of clock-skew-related problems if the If-Modified-
+ Since date is derived from the client's clock without correction
+ to the server's clock. Corrections for different time bases
+ between client and server are at best approximate due to network
+ latency.
+
+ The result of a request having both an If-Modified-Since header field
+ and either an If-Match or an If-Unmodified-Since header fields is
+ undefined by this specification.
+
+14.26 If-None-Match
+
+ The If-None-Match request-header field is used with a method to make
+ it conditional. A client that has one or more entities previously
+ obtained from the resource can verify that none of those entities is
+ current by including a list of their associated entity tags in the
+ If-None-Match header field. The purpose of this feature is to allow
+ efficient updates of cached information with a minimum amount of
+ transaction overhead. It is also used to prevent a method (e.g. PUT)
+ from inadvertently modifying an existing resource when the client
+ believes that the resource does not exist.
+
+ As a special case, the value "*" matches any current entity of the
+ resource.
+
+ If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-None-Match header) on that resource, or if "*" is
+ given and any current entity exists for that resource, then the
+ server MUST NOT perform the requested method, unless required to do
+ so because the resource's modification date fails to match that
+ supplied in an If-Modified-Since header field in the request.
+ Instead, if the request method was GET or HEAD, the server SHOULD
+ respond with a 304 (Not Modified) response, including the cache-
+ related header fields (particularly ETag) of one of the entities that
+ matched. For all other request methods, the server MUST respond with
+ a status of 412 (Precondition Failed).
+
+ See section 13.3.3 for rules on how to determine if two entities tags
+ match. The weak comparison function can only be used with GET or HEAD
+ requests.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 132]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If none of the entity tags match, then the server MAY perform the
+ requested method as if the If-None-Match header field did not exist,
+ but MUST also ignore any If-Modified-Since header field(s) in the
+ request. That is, if no entity tags match, then the server MUST NOT
+ return a 304 (Not Modified) response.
+
+ If the request would, without the If-None-Match header field, result
+ in anything other than a 2xx or 304 status, then the If-None-Match
+ header MUST be ignored. (See section 13.3.4 for a discussion of
+ server behavior when both If-Modified-Since and If-None-Match appear
+ in the same request.)
+
+ The meaning of "If-None-Match: *" is that the method MUST NOT be
+ performed if the representation selected by the origin server (or by
+ a cache, possibly using the Vary mechanism, see section 14.44)
+ exists, and SHOULD be performed if the representation does not exist.
+ This feature is intended to be useful in preventing races between PUT
+ operations.
+
+ Examples:
+
+ If-None-Match: "xyzzy"
+ If-None-Match: W/"xyzzy"
+ If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+ If-None-Match: *
+
+ The result of a request having both an If-None-Match header field and
+ either an If-Match or an If-Unmodified-Since header fields is
+ undefined by this specification.
+
+14.27 If-Range
+
+ If a client has a partial copy of an entity in its cache, and wishes
+ to have an up-to-date copy of the entire entity in its cache, it
+ could use the Range request-header with a conditional GET (using
+ either or both of If-Unmodified-Since and If-Match.) However, if the
+ condition fails because the entity has been modified, the client
+ would then have to make a second request to obtain the entire current
+ entity-body.
+
+ The If-Range header allows a client to "short-circuit" the second
+ request. Informally, its meaning is `if the entity is unchanged, send
+ me the part(s) that I am missing; otherwise, send me the entire new
+ entity'.
+
+ If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
+
+
+
+
+Fielding, et al. Standards Track [Page 133]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the client has no entity tag for an entity, but does have a Last-
+ Modified date, it MAY use that date in an If-Range header. (The
+ server can distinguish between a valid HTTP-date and any form of
+ entity-tag by examining no more than two characters.) The If-Range
+ header SHOULD only be used together with a Range header, and MUST be
+ ignored if the request does not include a Range header, or if the
+ server does not support the sub-range operation.
+
+ If the entity tag given in the If-Range header matches the current
+ entity tag for the entity, then the server SHOULD provide the
+ specified sub-range of the entity using a 206 (Partial content)
+ response. If the entity tag does not match, then the server SHOULD
+ return the entire entity using a 200 (OK) response.
+
+14.28 If-Unmodified-Since
+
+ The If-Unmodified-Since request-header field is used with a method to
+ make it conditional. If the requested resource has not been modified
+ since the time specified in this field, the server SHOULD perform the
+ requested operation as if the If-Unmodified-Since header were not
+ present.
+
+ If the requested variant has been modified since the specified time,
+ the server MUST NOT perform the requested operation, and MUST return
+ a 412 (Precondition Failed).
+
+ If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
+
+ An example of the field is:
+
+ If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ If the request normally (i.e., without the If-Unmodified-Since
+ header) would result in anything other than a 2xx or 412 status, the
+ If-Unmodified-Since header SHOULD be ignored.
+
+ If the specified date is invalid, the header is ignored.
+
+ The result of a request having both an If-Unmodified-Since header
+ field and either an If-None-Match or an If-Modified-Since header
+ fields is undefined by this specification.
+
+14.29 Last-Modified
+
+ The Last-Modified entity-header field indicates the date and time at
+ which the origin server believes the variant was last modified.
+
+ Last-Modified = "Last-Modified" ":" HTTP-date
+
+
+
+Fielding, et al. Standards Track [Page 134]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An example of its use is
+
+ Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
+
+ The exact meaning of this header field depends on the implementation
+ of the origin server and the nature of the original resource. For
+ files, it may be just the file system last-modified time. For
+ entities with dynamically included parts, it may be the most recent
+ of the set of last-modify times for its component parts. For database
+ gateways, it may be the last-update time stamp of the record. For
+ virtual objects, it may be the last time the internal state changed.
+
+ An origin server MUST NOT send a Last-Modified date which is later
+ than the server's time of message origination. In such cases, where
+ the resource's last modification would indicate some time in the
+ future, the server MUST replace that date with the message
+ origination date.
+
+ An origin server SHOULD obtain the Last-Modified value of the entity
+ as close as possible to the time that it generates the Date value of
+ its response. This allows a recipient to make an accurate assessment
+ of the entity's modification time, especially if the entity changes
+ near the time that the response is generated.
+
+ HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
+
+14.30 Location
+
+ The Location response-header field is used to redirect the recipient
+ to a location other than the Request-URI for completion of the
+ request or identification of a new resource. For 201 (Created)
+ responses, the Location is that of the new resource which was created
+ by the request. For 3xx responses, the location SHOULD indicate the
+ server's preferred URI for automatic redirection to the resource. The
+ field value consists of a single absolute URI.
+
+ Location = "Location" ":" absoluteURI
+
+ An example is:
+
+ Location: http://www.w3.org/pub/WWW/People.html
+
+ Note: The Content-Location header field (section 14.14) differs
+ from Location in that the Content-Location identifies the original
+ location of the entity enclosed in the request. It is therefore
+ possible for a response to contain header fields for both Location
+ and Content-Location. Also see section 13.10 for cache
+ requirements of some methods.
+
+
+
+Fielding, et al. Standards Track [Page 135]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.31 Max-Forwards
+
+ The Max-Forwards request-header field provides a mechanism with the
+ TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the
+ number of proxies or gateways that can forward the request to the
+ next inbound server. This can be useful when the client is attempting
+ to trace a request chain which appears to be failing or looping in
+ mid-chain.
+
+ Max-Forwards = "Max-Forwards" ":" 1*DIGIT
+
+ The Max-Forwards value is a decimal integer indicating the remaining
+ number of times this request message may be forwarded.
+
+ Each proxy or gateway recipient of a TRACE or OPTIONS request
+ containing a Max-Forwards header field MUST check and update its
+ value prior to forwarding the request. If the received value is zero
+ (0), the recipient MUST NOT forward the request; instead, it MUST
+ respond as the final recipient. If the received Max-Forwards value is
+ greater than zero, then the forwarded message MUST contain an updated
+ Max-Forwards field with a value decremented by one (1).
+
+ The Max-Forwards header field MAY be ignored for all other methods
+ defined by this specification and for any extension methods for which
+ it is not explicitly referred to as part of that method definition.
+
+14.32 Pragma
+
+ The Pragma general-header field is used to include implementation-
+ specific directives that might apply to any recipient along the
+ request/response chain. All pragma directives specify optional
+ behavior from the viewpoint of the protocol; however, some systems
+ MAY require that behavior be consistent with the directives.
+
+ Pragma = "Pragma" ":" 1#pragma-directive
+ pragma-directive = "no-cache" | extension-pragma
+ extension-pragma = token [ "=" ( token | quoted-string ) ]
+
+ When the no-cache directive is present in a request message, an
+ application SHOULD forward the request toward the origin server even
+ if it has a cached copy of what is being requested. This pragma
+ directive has the same semantics as the no-cache cache-directive (see
+ section 14.9) and is defined here for backward compatibility with
+ HTTP/1.0. Clients SHOULD include both header fields when a no-cache
+ request is sent to a server not known to be HTTP/1.1 compliant.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 136]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Pragma directives MUST be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives might be applicable to all recipients along the
+ request/response chain. It is not possible to specify a pragma for a
+ specific recipient; however, any pragma directive not relevant to a
+ recipient SHOULD be ignored by that recipient.
+
+ HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had
+ sent "Cache-Control: no-cache". No new Pragma directives will be
+ defined in HTTP.
+
+ Note: because the meaning of "Pragma: no-cache as a response
+ header field is not actually specified, it does not provide a
+ reliable replacement for "Cache-Control: no-cache" in a response
+
+14.33 Proxy-Authenticate
+
+ The Proxy-Authenticate response-header field MUST be included as part
+ of a 407 (Proxy Authentication Required) response. The field value
+ consists of a challenge that indicates the authentication scheme and
+ parameters applicable to the proxy for this Request-URI.
+
+ Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. Unlike
+ WWW-Authenticate, the Proxy-Authenticate header field applies only to
+ the current connection and SHOULD NOT be passed on to downstream
+ clients. However, an intermediate proxy might need to obtain its own
+ credentials by requesting them from the downstream client, which in
+ some circumstances will appear as if the proxy is forwarding the
+ Proxy-Authenticate header field.
+
+14.34 Proxy-Authorization
+
+ The Proxy-Authorization request-header field allows the client to
+ identify itself (or its user) to a proxy which requires
+ authentication. The Proxy-Authorization field value consists of
+ credentials containing the authentication information of the user
+ agent for the proxy and/or realm of the resource being requested.
+
+ Proxy-Authorization = "Proxy-Authorization" ":" credentials
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43] . Unlike
+ Authorization, the Proxy-Authorization header field applies only to
+ the next outbound proxy that demanded authentication using the Proxy-
+ Authenticate field. When multiple proxies are used in a chain, the
+
+
+
+Fielding, et al. Standards Track [Page 137]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Proxy-Authorization header field is consumed by the first outbound
+ proxy that was expecting to receive credentials. A proxy MAY relay
+ the credentials from the client request to the next proxy if that is
+ the mechanism by which the proxies cooperatively authenticate a given
+ request.
+
+14.35 Range
+
+14.35.1 Byte Ranges
+
+ Since all HTTP entities are represented in HTTP messages as sequences
+ of bytes, the concept of a byte range is meaningful for any HTTP
+ entity. (However, not all clients and servers need to support byte-
+ range operations.)
+
+ Byte range specifications in HTTP apply to the sequence of bytes in
+ the entity-body (not necessarily the same as the message-body).
+
+ A byte range operation MAY specify a single range of bytes, or a set
+ of ranges within a single entity.
+
+ ranges-specifier = byte-ranges-specifier
+ byte-ranges-specifier = bytes-unit "=" byte-range-set
+ byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec )
+ byte-range-spec = first-byte-pos "-" [last-byte-pos]
+ first-byte-pos = 1*DIGIT
+ last-byte-pos = 1*DIGIT
+
+ The first-byte-pos value in a byte-range-spec gives the byte-offset
+ of the first byte in a range. The last-byte-pos value gives the
+ byte-offset of the last byte in the range; that is, the byte
+ positions specified are inclusive. Byte offsets start at zero.
+
+ If the last-byte-pos value is present, it MUST be greater than or
+ equal to the first-byte-pos in that byte-range-spec, or the byte-
+ range-spec is syntactically invalid. The recipient of a byte-range-
+ set that includes one or more syntactically invalid byte-range-spec
+ values MUST ignore the header field that includes that byte-range-
+ set.
+
+ If the last-byte-pos value is absent, or if the value is greater than
+ or equal to the current length of the entity-body, last-byte-pos is
+ taken to be equal to one less than the current length of the entity-
+ body in bytes.
+
+ By its choice of last-byte-pos, a client can limit the number of
+ bytes retrieved without knowing the size of the entity.
+
+
+
+
+Fielding, et al. Standards Track [Page 138]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ suffix-byte-range-spec = "-" suffix-length
+ suffix-length = 1*DIGIT
+
+ A suffix-byte-range-spec is used to specify the suffix of the
+ entity-body, of a length given by the suffix-length value. (That is,
+ this form specifies the last N bytes of an entity-body.) If the
+ entity is shorter than the specified suffix-length, the entire
+ entity-body is used.
+
+ If a syntactically valid byte-range-set includes at least one byte-
+ range-spec whose first-byte-pos is less than the current length of
+ the entity-body, or at least one suffix-byte-range-spec with a non-
+ zero suffix-length, then the byte-range-set is satisfiable.
+ Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set
+ is unsatisfiable, the server SHOULD return a response with a status
+ of 416 (Requested range not satisfiable). Otherwise, the server
+ SHOULD return a response with a status of 206 (Partial Content)
+ containing the satisfiable ranges of the entity-body.
+
+ Examples of byte-ranges-specifier values (assuming an entity-body of
+ length 10000):
+
+ - The first 500 bytes (byte offsets 0-499, inclusive): bytes=0-
+ 499
+
+ - The second 500 bytes (byte offsets 500-999, inclusive):
+ bytes=500-999
+
+ - The final 500 bytes (byte offsets 9500-9999, inclusive):
+ bytes=-500
+
+ - Or bytes=9500-
+
+ - The first and last bytes only (bytes 0 and 9999): bytes=0-0,-1
+
+ - Several legal but not canonical specifications of the second 500
+ bytes (byte offsets 500-999, inclusive):
+ bytes=500-600,601-999
+ bytes=500-700,601-999
+
+14.35.2 Range Retrieval Requests
+
+ HTTP retrieval requests using conditional or unconditional GET
+ methods MAY request one or more sub-ranges of the entity, instead of
+ the entire entity, using the Range request header, which applies to
+ the entity returned as the result of the request:
+
+ Range = "Range" ":" ranges-specifier
+
+
+
+Fielding, et al. Standards Track [Page 139]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A server MAY ignore the Range header. However, HTTP/1.1 origin
+ servers and intermediate caches ought to support byte ranges when
+ possible, since Range supports efficient recovery from partially
+ failed transfers, and supports efficient partial retrieval of large
+ entities.
+
+ If the server supports the Range header and the specified range or
+ ranges are appropriate for the entity:
+
+ - The presence of a Range header in an unconditional GET modifies
+ what is returned if the GET is otherwise successful. In other
+ words, the response carries a status code of 206 (Partial
+ Content) instead of 200 (OK).
+
+ - The presence of a Range header in a conditional GET (a request
+ using one or both of If-Modified-Since and If-None-Match, or
+ one or both of If-Unmodified-Since and If-Match) modifies what
+ is returned if the GET is otherwise successful and the
+ condition is true. It does not affect the 304 (Not Modified)
+ response returned if the conditional is false.
+
+ In some cases, it might be more appropriate to use the If-Range
+ header (see section 14.27) in addition to the Range header.
+
+ If a proxy that supports ranges receives a Range request, forwards
+ the request to an inbound server, and receives an entire entity in
+ reply, it SHOULD only return the requested range to its client. It
+ SHOULD store the entire received response in its cache if that is
+ consistent with its cache allocation policies.
+
+14.36 Referer
+
+ The Referer[sic] request-header field allows the client to specify,
+ for the server's benefit, the address (URI) of the resource from
+ which the Request-URI was obtained (the "referrer", although the
+ header field is misspelled.) The Referer request-header allows a
+ server to generate lists of back-links to resources for interest,
+ logging, optimized caching, etc. It also allows obsolete or mistyped
+ links to be traced for maintenance. The Referer field MUST NOT be
+ sent if the Request-URI was obtained from a source that does not have
+ its own URI, such as input from the user keyboard.
+
+ Referer = "Referer" ":" ( absoluteURI | relativeURI )
+
+ Example:
+
+ Referer: http://www.w3.org/hypertext/DataSources/Overview.html
+
+
+
+
+Fielding, et al. Standards Track [Page 140]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the field value is a relative URI, it SHOULD be interpreted
+ relative to the Request-URI. The URI MUST NOT include a fragment. See
+ section 15.1.3 for security considerations.
+
+14.37 Retry-After
+
+ The Retry-After response-header field can be used with a 503 (Service
+ Unavailable) response to indicate how long the service is expected to
+ be unavailable to the requesting client. This field MAY also be used
+ with any 3xx (Redirection) response to indicate the minimum time the
+ user-agent is asked wait before issuing the redirected request. The
+ value of this field can be either an HTTP-date or an integer number
+ of seconds (in decimal) after the time of the response.
+
+ Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds )
+
+ Two examples of its use are
+
+ Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
+ Retry-After: 120
+
+ In the latter example, the delay is 2 minutes.
+
+14.38 Server
+
+ The Server response-header field contains information about the
+ software used by the origin server to handle the request. The field
+ can contain multiple product tokens (section 3.8) and comments
+ identifying the server and any significant subproducts. The product
+ tokens are listed in order of their significance for identifying the
+ application.
+
+ Server = "Server" ":" 1*( product | comment )
+
+ Example:
+
+ Server: CERN/3.0 libwww/2.17
+
+ If the response is being forwarded through a proxy, the proxy
+ application MUST NOT modify the Server response-header. Instead, it
+ SHOULD include a Via field (as described in section 14.45).
+
+ Note: Revealing the specific software version of the server might
+ allow the server machine to become more vulnerable to attacks
+ against software that is known to contain security holes. Server
+ implementors are encouraged to make this field a configurable
+ option.
+
+
+
+
+Fielding, et al. Standards Track [Page 141]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.39 TE
+
+ The TE request-header field indicates what extension transfer-codings
+ it is willing to accept in the response and whether or not it is
+ willing to accept trailer fields in a chunked transfer-coding. Its
+ value may consist of the keyword "trailers" and/or a comma-separated
+ list of extension transfer-coding names with optional accept
+ parameters (as described in section 3.6).
+
+ TE = "TE" ":" #( t-codings )
+ t-codings = "trailers" | ( transfer-extension [ accept-params ] )
+
+ The presence of the keyword "trailers" indicates that the client is
+ willing to accept trailer fields in a chunked transfer-coding, as
+ defined in section 3.6.1. This keyword is reserved for use with
+ transfer-coding values even though it does not itself represent a
+ transfer-coding.
+
+ Examples of its use are:
+
+ TE: deflate
+ TE:
+ TE: trailers, deflate;q=0.5
+
+ The TE header field only applies to the immediate connection.
+ Therefore, the keyword MUST be supplied within a Connection header
+ field (section 14.10) whenever TE is present in an HTTP/1.1 message.
+
+ A server tests whether a transfer-coding is acceptable, according to
+ a TE field, using these rules:
+
+ 1. The "chunked" transfer-coding is always acceptable. If the
+ keyword "trailers" is listed, the client indicates that it is
+ willing to accept trailer fields in the chunked response on
+ behalf of itself and any downstream clients. The implication is
+ that, if given, the client is stating that either all
+ downstream clients are willing to accept trailer fields in the
+ forwarded response, or that it will attempt to buffer the
+ response on behalf of downstream recipients.
+
+ Note: HTTP/1.1 does not define any means to limit the size of a
+ chunked response such that a client can be assured of buffering
+ the entire response.
+
+ 2. If the transfer-coding being tested is one of the transfer-
+ codings listed in the TE field, then it is acceptable unless it
+ is accompanied by a qvalue of 0. (As defined in section 3.9, a
+ qvalue of 0 means "not acceptable.")
+
+
+
+Fielding, et al. Standards Track [Page 142]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 3. If multiple transfer-codings are acceptable, then the
+ acceptable transfer-coding with the highest non-zero qvalue is
+ preferred. The "chunked" transfer-coding always has a qvalue
+ of 1.
+
+ If the TE field-value is empty or if no TE field is present, the only
+ transfer-coding is "chunked". A message with no transfer-coding is
+ always acceptable.
+
+14.40 Trailer
+
+ The Trailer general field value indicates that the given set of
+ header fields is present in the trailer of a message encoded with
+ chunked transfer-coding.
+
+ Trailer = "Trailer" ":" 1#field-name
+
+ An HTTP/1.1 message SHOULD include a Trailer header field in a
+ message using chunked transfer-coding with a non-empty trailer. Doing
+ so allows the recipient to know which header fields to expect in the
+ trailer.
+
+ If no Trailer header field is present, the trailer SHOULD NOT include
+ any header fields. See section 3.6.1 for restrictions on the use of
+ trailer fields in a "chunked" transfer-coding.
+
+ Message header fields listed in the Trailer header field MUST NOT
+ include the following header fields:
+
+ . Transfer-Encoding
+
+ . Content-Length
+
+ . Trailer
+
+14.41 Transfer-Encoding
+
+ The Transfer-Encoding general-header field indicates what (if any)
+ type of transformation has been applied to the message body in order
+ to safely transfer it between the sender and the recipient. This
+ differs from the content-coding in that the transfer-coding is a
+ property of the message, not of the entity.
+
+ Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding
+
+ Transfer-codings are defined in section 3.6. An example is:
+
+ Transfer-Encoding: chunked
+
+
+
+Fielding, et al. Standards Track [Page 143]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If multiple encodings have been applied to an entity, the transfer-
+ codings MUST be listed in the order in which they were applied.
+ Additional information about the encoding parameters MAY be provided
+ by other entity-header fields not defined by this specification.
+
+ Many older HTTP/1.0 applications do not understand the Transfer-
+ Encoding header.
+
+14.42 Upgrade
+
+ The Upgrade general-header allows the client to specify what
+ additional communication protocols it supports and would like to use
+ if the server finds it appropriate to switch protocols. The server
+ MUST use the Upgrade header field within a 101 (Switching Protocols)
+ response to indicate which protocol(s) are being switched.
+
+ Upgrade = "Upgrade" ":" 1#product
+
+ For example,
+
+ Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
+
+ The Upgrade header field is intended to provide a simple mechanism
+ for transition from HTTP/1.1 to some other, incompatible protocol. It
+ does so by allowing the client to advertise its desire to use another
+ protocol, such as a later version of HTTP with a higher major version
+ number, even though the current request has been made using HTTP/1.1.
+ This eases the difficult transition between incompatible protocols by
+ allowing the client to initiate a request in the more commonly
+ supported protocol while indicating to the server that it would like
+ to use a "better" protocol if available (where "better" is determined
+ by the server, possibly according to the nature of the method and/or
+ resource being requested).
+
+ The Upgrade header field only applies to switching application-layer
+ protocols upon the existing transport-layer connection. Upgrade
+ cannot be used to insist on a protocol change; its acceptance and use
+ by the server is optional. The capabilities and nature of the
+ application-layer communication after the protocol change is entirely
+ dependent upon the new protocol chosen, although the first action
+ after changing the protocol MUST be a response to the initial HTTP
+ request containing the Upgrade header field.
+
+ The Upgrade header field only applies to the immediate connection.
+ Therefore, the upgrade keyword MUST be supplied within a Connection
+ header field (section 14.10) whenever Upgrade is present in an
+ HTTP/1.1 message.
+
+
+
+
+Fielding, et al. Standards Track [Page 144]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Upgrade header field cannot be used to indicate a switch to a
+ protocol on a different connection. For that purpose, it is more
+ appropriate to use a 301, 302, 303, or 305 redirection response.
+
+ This specification only defines the protocol name "HTTP" for use by
+ the family of Hypertext Transfer Protocols, as defined by the HTTP
+ version rules of section 3.1 and future updates to this
+ specification. Any token can be used as a protocol name; however, it
+ will only be useful if both the client and server associate the name
+ with the same protocol.
+
+14.43 User-Agent
+
+ The User-Agent request-header field contains information about the
+ user agent originating the request. This is for statistical purposes,
+ the tracing of protocol violations, and automated recognition of user
+ agents for the sake of tailoring responses to avoid particular user
+ agent limitations. User agents SHOULD include this field with
+ requests. The field can contain multiple product tokens (section 3.8)
+ and comments identifying the agent and any subproducts which form a
+ significant part of the user agent. By convention, the product tokens
+ are listed in order of their significance for identifying the
+ application.
+
+ User-Agent = "User-Agent" ":" 1*( product | comment )
+
+ Example:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+
+14.44 Vary
+
+ The Vary field value indicates the set of request-header fields that
+ fully determines, while the response is fresh, whether a cache is
+ permitted to use the response to reply to a subsequent request
+ without revalidation. For uncacheable or stale responses, the Vary
+ field value advises the user agent about the criteria that were used
+ to select the representation. A Vary field value of "*" implies that
+ a cache cannot determine from the request headers of a subsequent
+ request whether this response is the appropriate representation. See
+ section 13.6 for use of the Vary header field by caches.
+
+ Vary = "Vary" ":" ( "*" | 1#field-name )
+
+ An HTTP/1.1 server SHOULD include a Vary header field with any
+ cacheable response that is subject to server-driven negotiation.
+ Doing so allows a cache to properly interpret future requests on that
+ resource and informs the user agent about the presence of negotiation
+
+
+
+Fielding, et al. Standards Track [Page 145]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ on that resource. A server MAY include a Vary header field with a
+ non-cacheable response that is subject to server-driven negotiation,
+ since this might provide the user agent with useful information about
+ the dimensions over which the response varies at the time of the
+ response.
+
+ A Vary field value consisting of a list of field-names signals that
+ the representation selected for the response is based on a selection
+ algorithm which considers ONLY the listed request-header field values
+ in selecting the most appropriate representation. A cache MAY assume
+ that the same selection will be made for future requests with the
+ same values for the listed field names, for the duration of time for
+ which the response is fresh.
+
+ The field-names given are not limited to the set of standard
+ request-header fields defined by this specification. Field names are
+ case-insensitive.
+
+ A Vary field value of "*" signals that unspecified parameters not
+ limited to the request-headers (e.g., the network address of the
+ client), play a role in the selection of the response representation.
+ The "*" value MUST NOT be generated by a proxy server; it may only be
+ generated by an origin server.
+
+14.45 Via
+
+ The Via general-header field MUST be used by gateways and proxies to
+ indicate the intermediate protocols and recipients between the user
+ agent and the server on requests, and between the origin server and
+ the client on responses. It is analogous to the "Received" field of
+ RFC 822 [9] and is intended to be used for tracking message forwards,
+ avoiding request loops, and identifying the protocol capabilities of
+ all senders along the request/response chain.
+
+ Via = "Via" ":" 1#( received-protocol received-by [ comment ] )
+ received-protocol = [ protocol-name "/" ] protocol-version
+ protocol-name = token
+ protocol-version = token
+ received-by = ( host [ ":" port ] ) | pseudonym
+ pseudonym = token
+
+ The received-protocol indicates the protocol version of the message
+ received by the server or client along each segment of the
+ request/response chain. The received-protocol version is appended to
+ the Via field value when the message is forwarded so that information
+ about the protocol capabilities of upstream applications remains
+ visible to all recipients.
+
+
+
+
+Fielding, et al. Standards Track [Page 146]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The protocol-name is optional if and only if it would be "HTTP". The
+ received-by field is normally the host and optional port number of a
+ recipient server or client that subsequently forwarded the message.
+ However, if the real host is considered to be sensitive information,
+ it MAY be replaced by a pseudonym. If the port is not given, it MAY
+ be assumed to be the default port of the received-protocol.
+
+ Multiple Via field values represents each proxy or gateway that has
+ forwarded the message. Each recipient MUST append its information
+ such that the end result is ordered according to the sequence of
+ forwarding applications.
+
+ Comments MAY be used in the Via header field to identify the software
+ of the recipient proxy or gateway, analogous to the User-Agent and
+ Server header fields. However, all comments in the Via field are
+ optional and MAY be removed by any recipient prior to forwarding the
+ message.
+
+ For example, a request message could be sent from an HTTP/1.0 user
+ agent to an internal proxy code-named "fred", which uses HTTP/1.1 to
+ forward the request to a public proxy at nowhere.com, which completes
+ the request by forwarding it to the origin server at www.ics.uci.edu.
+ The request received by www.ics.uci.edu would then have the following
+ Via header field:
+
+ Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
+
+ Proxies and gateways used as a portal through a network firewall
+ SHOULD NOT, by default, forward the names and ports of hosts within
+ the firewall region. This information SHOULD only be propagated if
+ explicitly enabled. If not enabled, the received-by host of any host
+ behind the firewall SHOULD be replaced by an appropriate pseudonym
+ for that host.
+
+ For organizations that have strong privacy requirements for hiding
+ internal structures, a proxy MAY combine an ordered subsequence of
+ Via header field entries with identical received-protocol values into
+ a single such entry. For example,
+
+ Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
+
+ could be collapsed to
+
+ Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 147]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Applications SHOULD NOT combine multiple entries unless they are all
+ under the same organizational control and the hosts have already been
+ replaced by pseudonyms. Applications MUST NOT combine entries which
+ have different received-protocol values.
+
+14.46 Warning
+
+ The Warning general-header field is used to carry additional
+ information about the status or transformation of a message which
+ might not be reflected in the message. This information is typically
+ used to warn about a possible lack of semantic transparency from
+ caching operations or transformations applied to the entity body of
+ the message.
+
+ Warning headers are sent with responses using:
+
+ Warning = "Warning" ":" 1#warning-value
+
+ warning-value = warn-code SP warn-agent SP warn-text
+ [SP warn-date]
+
+ warn-code = 3DIGIT
+ warn-agent = ( host [ ":" port ] ) | pseudonym
+ ; the name or pseudonym of the server adding
+ ; the Warning header, for use in debugging
+ warn-text = quoted-string
+ warn-date = <"> HTTP-date <">
+
+ A response MAY carry more than one Warning header.
+
+ The warn-text SHOULD be in a natural language and character set that
+ is most likely to be intelligible to the human user receiving the
+ response. This decision MAY be based on any available knowledge, such
+ as the location of the cache or user, the Accept-Language field in a
+ request, the Content-Language field in a response, etc. The default
+ language is English and the default character set is ISO-8859-1.
+
+ If a character set other than ISO-8859-1 is used, it MUST be encoded
+ in the warn-text using the method described in RFC 2047 [14].
+
+ Warning headers can in general be applied to any message, however
+ some specific warn-codes are specific to caches and can only be
+ applied to response messages. New Warning headers SHOULD be added
+ after any existing Warning headers. A cache MUST NOT delete any
+ Warning header that it received with a message. However, if a cache
+ successfully validates a cache entry, it SHOULD remove any Warning
+ headers previously attached to that entry except as specified for
+
+
+
+
+Fielding, et al. Standards Track [Page 148]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ specific Warning codes. It MUST then add any Warning headers received
+ in the validating response. In other words, Warning headers are those
+ that would be attached to the most recent relevant response.
+
+ When multiple Warning headers are attached to a response, the user
+ agent ought to inform the user of as many of them as possible, in the
+ order that they appear in the response. If it is not possible to
+ inform the user of all of the warnings, the user agent SHOULD follow
+ these heuristics:
+
+ - Warnings that appear early in the response take priority over
+ those appearing later in the response.
+
+ - Warnings in the user's preferred character set take priority
+ over warnings in other character sets but with identical warn-
+ codes and warn-agents.
+
+ Systems that generate multiple Warning headers SHOULD order them with
+ this user agent behavior in mind.
+
+ Requirements for the behavior of caches with respect to Warnings are
+ stated in section 13.1.2.
+
+ This is a list of the currently-defined warn-codes, each with a
+ recommended warn-text in English, and a description of its meaning.
+
+ 110 Response is stale
+ MUST be included whenever the returned response is stale.
+
+ 111 Revalidation failed
+ MUST be included if a cache returns a stale response because an
+ attempt to revalidate the response failed, due to an inability to
+ reach the server.
+
+ 112 Disconnected operation
+ SHOULD be included if the cache is intentionally disconnected from
+ the rest of the network for a period of time.
+
+ 113 Heuristic expiration
+ MUST be included if the cache heuristically chose a freshness
+ lifetime greater than 24 hours and the response's age is greater
+ than 24 hours.
+
+ 199 Miscellaneous warning
+ The warning text MAY include arbitrary information to be presented
+ to a human user, or logged. A system receiving this warning MUST
+ NOT take any automated action, besides presenting the warning to
+ the user.
+
+
+
+Fielding, et al. Standards Track [Page 149]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 214 Transformation applied
+ MUST be added by an intermediate cache or proxy if it applies any
+ transformation changing the content-coding (as specified in the
+ Content-Encoding header) or media-type (as specified in the
+ Content-Type header) of the response, or the entity-body of the
+ response, unless this Warning code already appears in the response.
+
+ 299 Miscellaneous persistent warning
+ The warning text MAY include arbitrary information to be presented
+ to a human user, or logged. A system receiving this warning MUST
+ NOT take any automated action.
+
+ If an implementation sends a message with one or more Warning headers
+ whose version is HTTP/1.0 or lower, then the sender MUST include in
+ each warning-value a warn-date that matches the date in the response.
+
+ If an implementation receives a message with a warning-value that
+ includes a warn-date, and that warn-date is different from the Date
+ value in the response, then that warning-value MUST be deleted from
+ the message before storing, forwarding, or using it. (This prevents
+ bad consequences of naive caching of Warning header fields.) If all
+ of the warning-values are deleted for this reason, the Warning header
+ MUST be deleted as well.
+
+14.47 WWW-Authenticate
+
+ The WWW-Authenticate response-header field MUST be included in 401
+ (Unauthorized) response messages. The field value consists of at
+ least one challenge that indicates the authentication scheme(s) and
+ parameters applicable to the Request-URI.
+
+ WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. User
+ agents are advised to take special care in parsing the WWW-
+ Authenticate field value as it might contain more than one challenge,
+ or if more than one WWW-Authenticate header field is provided, the
+ contents of a challenge itself can contain a comma-separated list of
+ authentication parameters.
+
+15 Security Considerations
+
+ This section is meant to inform application developers, information
+ providers, and users of the security limitations in HTTP/1.1 as
+ described by this document. The discussion does not include
+ definitive solutions to the problems revealed, though it does make
+ some suggestions for reducing security risks.
+
+
+
+Fielding, et al. Standards Track [Page 150]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.1 Personal Information
+
+ HTTP clients are often privy to large amounts of personal information
+ (e.g. the user's name, location, mail address, passwords, encryption
+ keys, etc.), and SHOULD be very careful to prevent unintentional
+ leakage of this information via the HTTP protocol to other sources.
+ We very strongly recommend that a convenient interface be provided
+ for the user to control dissemination of such information, and that
+ designers and implementors be particularly careful in this area.
+ History shows that errors in this area often create serious security
+ and/or privacy problems and generate highly adverse publicity for the
+ implementor's company.
+
+15.1.1 Abuse of Server Log Information
+
+ A server is in the position to save personal data about a user's
+ requests which might identify their reading patterns or subjects of
+ interest. This information is clearly confidential in nature and its
+ handling can be constrained by law in certain countries. People using
+ the HTTP protocol to provide data are responsible for ensuring that
+ such material is not distributed without the permission of any
+ individuals that are identifiable by the published results.
+
+15.1.2 Transfer of Sensitive Information
+
+ Like any generic data transfer protocol, HTTP cannot regulate the
+ content of the data that is transferred, nor is there any a priori
+ method of determining the sensitivity of any particular piece of
+ information within the context of any given request. Therefore,
+ applications SHOULD supply as much control over this information as
+ possible to the provider of that information. Four header fields are
+ worth special mention in this context: Server, Via, Referer and From.
+
+ Revealing the specific software version of the server might allow the
+ server machine to become more vulnerable to attacks against software
+ that is known to contain security holes. Implementors SHOULD make the
+ Server header field a configurable option.
+
+ Proxies which serve as a portal through a network firewall SHOULD
+ take special precautions regarding the transfer of header information
+ that identifies the hosts behind the firewall. In particular, they
+ SHOULD remove, or replace with sanitized versions, any Via fields
+ generated behind the firewall.
+
+ The Referer header allows reading patterns to be studied and reverse
+ links drawn. Although it can be very useful, its power can be abused
+ if user details are not separated from the information contained in
+
+
+
+
+Fielding, et al. Standards Track [Page 151]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the Referer. Even when the personal information has been removed, the
+ Referer header might indicate a private document's URI whose
+ publication would be inappropriate.
+
+ The information sent in the From field might conflict with the user's
+ privacy interests or their site's security policy, and hence it
+ SHOULD NOT be transmitted without the user being able to disable,
+ enable, and modify the contents of the field. The user MUST be able
+ to set the contents of this field within a user preference or
+ application defaults configuration.
+
+ We suggest, though do not require, that a convenient toggle interface
+ be provided for the user to enable or disable the sending of From and
+ Referer information.
+
+ The User-Agent (section 14.43) or Server (section 14.38) header
+ fields can sometimes be used to determine that a specific client or
+ server have a particular security hole which might be exploited.
+ Unfortunately, this same information is often used for other valuable
+ purposes for which HTTP currently has no better mechanism.
+
+15.1.3 Encoding Sensitive Information in URI's
+
+ Because the source of a link might be private information or might
+ reveal an otherwise private information source, it is strongly
+ recommended that the user be able to select whether or not the
+ Referer field is sent. For example, a browser client could have a
+ toggle switch for browsing openly/anonymously, which would
+ respectively enable/disable the sending of Referer and From
+ information.
+
+ Clients SHOULD NOT include a Referer header field in a (non-secure)
+ HTTP request if the referring page was transferred with a secure
+ protocol.
+
+ Authors of services which use the HTTP protocol SHOULD NOT use GET
+ based forms for the submission of sensitive data, because this will
+ cause this data to be encoded in the Request-URI. Many existing
+ servers, proxies, and user agents will log the request URI in some
+ place where it might be visible to third parties. Servers can use
+ POST-based form submission instead
+
+15.1.4 Privacy Issues Connected to Accept Headers
+
+ Accept request-headers can reveal information about the user to all
+ servers which are accessed. The Accept-Language header in particular
+ can reveal information the user would consider to be of a private
+ nature, because the understanding of particular languages is often
+
+
+
+Fielding, et al. Standards Track [Page 152]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ strongly correlated to the membership of a particular ethnic group.
+ User agents which offer the option to configure the contents of an
+ Accept-Language header to be sent in every request are strongly
+ encouraged to let the configuration process include a message which
+ makes the user aware of the loss of privacy involved.
+
+ An approach that limits the loss of privacy would be for a user agent
+ to omit the sending of Accept-Language headers by default, and to ask
+ the user whether or not to start sending Accept-Language headers to a
+ server if it detects, by looking for any Vary response-header fields
+ generated by the server, that such sending could improve the quality
+ of service.
+
+ Elaborate user-customized accept header fields sent in every request,
+ in particular if these include quality values, can be used by servers
+ as relatively reliable and long-lived user identifiers. Such user
+ identifiers would allow content providers to do click-trail tracking,
+ and would allow collaborating content providers to match cross-server
+ click-trails or form submissions of individual users. Note that for
+ many users not behind a proxy, the network address of the host
+ running the user agent will also serve as a long-lived user
+ identifier. In environments where proxies are used to enhance
+ privacy, user agents ought to be conservative in offering accept
+ header configuration options to end users. As an extreme privacy
+ measure, proxies could filter the accept headers in relayed requests.
+ General purpose user agents which provide a high degree of header
+ configurability SHOULD warn users about the loss of privacy which can
+ be involved.
+
+15.2 Attacks Based On File and Path Names
+
+ Implementations of HTTP origin servers SHOULD be careful to restrict
+ the documents returned by HTTP requests to be only those that were
+ intended by the server administrators. If an HTTP server translates
+ HTTP URIs directly into file system calls, the server MUST take
+ special care not to serve files that were not intended to be
+ delivered to HTTP clients. For example, UNIX, Microsoft Windows, and
+ other operating systems use ".." as a path component to indicate a
+ directory level above the current one. On such a system, an HTTP
+ server MUST disallow any such construct in the Request-URI if it
+ would otherwise allow access to a resource outside those intended to
+ be accessible via the HTTP server. Similarly, files intended for
+ reference only internally to the server (such as access control
+ files, configuration files, and script code) MUST be protected from
+ inappropriate retrieval, since they might contain sensitive
+ information. Experience has shown that minor bugs in such HTTP server
+ implementations have turned into security risks.
+
+
+
+
+Fielding, et al. Standards Track [Page 153]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.3 DNS Spoofing
+
+ Clients using HTTP rely heavily on the Domain Name Service, and are
+ thus generally prone to security attacks based on the deliberate
+ mis-association of IP addresses and DNS names. Clients need to be
+ cautious in assuming the continuing validity of an IP number/DNS name
+ association.
+
+ In particular, HTTP clients SHOULD rely on their name resolver for
+ confirmation of an IP number/DNS name association, rather than
+ caching the result of previous host name lookups. Many platforms
+ already can cache host name lookups locally when appropriate, and
+ they SHOULD be configured to do so. It is proper for these lookups to
+ be cached, however, only when the TTL (Time To Live) information
+ reported by the name server makes it likely that the cached
+ information will remain useful.
+
+ If HTTP clients cache the results of host name lookups in order to
+ achieve a performance improvement, they MUST observe the TTL
+ information reported by DNS.
+
+ If HTTP clients do not observe this rule, they could be spoofed when
+ a previously-accessed server's IP address changes. As network
+ renumbering is expected to become increasingly common [24], the
+ possibility of this form of attack will grow. Observing this
+ requirement thus reduces this potential security vulnerability.
+
+ This requirement also improves the load-balancing behavior of clients
+ for replicated servers using the same DNS name and reduces the
+ likelihood of a user's experiencing failure in accessing sites which
+ use that strategy.
+
+15.4 Location Headers and Spoofing
+
+ If a single server supports multiple organizations that do not trust
+ one another, then it MUST check the values of Location and Content-
+ Location headers in responses that are generated under control of
+ said organizations to make sure that they do not attempt to
+ invalidate resources over which they have no authority.
+
+15.5 Content-Disposition Issues
+
+ RFC 1806 [35], from which the often implemented Content-Disposition
+ (see section 19.5.1) header in HTTP is derived, has a number of very
+ serious security considerations. Content-Disposition is not part of
+ the HTTP standard, but since it is widely implemented, we are
+ documenting its use and risks for implementors. See RFC 2183 [49]
+ (which updates RFC 1806) for details.
+
+
+
+Fielding, et al. Standards Track [Page 154]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.6 Authentication Credentials and Idle Clients
+
+ Existing HTTP clients and user agents typically retain authentication
+ information indefinitely. HTTP/1.1. does not provide a method for a
+ server to direct clients to discard these cached credentials. This is
+ a significant defect that requires further extensions to HTTP.
+ Circumstances under which credential caching can interfere with the
+ application's security model include but are not limited to:
+
+ - Clients which have been idle for an extended period following
+ which the server might wish to cause the client to reprompt the
+ user for credentials.
+
+ - Applications which include a session termination indication
+ (such as a `logout' or `commit' button on a page) after which
+ the server side of the application `knows' that there is no
+ further reason for the client to retain the credentials.
+
+ This is currently under separate study. There are a number of work-
+ arounds to parts of this problem, and we encourage the use of
+ password protection in screen savers, idle time-outs, and other
+ methods which mitigate the security problems inherent in this
+ problem. In particular, user agents which cache credentials are
+ encouraged to provide a readily accessible mechanism for discarding
+ cached credentials under user control.
+
+15.7 Proxies and Caching
+
+ By their very nature, HTTP proxies are men-in-the-middle, and
+ represent an opportunity for man-in-the-middle attacks. Compromise of
+ the systems on which the proxies run can result in serious security
+ and privacy problems. Proxies have access to security-related
+ information, personal information about individual users and
+ organizations, and proprietary information belonging to users and
+ content providers. A compromised proxy, or a proxy implemented or
+ configured without regard to security and privacy considerations,
+ might be used in the commission of a wide range of potential attacks.
+
+ Proxy operators should protect the systems on which proxies run as
+ they would protect any system that contains or transports sensitive
+ information. In particular, log information gathered at proxies often
+ contains highly sensitive personal information, and/or information
+ about organizations. Log information should be carefully guarded, and
+ appropriate guidelines for use developed and followed. (Section
+ 15.1.1).
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 155]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Caching proxies provide additional potential vulnerabilities, since
+ the contents of the cache represent an attractive target for
+ malicious exploitation. Because cache contents persist after an HTTP
+ request is complete, an attack on the cache can reveal information
+ long after a user believes that the information has been removed from
+ the network. Therefore, cache contents should be protected as
+ sensitive information.
+
+ Proxy implementors should consider the privacy and security
+ implications of their design and coding decisions, and of the
+ configuration options they provide to proxy operators (especially the
+ default configuration).
+
+ Users of a proxy need to be aware that they are no trustworthier than
+ the people who run the proxy; HTTP itself cannot solve this problem.
+
+ The judicious use of cryptography, when appropriate, may suffice to
+ protect against a broad range of security and privacy attacks. Such
+ cryptography is beyond the scope of the HTTP/1.1 specification.
+
+15.7.1 Denial of Service Attacks on Proxies
+
+ They exist. They are hard to defend against. Research continues.
+ Beware.
+
+16 Acknowledgments
+
+ This specification makes heavy use of the augmented BNF and generic
+ constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it
+ reuses many of the definitions provided by Nathaniel Borenstein and
+ Ned Freed for MIME [7]. We hope that their inclusion in this
+ specification will help reduce past confusion over the relationship
+ between HTTP and Internet mail message formats.
+
+ The HTTP protocol has evolved considerably over the years. It has
+ benefited from a large and active developer community--the many
+ people who have participated on the www-talk mailing list--and it is
+ that community which has been most responsible for the success of
+ HTTP and of the World-Wide Web in general. Marc Andreessen, Robert
+ Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois
+ Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob
+ McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc
+ VanHeyningen deserve special recognition for their efforts in
+ defining early aspects of the protocol.
+
+ This document has benefited greatly from the comments of all those
+ participating in the HTTP-WG. In addition to those already mentioned,
+ the following individuals have contributed to this specification:
+
+
+
+Fielding, et al. Standards Track [Page 156]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Gary Adams Ross Patterson
+ Harald Tveit Alvestrand Albert Lunde
+ Keith Ball John C. Mallery
+ Brian Behlendorf Jean-Philippe Martin-Flatin
+ Paul Burchard Mitra
+ Maurizio Codogno David Morris
+ Mike Cowlishaw Gavin Nicol
+ Roman Czyborra Bill Perry
+ Michael A. Dolan Jeffrey Perry
+ David J. Fiander Scott Powers
+ Alan Freier Owen Rees
+ Marc Hedlund Luigi Rizzo
+ Greg Herlihy David Robinson
+ Koen Holtman Marc Salomon
+ Alex Hopmann Rich Salz
+ Bob Jernigan Allan M. Schiffman
+ Shel Kaphan Jim Seidman
+ Rohit Khare Chuck Shotton
+ John Klensin Eric W. Sink
+ Martijn Koster Simon E. Spero
+ Alexei Kosut Richard N. Taylor
+ David M. Kristol Robert S. Thau
+ Daniel LaLiberte Bill (BearHeart) Weinman
+ Ben Laurie Francois Yergeau
+ Paul J. Leach Mary Ellen Zurko
+ Daniel DuBois Josh Cohen
+
+
+ Much of the content and presentation of the caching design is due to
+ suggestions and comments from individuals including: Shel Kaphan,
+ Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
+
+ Most of the specification of ranges is based on work originally done
+ by Ari Luotonen and John Franks, with additional input from Steve
+ Zilles.
+
+ Thanks to the "cave men" of Palo Alto. You know who you are.
+
+ Jim Gettys (the current editor of this document) wishes particularly
+ to thank Roy Fielding, the previous editor of this document, along
+ with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen
+ Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and
+ Larry Masinter for their help. And thanks go particularly to Jeff
+ Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 157]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik
+ Frystyk implemented RFC 2068 early, and we wish to thank them for the
+ discovery of many of the problems that this document attempts to
+ rectify.
+
+17 References
+
+ [1] Alvestrand, H., "Tags for the Identification of Languages", RFC
+ 1766, March 1995.
+
+ [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey,
+ D. and B. Alberti, "The Internet Gopher Protocol (a distributed
+ document search and retrieval protocol)", RFC 1436, March 1993.
+
+ [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", RFC
+ 1630, June 1994.
+
+ [4] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
+ Locators (URL)", RFC 1738, December 1994.
+
+ [5] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language -
+ 2.0", RFC 1866, November 1995.
+
+ [6] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer
+ Protocol -- HTTP/1.0", RFC 1945, May 1996.
+
+ [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message Bodies",
+ RFC 2045, November 1996.
+
+ [8] Braden, R., "Requirements for Internet Hosts -- Communication
+ Layers", STD 3, RFC 1123, October 1989.
+
+ [9] Crocker, D., "Standard for The Format of ARPA Internet Text
+ Messages", STD 11, RFC 822, August 1982.
+
+ [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R.,
+ Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype
+ Functional Specification," (v1.5), Thinking Machines
+ Corporation, April 1990.
+
+ [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808,
+ June 1995.
+
+ [12] Horton, M. and R. Adams, "Standard for Interchange of USENET
+ Messages", RFC 1036, December 1987.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 158]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [13] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC
+ 977, February 1986.
+
+ [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
+ Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
+ November 1996.
+
+ [15] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC
+ 1867, November 1995.
+
+ [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
+ August 1982.
+
+ [17] Postel, J., "Media Type Registration Procedure", RFC 1590,
+ November 1996.
+
+ [18] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC
+ 959, October 1985.
+
+ [19] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700,
+ October 1994.
+
+ [20] Sollins, K. and L. Masinter, "Functional Requirements for
+ Uniform Resource Names", RFC 1737, December 1994.
+
+ [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for
+ Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
+
+ [22] ISO-8859. International Standard -- Information Processing --
+ 8-bit Single-Byte Coded Graphic Character Sets --
+ Part 1: Latin alphabet No. 1, ISO-8859-1:1987.
+ Part 2: Latin alphabet No. 2, ISO-8859-2, 1987.
+ Part 3: Latin alphabet No. 3, ISO-8859-3, 1988.
+ Part 4: Latin alphabet No. 4, ISO-8859-4, 1988.
+ Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988.
+ Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987.
+ Part 7: Latin/Greek alphabet, ISO-8859-7, 1987.
+ Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988.
+ Part 9: Latin alphabet No. 5, ISO-8859-9, 1990.
+
+ [23] Meyers, J. and M. Rose, "The Content-MD5 Header Field", RFC
+ 1864, October 1995.
+
+ [24] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC
+ 1900, February 1996.
+
+ [25] Deutsch, P., "GZIP file format specification version 4.3", RFC
+ 1952, May 1996.
+
+
+
+Fielding, et al. Standards Track [Page 159]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [26] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP
+ Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35,
+ Dec. 1995. Slightly revised version of paper in Proc. 2nd
+ International WWW Conference '94: Mosaic and the Web, Oct. 1994,
+ which is available at
+ http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat
+ ency.html.
+
+ [27] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP
+ Performance", <URL: http://www.isi.edu/touch/pubs/http-perf96/>,
+ ISI Research Report ISI/RR-98-463, (original report dated Aug.
+ 1996), USC/Information Sciences Institute, August 1998.
+
+ [28] Mills, D., "Network Time Protocol (Version 3) Specification,
+ Implementation and Analysis", RFC 1305, March 1992.
+
+ [29] Deutsch, P., "DEFLATE Compressed Data Format Specification
+ version 1.3", RFC 1951, May 1996.
+
+ [30] S. Spero, "Analysis of HTTP Performance Problems,"
+ http://sunsite.unc.edu/mdma-release/http-prob.html.
+
+ [31] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format
+ Specification version 3.3", RFC 1950, May 1996.
+
+ [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
+ Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP:
+ Digest Access Authentication", RFC 2069, January 1997.
+
+ [33] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T.
+ Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC
+ 2068, January 1997.
+
+ [34] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [35] Troost, R. and Dorner, S., "Communicating Presentation
+ Information in Internet Messages: The Content-Disposition
+ Header", RFC 1806, June 1995.
+
+ [36] Mogul, J., Fielding, R., Gettys, J. and H. Frystyk, "Use and
+ Interpretation of HTTP Version Numbers", RFC 2145, May 1997.
+ [jg639]
+
+ [37] Palme, J., "Common Internet Message Headers", RFC 2076, February
+ 1997. [jg640]
+
+
+
+
+
+Fielding, et al. Standards Track [Page 160]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [38] Yergeau, F., "UTF-8, a transformation format of Unicode and
+ ISO-10646", RFC 2279, January 1998. [jg641]
+
+ [39] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E.,
+ Lie, H., and C. Lilley. "Network Performance Effects of
+ HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes
+ France, September 1997.[jg642]
+
+ [40] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Two: Media Types", RFC 2046, November
+ 1996. [jg643]
+
+ [41] Alvestrand, H., "IETF Policy on Character Sets and Languages",
+ BCP 18, RFC 2277, January 1998. [jg644]
+
+ [42] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
+ Identifiers (URI): Generic Syntax and Semantics", RFC 2396,
+ August 1998. [jg645]
+
+ [43] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., Sink, E. and L. Stewart, "HTTP
+ Authentication: Basic and Digest Access Authentication", RFC
+ 2617, June 1999. [jg646]
+
+ [44] Luotonen, A., "Tunneling TCP based protocols through Web proxy
+ servers," Work in Progress. [jg647]
+
+ [45] Palme, J. and A. Hopmann, "MIME E-mail Encapsulation of
+ Aggregate Documents, such as HTML (MHTML)", RFC 2110, March
+ 1997.
+
+ [46] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
+ 9, RFC 2026, October 1996.
+
+ [47] Masinter, L., "Hyper Text Coffee Pot Control Protocol
+ (HTCPCP/1.0)", RFC 2324, 1 April 1998.
+
+ [48] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Five: Conformance Criteria and Examples",
+ RFC 2049, November 1996.
+
+ [49] Troost, R., Dorner, S. and K. Moore, "Communicating Presentation
+ Information in Internet Messages: The Content-Disposition Header
+ Field", RFC 2183, August 1997.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 161]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+18 Authors' Addresses
+
+ Roy T. Fielding
+ Information and Computer Science
+ University of California, Irvine
+ Irvine, CA 92697-3425, USA
+
+ Fax: +1 (949) 824-1715
+
+
+ James Gettys
+ World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+ Jeffrey C. Mogul
+ Western Research Laboratory
+ Compaq Computer Corporation
+ 250 University Avenue
+ Palo Alto, California, 94305, USA
+
+
+
+ Henrik Frystyk Nielsen
+ World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+ Larry Masinter
+ Xerox Corporation
+ 3333 Coyote Hill Road
+ Palo Alto, CA 94034, USA
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 162]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Paul J. Leach
+ Microsoft Corporation
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+
+
+
+ Tim Berners-Lee
+ Director, World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 163]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+19 Appendices
+
+19.1 Internet Media Type message/http and application/http
+
+ In addition to defining the HTTP/1.1 protocol, this document serves
+ as the specification for the Internet media type "message/http" and
+ "application/http". The message/http type can be used to enclose a
+ single HTTP request or response message, provided that it obeys the
+ MIME restrictions for all "message" types regarding line length and
+ encodings. The application/http type can be used to enclose a
+ pipeline of one or more HTTP request or response messages (not
+ intermixed). The following is to be registered with IANA [17].
+
+ Media Type name: message
+ Media subtype name: http
+ Required parameters: none
+ Optional parameters: version, msgtype
+ version: The HTTP-Version number of the enclosed message
+ (e.g., "1.1"). If not present, the version can be
+ determined from the first line of the body.
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+ Security considerations: none
+
+ Media Type name: application
+ Media subtype name: http
+ Required parameters: none
+ Optional parameters: version, msgtype
+ version: The HTTP-Version number of the enclosed messages
+ (e.g., "1.1"). If not present, the version can be
+ determined from the first line of the body.
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+ Encoding considerations: HTTP messages enclosed by this type
+ are in "binary" format; use of an appropriate
+ Content-Transfer-Encoding is required when
+ transmitted via E-mail.
+ Security considerations: none
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 164]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+19.2 Internet Media Type multipart/byteranges
+
+ When an HTTP 206 (Partial Content) response message includes the
+ content of multiple ranges (a response to a request for multiple
+ non-overlapping ranges), these are transmitted as a multipart
+ message-body. The media type for this purpose is called
+ "multipart/byteranges".
+
+ The multipart/byteranges media type includes two or more parts, each
+ with its own Content-Type and Content-Range fields. The required
+ boundary parameter specifies the boundary string used to separate
+ each body-part.
+
+ Media Type name: multipart
+ Media subtype name: byteranges
+ Required parameters: boundary
+ Optional parameters: none
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+ Security considerations: none
+
+
+ For example:
+
+ HTTP/1.1 206 Partial Content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
+
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 500-999/8000
+
+ ...the first range...
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 7000-7999/8000
+
+ ...the second range
+ --THIS_STRING_SEPARATES--
+
+ Notes:
+
+ 1) Additional CRLFs may precede the first boundary string in the
+ entity.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 165]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 2) Although RFC 2046 [40] permits the boundary string to be
+ quoted, some existing implementations handle a quoted boundary
+ string incorrectly.
+
+ 3) A number of browsers and servers were coded to an early draft
+ of the byteranges specification to use a media type of
+ multipart/x-byteranges, which is almost, but not quite
+ compatible with the version documented in HTTP/1.1.
+
+19.3 Tolerant Applications
+
+ Although this document specifies the requirements for the generation
+ of HTTP/1.1 messages, not all applications will be correct in their
+ implementation. We therefore recommend that operational applications
+ be tolerant of deviations whenever those deviations can be
+ interpreted unambiguously.
+
+ Clients SHOULD be tolerant in parsing the Status-Line and servers
+ tolerant when parsing the Request-Line. In particular, they SHOULD
+ accept any amount of SP or HT characters between fields, even though
+ only a single SP is required.
+
+ The line terminator for message-header fields is the sequence CRLF.
+ However, we recommend that applications, when parsing such headers,
+ recognize a single LF as a line terminator and ignore the leading CR.
+
+ The character set of an entity-body SHOULD be labeled as the lowest
+ common denominator of the character codes used within that body, with
+ the exception that not labeling the entity is preferred over labeling
+ the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1
+ and 3.4.1.
+
+ Additional rules for requirements on parsing and encoding of dates
+ and other potential problems with date encodings include:
+
+ - HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date
+ which appears to be more than 50 years in the future is in fact
+ in the past (this helps solve the "year 2000" problem).
+
+ - An HTTP/1.1 implementation MAY internally represent a parsed
+ Expires date as earlier than the proper value, but MUST NOT
+ internally represent a parsed Expires date as later than the
+ proper value.
+
+ - All expiration-related calculations MUST be done in GMT. The
+ local time zone MUST NOT influence the calculation or comparison
+ of an age or expiration time.
+
+
+
+
+Fielding, et al. Standards Track [Page 166]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If an HTTP header incorrectly carries a date value with a time
+ zone other than GMT, it MUST be converted into GMT using the
+ most conservative possible conversion.
+
+19.4 Differences Between HTTP Entities and RFC 2045 Entities
+
+ HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC
+ 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to
+ allow entities to be transmitted in an open variety of
+ representations and with extensible mechanisms. However, RFC 2045
+ discusses mail, and HTTP has a few features that are different from
+ those described in RFC 2045. These differences were carefully chosen
+ to optimize performance over binary connections, to allow greater
+ freedom in the use of new media types, to make date comparisons
+ easier, and to acknowledge the practice of some early HTTP servers
+ and clients.
+
+ This appendix describes specific areas where HTTP differs from RFC
+ 2045. Proxies and gateways to strict MIME environments SHOULD be
+ aware of these differences and provide the appropriate conversions
+ where necessary. Proxies and gateways from MIME environments to HTTP
+ also need to be aware of the differences because some conversions
+ might be required.
+
+19.4.1 MIME-Version
+
+ HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY
+ include a single MIME-Version general-header field to indicate what
+ version of the MIME protocol was used to construct the message. Use
+ of the MIME-Version header field indicates that the message is in
+ full compliance with the MIME protocol (as defined in RFC 2045[7]).
+ Proxies/gateways are responsible for ensuring full compliance (where
+ possible) when exporting HTTP messages to strict MIME environments.
+
+ MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT
+
+ MIME version "1.0" is the default for use in HTTP/1.1. However,
+ HTTP/1.1 message parsing and semantics are defined by this document
+ and not the MIME specification.
+
+19.4.2 Conversion to Canonical Form
+
+ RFC 2045 [7] requires that an Internet mail entity be converted to
+ canonical form prior to being transferred, as described in section 4
+ of RFC 2049 [48]. Section 3.7.1 of this document describes the forms
+ allowed for subtypes of the "text" media type when transmitted over
+ HTTP. RFC 2046 requires that content with a type of "text" represent
+ line breaks as CRLF and forbids the use of CR or LF outside of line
+
+
+
+Fielding, et al. Standards Track [Page 167]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a
+ line break within text content when a message is transmitted over
+ HTTP.
+
+ Where it is possible, a proxy or gateway from HTTP to a strict MIME
+ environment SHOULD translate all line breaks within the text media
+ types described in section 3.7.1 of this document to the RFC 2049
+ canonical form of CRLF. Note, however, that this might be complicated
+ by the presence of a Content-Encoding and by the fact that HTTP
+ allows the use of some character sets which do not use octets 13 and
+ 10 to represent CR and LF, as is the case for some multi-byte
+ character sets.
+
+ Implementors should note that conversion will break any cryptographic
+ checksums applied to the original content unless the original content
+ is already in canonical form. Therefore, the canonical form is
+ recommended for any content that uses such checksums in HTTP.
+
+19.4.3 Conversion of Date Formats
+
+ HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to
+ simplify the process of date comparison. Proxies and gateways from
+ other protocols SHOULD ensure that any Date header field present in a
+ message conforms to one of the HTTP/1.1 formats and rewrite the date
+ if necessary.
+
+19.4.4 Introduction of Content-Encoding
+
+ RFC 2045 does not include any concept equivalent to HTTP/1.1's
+ Content-Encoding header field. Since this acts as a modifier on the
+ media type, proxies and gateways from HTTP to MIME-compliant
+ protocols MUST either change the value of the Content-Type header
+ field or decode the entity-body before forwarding the message. (Some
+ experimental applications of Content-Type for Internet mail have used
+ a media-type parameter of ";conversions=<content-coding>" to perform
+ a function equivalent to Content-Encoding. However, this parameter is
+ not part of RFC 2045.)
+
+19.4.5 No Content-Transfer-Encoding
+
+ HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC
+ 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST
+ remove any non-identity CTE ("quoted-printable" or "base64") encoding
+ prior to delivering the response message to an HTTP client.
+
+ Proxies and gateways from HTTP to MIME-compliant protocols are
+ responsible for ensuring that the message is in the correct format
+ and encoding for safe transport on that protocol, where "safe
+
+
+
+Fielding, et al. Standards Track [Page 168]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ transport" is defined by the limitations of the protocol being used.
+ Such a proxy or gateway SHOULD label the data with an appropriate
+ Content-Transfer-Encoding if doing so will improve the likelihood of
+ safe transport over the destination protocol.
+
+19.4.6 Introduction of Transfer-Encoding
+
+ HTTP/1.1 introduces the Transfer-Encoding header field (section
+ 14.41). Proxies/gateways MUST remove any transfer-coding prior to
+ forwarding a message via a MIME-compliant protocol.
+
+ A process for decoding the "chunked" transfer-coding (section 3.6)
+ can be represented in pseudo-code as:
+
+ length := 0
+ read chunk-size, chunk-extension (if any) and CRLF
+ while (chunk-size > 0) {
+ read chunk-data and CRLF
+ append chunk-data to entity-body
+ length := length + chunk-size
+ read chunk-size and CRLF
+ }
+ read entity-header
+ while (entity-header not empty) {
+ append entity-header to existing header fields
+ read entity-header
+ }
+ Content-Length := length
+ Remove "chunked" from Transfer-Encoding
+
+19.4.7 MHTML and Line Length Limitations
+
+ HTTP implementations which share code with MHTML [45] implementations
+ need to be aware of MIME line length limitations. Since HTTP does not
+ have this limitation, HTTP does not fold long lines. MHTML messages
+ being transported by HTTP follow all conventions of MHTML, including
+ line length limitations and folding, canonicalization, etc., since
+ HTTP transports all message-bodies as payload (see section 3.7.2) and
+ does not interpret the content or any MIME header lines that might be
+ contained therein.
+
+19.5 Additional Features
+
+ RFC 1945 and RFC 2068 document protocol elements used by some
+ existing HTTP implementations, but not consistently and correctly
+ across most HTTP/1.1 applications. Implementors are advised to be
+ aware of these features, but cannot rely upon their presence in, or
+ interoperability with, other HTTP/1.1 applications. Some of these
+
+
+
+Fielding, et al. Standards Track [Page 169]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ describe proposed experimental features, and some describe features
+ that experimental deployment found lacking that are now addressed in
+ the base HTTP/1.1 specification.
+
+ A number of other headers, such as Content-Disposition and Title,
+ from SMTP and MIME are also often implemented (see RFC 2076 [37]).
+
+19.5.1 Content-Disposition
+
+ The Content-Disposition response-header field has been proposed as a
+ means for the origin server to suggest a default filename if the user
+ requests that the content is saved to a file. This usage is derived
+ from the definition of Content-Disposition in RFC 1806 [35].
+
+ content-disposition = "Content-Disposition" ":"
+ disposition-type *( ";" disposition-parm )
+ disposition-type = "attachment" | disp-extension-token
+ disposition-parm = filename-parm | disp-extension-parm
+ filename-parm = "filename" "=" quoted-string
+ disp-extension-token = token
+ disp-extension-parm = token "=" ( token | quoted-string )
+
+ An example is
+
+ Content-Disposition: attachment; filename="fname.ext"
+
+ The receiving user agent SHOULD NOT respect any directory path
+ information present in the filename-parm parameter, which is the only
+ parameter believed to apply to HTTP implementations at this time. The
+ filename SHOULD be treated as a terminal component only.
+
+ If this header is used in a response with the application/octet-
+ stream content-type, the implied suggestion is that the user agent
+ should not display the response, but directly enter a `save response
+ as...' dialog.
+
+ See section 15.5 for Content-Disposition security issues.
+
+19.6 Compatibility with Previous Versions
+
+ It is beyond the scope of a protocol specification to mandate
+ compliance with previous versions. HTTP/1.1 was deliberately
+ designed, however, to make supporting previous versions easy. It is
+ worth noting that, at the time of composing this specification
+ (1996), we would expect commercial HTTP/1.1 servers to:
+
+ - recognize the format of the Request-Line for HTTP/0.9, 1.0, and
+ 1.1 requests;
+
+
+
+Fielding, et al. Standards Track [Page 170]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - understand any valid request in the format of HTTP/0.9, 1.0, or
+ 1.1;
+
+ - respond appropriately with a message in the same major version
+ used by the client.
+
+ And we would expect HTTP/1.1 clients to:
+
+ - recognize the format of the Status-Line for HTTP/1.0 and 1.1
+ responses;
+
+ - understand any valid response in the format of HTTP/0.9, 1.0, or
+ 1.1.
+
+ For most implementations of HTTP/1.0, each connection is established
+ by the client prior to the request and closed by the server after
+ sending the response. Some implementations implement the Keep-Alive
+ version of persistent connections described in section 19.7.1 of RFC
+ 2068 [33].
+
+19.6.1 Changes from HTTP/1.0
+
+ This section summarizes major differences between versions HTTP/1.0
+ and HTTP/1.1.
+
+19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP
+ Addresses
+
+ The requirements that clients and servers support the Host request-
+ header, report an error if the Host request-header (section 14.23) is
+ missing from an HTTP/1.1 request, and accept absolute URIs (section
+ 5.1.2) are among the most important changes defined by this
+ specification.
+
+ Older HTTP/1.0 clients assumed a one-to-one relationship of IP
+ addresses and servers; there was no other established mechanism for
+ distinguishing the intended server of a request than the IP address
+ to which that request was directed. The changes outlined above will
+ allow the Internet, once older HTTP clients are no longer common, to
+ support multiple Web sites from a single IP address, greatly
+ simplifying large operational Web servers, where allocation of many
+ IP addresses to a single host has created serious problems. The
+ Internet will also be able to recover the IP addresses that have been
+ allocated for the sole purpose of allowing special-purpose domain
+ names to be used in root-level HTTP URLs. Given the rate of growth of
+ the Web, and the number of servers already deployed, it is extremely
+
+
+
+
+
+Fielding, et al. Standards Track [Page 171]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ important that all implementations of HTTP (including updates to
+ existing HTTP/1.0 applications) correctly implement these
+ requirements:
+
+ - Both clients and servers MUST support the Host request-header.
+
+ - A client that sends an HTTP/1.1 request MUST send a Host header.
+
+ - Servers MUST report a 400 (Bad Request) error if an HTTP/1.1
+ request does not include a Host request-header.
+
+ - Servers MUST accept absolute URIs.
+
+19.6.2 Compatibility with HTTP/1.0 Persistent Connections
+
+ Some clients and servers might wish to be compatible with some
+ previous implementations of persistent connections in HTTP/1.0
+ clients and servers. Persistent connections in HTTP/1.0 are
+ explicitly negotiated as they are not the default behavior. HTTP/1.0
+ experimental implementations of persistent connections are faulty,
+ and the new facilities in HTTP/1.1 are designed to rectify these
+ problems. The problem was that some existing 1.0 clients may be
+ sending Keep-Alive to a proxy server that doesn't understand
+ Connection, which would then erroneously forward it to the next
+ inbound server, which would establish the Keep-Alive connection and
+ result in a hung HTTP/1.0 proxy waiting for the close on the
+ response. The result is that HTTP/1.0 clients must be prevented from
+ using Keep-Alive when talking to proxies.
+
+ However, talking to proxies is the most important use of persistent
+ connections, so that prohibition is clearly unacceptable. Therefore,
+ we need some other mechanism for indicating a persistent connection
+ is desired, which is safe to use even when talking to an old proxy
+ that ignores Connection. Persistent connections are the default for
+ HTTP/1.1 messages; we introduce a new keyword (Connection: close) for
+ declaring non-persistence. See section 14.10.
+
+ The original HTTP/1.0 form of persistent connections (the Connection:
+ Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33]
+
+19.6.3 Changes from RFC 2068
+
+ This specification has been carefully audited to correct and
+ disambiguate key word usage; RFC 2068 had many problems in respect to
+ the conventions laid out in RFC 2119 [34].
+
+ Clarified which error code should be used for inbound server failures
+ (e.g. DNS failures). (Section 10.5.5).
+
+
+
+Fielding, et al. Standards Track [Page 172]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ CREATE had a race that required an Etag be sent when a resource is
+ first created. (Section 10.2.2).
+
+ Content-Base was deleted from the specification: it was not
+ implemented widely, and there is no simple, safe way to introduce it
+ without a robust extension mechanism. In addition, it is used in a
+ similar, but not identical fashion in MHTML [45].
+
+ Transfer-coding and message lengths all interact in ways that
+ required fixing exactly when chunked encoding is used (to allow for
+ transfer encoding that may not be self delimiting); it was important
+ to straighten out exactly how message lengths are computed. (Sections
+ 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16)
+
+ A content-coding of "identity" was introduced, to solve problems
+ discovered in caching. (section 3.5)
+
+ Quality Values of zero should indicate that "I don't want something"
+ to allow clients to refuse a representation. (Section 3.9)
+
+ The use and interpretation of HTTP version numbers has been clarified
+ by RFC 2145. Require proxies to upgrade requests to highest protocol
+ version they support to deal with problems discovered in HTTP/1.0
+ implementations (Section 3.1)
+
+ Charset wildcarding is introduced to avoid explosion of character set
+ names in accept headers. (Section 14.2)
+
+ A case was missed in the Cache-Control model of HTTP/1.1; s-maxage
+ was introduced to add this missing case. (Sections 13.4, 14.8, 14.9,
+ 14.9.3)
+
+ The Cache-Control: max-age directive was not properly defined for
+ responses. (Section 14.9.3)
+
+ There are situations where a server (especially a proxy) does not
+ know the full length of a response but is capable of serving a
+ byterange request. We therefore need a mechanism to allow byteranges
+ with a content-range not indicating the full length of the message.
+ (Section 14.16)
+
+ Range request responses would become very verbose if all meta-data
+ were always returned; by allowing the server to only send needed
+ headers in a 206 response, this problem can be avoided. (Section
+ 10.2.7, 13.5.3, and 14.27)
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 173]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Fix problem with unsatisfiable range requests; there are two cases:
+ syntactic problems, and range doesn't exist in the document. The 416
+ status code was needed to resolve this ambiguity needed to indicate
+ an error for a byte range request that falls outside of the actual
+ contents of a document. (Section 10.4.17, 14.16)
+
+ Rewrite of message transmission requirements to make it much harder
+ for implementors to get it wrong, as the consequences of errors here
+ can have significant impact on the Internet, and to deal with the
+ following problems:
+
+ 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where
+ this was incorrectly placing a requirement on the behavior of
+ an implementation of a future version of HTTP/1.x
+
+ 2. Made it clear that user-agents should retry requests, not
+ "clients" in general.
+
+ 3. Converted requirements for clients to ignore unexpected 100
+ (Continue) responses, and for proxies to forward 100 responses,
+ into a general requirement for 1xx responses.
+
+ 4. Modified some TCP-specific language, to make it clearer that
+ non-TCP transports are possible for HTTP.
+
+ 5. Require that the origin server MUST NOT wait for the request
+ body before it sends a required 100 (Continue) response.
+
+ 6. Allow, rather than require, a server to omit 100 (Continue) if
+ it has already seen some of the request body.
+
+ 7. Allow servers to defend against denial-of-service attacks and
+ broken clients.
+
+ This change adds the Expect header and 417 status code. The message
+ transmission requirements fixes are in sections 8.2, 10.4.18,
+ 8.1.2.2, 13.11, and 14.20.
+
+ Proxies should be able to add Content-Length when appropriate.
+ (Section 13.5.2)
+
+ Clean up confusion between 403 and 404 responses. (Section 10.4.4,
+ 10.4.5, and 10.4.11)
+
+ Warnings could be cached incorrectly, or not updated appropriately.
+ (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning
+ also needed to be a general header, as PUT or other methods may have
+ need for it in requests.
+
+
+
+Fielding, et al. Standards Track [Page 174]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Transfer-coding had significant problems, particularly with
+ interactions with chunked encoding. The solution is that transfer-
+ codings become as full fledged as content-codings. This involves
+ adding an IANA registry for transfer-codings (separate from content
+ codings), a new header field (TE) and enabling trailer headers in the
+ future. Transfer encoding is a major performance benefit, so it was
+ worth fixing [39]. TE also solves another, obscure, downward
+ interoperability problem that could have occurred due to interactions
+ between authentication trailers, chunked encoding and HTTP/1.0
+ clients.(Section 3.6, 3.6.1, and 14.39)
+
+ The PATCH, LINK, UNLINK methods were defined but not commonly
+ implemented in previous versions of this specification. See RFC 2068
+ [33].
+
+ The Alternates, Content-Version, Derived-From, Link, URI, Public and
+ Content-Base header fields were defined in previous versions of this
+ specification, but not commonly implemented. See RFC 2068 [33].
+
+20 Index
+
+ Please see the PostScript version of this RFC for the INDEX.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 175]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+21. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 176]
+
diff --git a/lib/inets/doc/archive/rfc959.txt b/lib/inets/doc/archive/rfc959.txt
new file mode 100644
index 0000000000..5c9f11af5d
--- /dev/null
+++ b/lib/inets/doc/archive/rfc959.txt
@@ -0,0 +1,3933 @@
+
+
+Network Working Group J. Postel
+Request for Comments: 959 J. Reynolds
+ ISI
+Obsoletes RFC: 765 (IEN 149) October 1985
+
+ FILE TRANSFER PROTOCOL (FTP)
+
+
+Status of this Memo
+
+ This memo is the official specification of the File Transfer
+ Protocol (FTP). Distribution of this memo is unlimited.
+
+ The following new optional commands are included in this edition of
+ the specification:
+
+ CDUP (Change to Parent Directory), SMNT (Structure Mount), STOU
+ (Store Unique), RMD (Remove Directory), MKD (Make Directory), PWD
+ (Print Directory), and SYST (System).
+
+ Note that this specification is compatible with the previous edition.
+
+1. INTRODUCTION
+
+ The objectives of FTP are 1) to promote sharing of files (computer
+ programs and/or data), 2) to encourage indirect or implicit (via
+ programs) use of remote computers, 3) to shield a user from
+ variations in file storage systems among hosts, and 4) to transfer
+ data reliably and efficiently. FTP, though usable directly by a user
+ at a terminal, is designed mainly for use by programs.
+
+ The attempt in this specification is to satisfy the diverse needs of
+ users of maxi-hosts, mini-hosts, personal workstations, and TACs,
+ with a simple, and easily implemented protocol design.
+
+ This paper assumes knowledge of the Transmission Control Protocol
+ (TCP) [2] and the Telnet Protocol [3]. These documents are contained
+ in the ARPA-Internet protocol handbook [1].
+
+2. OVERVIEW
+
+ In this section, the history, the terminology, and the FTP model are
+ discussed. The terms defined in this section are only those that
+ have special significance in FTP. Some of the terminology is very
+ specific to the FTP model; some readers may wish to turn to the
+ section on the FTP model while reviewing the terminology.
+
+
+
+
+
+
+
+Postel & Reynolds [Page 1]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 2.1. HISTORY
+
+ FTP has had a long evolution over the years. Appendix III is a
+ chronological compilation of Request for Comments documents
+ relating to FTP. These include the first proposed file transfer
+ mechanisms in 1971 that were developed for implementation on hosts
+ at M.I.T. (RFC 114), plus comments and discussion in RFC 141.
+
+ RFC 172 provided a user-level oriented protocol for file transfer
+ between host computers (including terminal IMPs). A revision of
+ this as RFC 265, restated FTP for additional review, while RFC 281
+ suggested further changes. The use of a "Set Data Type"
+ transaction was proposed in RFC 294 in January 1982.
+
+ RFC 354 obsoleted RFCs 264 and 265. The File Transfer Protocol
+ was now defined as a protocol for file transfer between HOSTs on
+ the ARPANET, with the primary function of FTP defined as
+ transfering files efficiently and reliably among hosts and
+ allowing the convenient use of remote file storage capabilities.
+ RFC 385 further commented on errors, emphasis points, and
+ additions to the protocol, while RFC 414 provided a status report
+ on the working server and user FTPs. RFC 430, issued in 1973,
+ (among other RFCs too numerous to mention) presented further
+ comments on FTP. Finally, an "official" FTP document was
+ published as RFC 454.
+
+ By July 1973, considerable changes from the last versions of FTP
+ were made, but the general structure remained the same. RFC 542
+ was published as a new "official" specification to reflect these
+ changes. However, many implementations based on the older
+ specification were not updated.
+
+ In 1974, RFCs 607 and 614 continued comments on FTP. RFC 624
+ proposed further design changes and minor modifications. In 1975,
+ RFC 686 entitled, "Leaving Well Enough Alone", discussed the
+ differences between all of the early and later versions of FTP.
+ RFC 691 presented a minor revision of RFC 686, regarding the
+ subject of print files.
+
+ Motivated by the transition from the NCP to the TCP as the
+ underlying protocol, a phoenix was born out of all of the above
+ efforts in RFC 765 as the specification of FTP for use on TCP.
+
+ This current edition of the FTP specification is intended to
+ correct some minor documentation errors, to improve the
+ explanation of some protocol features, and to add some new
+ optional commands.
+
+
+Postel & Reynolds [Page 2]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ In particular, the following new optional commands are included in
+ this edition of the specification:
+
+ CDUP - Change to Parent Directory
+
+ SMNT - Structure Mount
+
+ STOU - Store Unique
+
+ RMD - Remove Directory
+
+ MKD - Make Directory
+
+ PWD - Print Directory
+
+ SYST - System
+
+ This specification is compatible with the previous edition. A
+ program implemented in conformance to the previous specification
+ should automatically be in conformance to this specification.
+
+ 2.2. TERMINOLOGY
+
+ ASCII
+
+ The ASCII character set is as defined in the ARPA-Internet
+ Protocol Handbook. In FTP, ASCII characters are defined to be
+ the lower half of an eight-bit code set (i.e., the most
+ significant bit is zero).
+
+ access controls
+
+ Access controls define users' access privileges to the use of a
+ system, and to the files in that system. Access controls are
+ necessary to prevent unauthorized or accidental use of files.
+ It is the prerogative of a server-FTP process to invoke access
+ controls.
+
+ byte size
+
+ There are two byte sizes of interest in FTP: the logical byte
+ size of the file, and the transfer byte size used for the
+ transmission of the data. The transfer byte size is always 8
+ bits. The transfer byte size is not necessarily the byte size
+ in which data is to be stored in a system, nor the logical byte
+ size for interpretation of the structure of the data.
+
+
+
+Postel & Reynolds [Page 3]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ control connection
+
+ The communication path between the USER-PI and SERVER-PI for
+ the exchange of commands and replies. This connection follows
+ the Telnet Protocol.
+
+ data connection
+
+ A full duplex connection over which data is transferred, in a
+ specified mode and type. The data transferred may be a part of
+ a file, an entire file or a number of files. The path may be
+ between a server-DTP and a user-DTP, or between two
+ server-DTPs.
+
+ data port
+
+ The passive data transfer process "listens" on the data port
+ for a connection from the active transfer process in order to
+ open the data connection.
+
+ DTP
+
+ The data transfer process establishes and manages the data
+ connection. The DTP can be passive or active.
+
+ End-of-Line
+
+ The end-of-line sequence defines the separation of printing
+ lines. The sequence is Carriage Return, followed by Line Feed.
+
+ EOF
+
+ The end-of-file condition that defines the end of a file being
+ transferred.
+
+ EOR
+
+ The end-of-record condition that defines the end of a record
+ being transferred.
+
+ error recovery
+
+ A procedure that allows a user to recover from certain errors
+ such as failure of either host system or transfer process. In
+ FTP, error recovery may involve restarting a file transfer at a
+ given checkpoint.
+
+
+
+Postel & Reynolds [Page 4]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ FTP commands
+
+ A set of commands that comprise the control information flowing
+ from the user-FTP to the server-FTP process.
+
+ file
+
+ An ordered set of computer data (including programs), of
+ arbitrary length, uniquely identified by a pathname.
+
+ mode
+
+ The mode in which data is to be transferred via the data
+ connection. The mode defines the data format during transfer
+ including EOR and EOF. The transfer modes defined in FTP are
+ described in the Section on Transmission Modes.
+
+ NVT
+
+ The Network Virtual Terminal as defined in the Telnet Protocol.
+
+ NVFS
+
+ The Network Virtual File System. A concept which defines a
+ standard network file system with standard commands and
+ pathname conventions.
+
+ page
+
+ A file may be structured as a set of independent parts called
+ pages. FTP supports the transmission of discontinuous files as
+ independent indexed pages.
+
+ pathname
+
+ Pathname is defined to be the character string which must be
+ input to a file system by a user in order to identify a file.
+ Pathname normally contains device and/or directory names, and
+ file name specification. FTP does not yet specify a standard
+ pathname convention. Each user must follow the file naming
+ conventions of the file systems involved in the transfer.
+
+ PI
+
+ The protocol interpreter. The user and server sides of the
+ protocol have distinct roles implemented in a user-PI and a
+ server-PI.
+
+
+Postel & Reynolds [Page 5]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ record
+
+ A sequential file may be structured as a number of contiguous
+ parts called records. Record structures are supported by FTP
+ but a file need not have record structure.
+
+ reply
+
+ A reply is an acknowledgment (positive or negative) sent from
+ server to user via the control connection in response to FTP
+ commands. The general form of a reply is a completion code
+ (including error codes) followed by a text string. The codes
+ are for use by programs and the text is usually intended for
+ human users.
+
+ server-DTP
+
+ The data transfer process, in its normal "active" state,
+ establishes the data connection with the "listening" data port.
+ It sets up parameters for transfer and storage, and transfers
+ data on command from its PI. The DTP can be placed in a
+ "passive" state to listen for, rather than initiate a
+ connection on the data port.
+
+ server-FTP process
+
+ A process or set of processes which perform the function of
+ file transfer in cooperation with a user-FTP process and,
+ possibly, another server. The functions consist of a protocol
+ interpreter (PI) and a data transfer process (DTP).
+
+ server-PI
+
+ The server protocol interpreter "listens" on Port L for a
+ connection from a user-PI and establishes a control
+ communication connection. It receives standard FTP commands
+ from the user-PI, sends replies, and governs the server-DTP.
+
+ type
+
+ The data representation type used for data transfer and
+ storage. Type implies certain transformations between the time
+ of data storage and data transfer. The representation types
+ defined in FTP are described in the Section on Establishing
+ Data Connections.
+
+
+
+
+Postel & Reynolds [Page 6]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ user
+
+ A person or a process on behalf of a person wishing to obtain
+ file transfer service. The human user may interact directly
+ with a server-FTP process, but use of a user-FTP process is
+ preferred since the protocol design is weighted towards
+ automata.
+
+ user-DTP
+
+ The data transfer process "listens" on the data port for a
+ connection from a server-FTP process. If two servers are
+ transferring data between them, the user-DTP is inactive.
+
+ user-FTP process
+
+ A set of functions including a protocol interpreter, a data
+ transfer process and a user interface which together perform
+ the function of file transfer in cooperation with one or more
+ server-FTP processes. The user interface allows a local
+ language to be used in the command-reply dialogue with the
+ user.
+
+ user-PI
+
+ The user protocol interpreter initiates the control connection
+ from its port U to the server-FTP process, initiates FTP
+ commands, and governs the user-DTP if that process is part of
+ the file transfer.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 7]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 2.3. THE FTP MODEL
+
+ With the above definitions in mind, the following model (shown in
+ Figure 1) may be diagrammed for an FTP service.
+
+ -------------
+ |/---------\|
+ || User || --------
+ ||Interface|<--->| User |
+ |\----^----/| --------
+ ---------- | | |
+ |/------\| FTP Commands |/----V----\|
+ ||Server|<---------------->| User ||
+ || PI || FTP Replies || PI ||
+ |\--^---/| |\----^----/|
+ | | | | | |
+ -------- |/--V---\| Data |/----V----\| --------
+ | File |<--->|Server|<---------------->| User |<--->| File |
+ |System| || DTP || Connection || DTP || |System|
+ -------- |\------/| |\---------/| --------
+ ---------- -------------
+
+ Server-FTP USER-FTP
+
+ NOTES: 1. The data connection may be used in either direction.
+ 2. The data connection need not exist all of the time.
+
+ Figure 1 Model for FTP Use
+
+ In the model described in Figure 1, the user-protocol interpreter
+ initiates the control connection. The control connection follows
+ the Telnet protocol. At the initiation of the user, standard FTP
+ commands are generated by the user-PI and transmitted to the
+ server process via the control connection. (The user may
+ establish a direct control connection to the server-FTP, from a
+ TAC terminal for example, and generate standard FTP commands
+ independently, bypassing the user-FTP process.) Standard replies
+ are sent from the server-PI to the user-PI over the control
+ connection in response to the commands.
+
+ The FTP commands specify the parameters for the data connection
+ (data port, transfer mode, representation type, and structure) and
+ the nature of file system operation (store, retrieve, append,
+ delete, etc.). The user-DTP or its designate should "listen" on
+ the specified data port, and the server initiate the data
+ connection and data transfer in accordance with the specified
+ parameters. It should be noted that the data port need not be in
+
+
+Postel & Reynolds [Page 8]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ the same host that initiates the FTP commands via the control
+ connection, but the user or the user-FTP process must ensure a
+ "listen" on the specified data port. It ought to also be noted
+ that the data connection may be used for simultaneous sending and
+ receiving.
+
+ In another situation a user might wish to transfer files between
+ two hosts, neither of which is a local host. The user sets up
+ control connections to the two servers and then arranges for a
+ data connection between them. In this manner, control information
+ is passed to the user-PI but data is transferred between the
+ server data transfer processes. Following is a model of this
+ server-server interaction.
+
+
+ Control ------------ Control
+ ---------->| User-FTP |<-----------
+ | | User-PI | |
+ | | "C" | |
+ V ------------ V
+ -------------- --------------
+ | Server-FTP | Data Connection | Server-FTP |
+ | "A" |<---------------------->| "B" |
+ -------------- Port (A) Port (B) --------------
+
+
+ Figure 2
+
+ The protocol requires that the control connections be open while
+ data transfer is in progress. It is the responsibility of the
+ user to request the closing of the control connections when
+ finished using the FTP service, while it is the server who takes
+ the action. The server may abort data transfer if the control
+ connections are closed without command.
+
+ The Relationship between FTP and Telnet:
+
+ The FTP uses the Telnet protocol on the control connection.
+ This can be achieved in two ways: first, the user-PI or the
+ server-PI may implement the rules of the Telnet Protocol
+ directly in their own procedures; or, second, the user-PI or
+ the server-PI may make use of the existing Telnet module in the
+ system.
+
+ Ease of implementaion, sharing code, and modular programming
+ argue for the second approach. Efficiency and independence
+
+
+
+Postel & Reynolds [Page 9]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ argue for the first approach. In practice, FTP relies on very
+ little of the Telnet Protocol, so the first approach does not
+ necessarily involve a large amount of code.
+
+3. DATA TRANSFER FUNCTIONS
+
+ Files are transferred only via the data connection. The control
+ connection is used for the transfer of commands, which describe the
+ functions to be performed, and the replies to these commands (see the
+ Section on FTP Replies). Several commands are concerned with the
+ transfer of data between hosts. These data transfer commands include
+ the MODE command which specify how the bits of the data are to be
+ transmitted, and the STRUcture and TYPE commands, which are used to
+ define the way in which the data are to be represented. The
+ transmission and representation are basically independent but the
+ "Stream" transmission mode is dependent on the file structure
+ attribute and if "Compressed" transmission mode is used, the nature
+ of the filler byte depends on the representation type.
+
+ 3.1. DATA REPRESENTATION AND STORAGE
+
+ Data is transferred from a storage device in the sending host to a
+ storage device in the receiving host. Often it is necessary to
+ perform certain transformations on the data because data storage
+ representations in the two systems are different. For example,
+ NVT-ASCII has different data storage representations in different
+ systems. DEC TOPS-20s's generally store NVT-ASCII as five 7-bit
+ ASCII characters, left-justified in a 36-bit word. IBM Mainframe's
+ store NVT-ASCII as 8-bit EBCDIC codes. Multics stores NVT-ASCII
+ as four 9-bit characters in a 36-bit word. It is desirable to
+ convert characters into the standard NVT-ASCII representation when
+ transmitting text between dissimilar systems. The sending and
+ receiving sites would have to perform the necessary
+ transformations between the standard representation and their
+ internal representations.
+
+ A different problem in representation arises when transmitting
+ binary data (not character codes) between host systems with
+ different word lengths. It is not always clear how the sender
+ should send data, and the receiver store it. For example, when
+ transmitting 32-bit bytes from a 32-bit word-length system to a
+ 36-bit word-length system, it may be desirable (for reasons of
+ efficiency and usefulness) to store the 32-bit bytes
+ right-justified in a 36-bit word in the latter system. In any
+ case, the user should have the option of specifying data
+ representation and transformation functions. It should be noted
+
+
+
+Postel & Reynolds [Page 10]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ that FTP provides for very limited data type representations.
+ Transformations desired beyond this limited capability should be
+ performed by the user directly.
+
+ 3.1.1. DATA TYPES
+
+ Data representations are handled in FTP by a user specifying a
+ representation type. This type may implicitly (as in ASCII or
+ EBCDIC) or explicitly (as in Local byte) define a byte size for
+ interpretation which is referred to as the "logical byte size."
+ Note that this has nothing to do with the byte size used for
+ transmission over the data connection, called the "transfer
+ byte size", and the two should not be confused. For example,
+ NVT-ASCII has a logical byte size of 8 bits. If the type is
+ Local byte, then the TYPE command has an obligatory second
+ parameter specifying the logical byte size. The transfer byte
+ size is always 8 bits.
+
+ 3.1.1.1. ASCII TYPE
+
+ This is the default type and must be accepted by all FTP
+ implementations. It is intended primarily for the transfer
+ of text files, except when both hosts would find the EBCDIC
+ type more convenient.
+
+ The sender converts the data from an internal character
+ representation to the standard 8-bit NVT-ASCII
+ representation (see the Telnet specification). The receiver
+ will convert the data from the standard form to his own
+ internal form.
+
+ In accordance with the NVT standard, the <CRLF> sequence
+ should be used where necessary to denote the end of a line
+ of text. (See the discussion of file structure at the end
+ of the Section on Data Representation and Storage.)
+
+ Using the standard NVT-ASCII representation means that data
+ must be interpreted as 8-bit bytes.
+
+ The Format parameter for ASCII and EBCDIC types is discussed
+ below.
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 11]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 3.1.1.2. EBCDIC TYPE
+
+ This type is intended for efficient transfer between hosts
+ which use EBCDIC for their internal character
+ representation.
+
+ For transmission, the data are represented as 8-bit EBCDIC
+ characters. The character code is the only difference
+ between the functional specifications of EBCDIC and ASCII
+ types.
+
+ End-of-line (as opposed to end-of-record--see the discussion
+ of structure) will probably be rarely used with EBCDIC type
+ for purposes of denoting structure, but where it is
+ necessary the <NL> character should be used.
+
+ 3.1.1.3. IMAGE TYPE
+
+ The data are sent as contiguous bits which, for transfer,
+ are packed into the 8-bit transfer bytes. The receiving
+ site must store the data as contiguous bits. The structure
+ of the storage system might necessitate the padding of the
+ file (or of each record, for a record-structured file) to
+ some convenient boundary (byte, word or block). This
+ padding, which must be all zeros, may occur only at the end
+ of the file (or at the end of each record) and there must be
+ a way of identifying the padding bits so that they may be
+ stripped off if the file is retrieved. The padding
+ transformation should be well publicized to enable a user to
+ process a file at the storage site.
+
+ Image type is intended for the efficient storage and
+ retrieval of files and for the transfer of binary data. It
+ is recommended that this type be accepted by all FTP
+ implementations.
+
+ 3.1.1.4. LOCAL TYPE
+
+ The data is transferred in logical bytes of the size
+ specified by the obligatory second parameter, Byte size.
+ The value of Byte size must be a decimal integer; there is
+ no default value. The logical byte size is not necessarily
+ the same as the transfer byte size. If there is a
+ difference in byte sizes, then the logical bytes should be
+ packed contiguously, disregarding transfer byte boundaries
+ and with any necessary padding at the end.
+
+
+
+Postel & Reynolds [Page 12]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ When the data reaches the receiving host, it will be
+ transformed in a manner dependent on the logical byte size
+ and the particular host. This transformation must be
+ invertible (i.e., an identical file can be retrieved if the
+ same parameters are used) and should be well publicized by
+ the FTP implementors.
+
+ For example, a user sending 36-bit floating-point numbers to
+ a host with a 32-bit word could send that data as Local byte
+ with a logical byte size of 36. The receiving host would
+ then be expected to store the logical bytes so that they
+ could be easily manipulated; in this example putting the
+ 36-bit logical bytes into 64-bit double words should
+ suffice.
+
+ In another example, a pair of hosts with a 36-bit word size
+ may send data to one another in words by using TYPE L 36.
+ The data would be sent in the 8-bit transmission bytes
+ packed so that 9 transmission bytes carried two host words.
+
+ 3.1.1.5. FORMAT CONTROL
+
+ The types ASCII and EBCDIC also take a second (optional)
+ parameter; this is to indicate what kind of vertical format
+ control, if any, is associated with a file. The following
+ data representation types are defined in FTP:
+
+ A character file may be transferred to a host for one of
+ three purposes: for printing, for storage and later
+ retrieval, or for processing. If a file is sent for
+ printing, the receiving host must know how the vertical
+ format control is represented. In the second case, it must
+ be possible to store a file at a host and then retrieve it
+ later in exactly the same form. Finally, it should be
+ possible to move a file from one host to another and process
+ the file at the second host without undue trouble. A single
+ ASCII or EBCDIC format does not satisfy all these
+ conditions. Therefore, these types have a second parameter
+ specifying one of the following three formats:
+
+ 3.1.1.5.1. NON PRINT
+
+ This is the default format to be used if the second
+ (format) parameter is omitted. Non-print format must be
+ accepted by all FTP implementations.
+
+
+
+
+Postel & Reynolds [Page 13]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The file need contain no vertical format information. If
+ it is passed to a printer process, this process may
+ assume standard values for spacing and margins.
+
+ Normally, this format will be used with files destined
+ for processing or just storage.
+
+ 3.1.1.5.2. TELNET FORMAT CONTROLS
+
+ The file contains ASCII/EBCDIC vertical format controls
+ (i.e., <CR>, <LF>, <NL>, <VT>, <FF>) which the printer
+ process will interpret appropriately. <CRLF>, in exactly
+ this sequence, also denotes end-of-line.
+
+ 3.1.1.5.2. CARRIAGE CONTROL (ASA)
+
+ The file contains ASA (FORTRAN) vertical format control
+ characters. (See RFC 740 Appendix C; and Communications
+ of the ACM, Vol. 7, No. 10, p. 606, October 1964.) In a
+ line or a record formatted according to the ASA Standard,
+ the first character is not to be printed. Instead, it
+ should be used to determine the vertical movement of the
+ paper which should take place before the rest of the
+ record is printed.
+
+ The ASA Standard specifies the following control
+ characters:
+
+ Character Vertical Spacing
+
+ blank Move paper up one line
+ 0 Move paper up two lines
+ 1 Move paper to top of next page
+ + No movement, i.e., overprint
+
+ Clearly there must be some way for a printer process to
+ distinguish the end of the structural entity. If a file
+ has record structure (see below) this is no problem;
+ records will be explicitly marked during transfer and
+ storage. If the file has no record structure, the <CRLF>
+ end-of-line sequence is used to separate printing lines,
+ but these format effectors are overridden by the ASA
+ controls.
+
+
+
+
+
+
+Postel & Reynolds [Page 14]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 3.1.2. DATA STRUCTURES
+
+ In addition to different representation types, FTP allows the
+ structure of a file to be specified. Three file structures are
+ defined in FTP:
+
+ file-structure, where there is no internal structure and
+ the file is considered to be a
+ continuous sequence of data bytes,
+
+ record-structure, where the file is made up of sequential
+ records,
+
+ and page-structure, where the file is made up of independent
+ indexed pages.
+
+ File-structure is the default to be assumed if the STRUcture
+ command has not been used but both file and record structures
+ must be accepted for "text" files (i.e., files with TYPE ASCII
+ or EBCDIC) by all FTP implementations. The structure of a file
+ will affect both the transfer mode of a file (see the Section
+ on Transmission Modes) and the interpretation and storage of
+ the file.
+
+ The "natural" structure of a file will depend on which host
+ stores the file. A source-code file will usually be stored on
+ an IBM Mainframe in fixed length records but on a DEC TOPS-20
+ as a stream of characters partitioned into lines, for example
+ by <CRLF>. If the transfer of files between such disparate
+ sites is to be useful, there must be some way for one site to
+ recognize the other's assumptions about the file.
+
+ With some sites being naturally file-oriented and others
+ naturally record-oriented there may be problems if a file with
+ one structure is sent to a host oriented to the other. If a
+ text file is sent with record-structure to a host which is file
+ oriented, then that host should apply an internal
+ transformation to the file based on the record structure.
+ Obviously, this transformation should be useful, but it must
+ also be invertible so that an identical file may be retrieved
+ using record structure.
+
+ In the case of a file being sent with file-structure to a
+ record-oriented host, there exists the question of what
+ criteria the host should use to divide the file into records
+ which can be processed locally. If this division is necessary,
+ the FTP implementation should use the end-of-line sequence,
+
+
+Postel & Reynolds [Page 15]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ <CRLF> for ASCII, or <NL> for EBCDIC text files, as the
+ delimiter. If an FTP implementation adopts this technique, it
+ must be prepared to reverse the transformation if the file is
+ retrieved with file-structure.
+
+ 3.1.2.1. FILE STRUCTURE
+
+ File structure is the default to be assumed if the STRUcture
+ command has not been used.
+
+ In file-structure there is no internal structure and the
+ file is considered to be a continuous sequence of data
+ bytes.
+
+ 3.1.2.2. RECORD STRUCTURE
+
+ Record structures must be accepted for "text" files (i.e.,
+ files with TYPE ASCII or EBCDIC) by all FTP implementations.
+
+ In record-structure the file is made up of sequential
+ records.
+
+ 3.1.2.3. PAGE STRUCTURE
+
+ To transmit files that are discontinuous, FTP defines a page
+ structure. Files of this type are sometimes known as
+ "random access files" or even as "holey files". In these
+ files there is sometimes other information associated with
+ the file as a whole (e.g., a file descriptor), or with a
+ section of the file (e.g., page access controls), or both.
+ In FTP, the sections of the file are called pages.
+
+ To provide for various page sizes and associated
+ information, each page is sent with a page header. The page
+ header has the following defined fields:
+
+ Header Length
+
+ The number of logical bytes in the page header
+ including this byte. The minimum header length is 4.
+
+ Page Index
+
+ The logical page number of this section of the file.
+ This is not the transmission sequence number of this
+ page, but the index used to identify this page of the
+ file.
+
+
+Postel & Reynolds [Page 16]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Data Length
+
+ The number of logical bytes in the page data. The
+ minimum data length is 0.
+
+ Page Type
+
+ The type of page this is. The following page types
+ are defined:
+
+ 0 = Last Page
+
+ This is used to indicate the end of a paged
+ structured transmission. The header length must
+ be 4, and the data length must be 0.
+
+ 1 = Simple Page
+
+ This is the normal type for simple paged files
+ with no page level associated control
+ information. The header length must be 4.
+
+ 2 = Descriptor Page
+
+ This type is used to transmit the descriptive
+ information for the file as a whole.
+
+ 3 = Access Controlled Page
+
+ This type includes an additional header field
+ for paged files with page level access control
+ information. The header length must be 5.
+
+ Optional Fields
+
+ Further header fields may be used to supply per page
+ control information, for example, per page access
+ control.
+
+ All fields are one logical byte in length. The logical byte
+ size is specified by the TYPE command. See Appendix I for
+ further details and a specific case at the page structure.
+
+ A note of caution about parameters: a file must be stored and
+ retrieved with the same parameters if the retrieved version is to
+
+
+
+
+Postel & Reynolds [Page 17]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ be identical to the version originally transmitted. Conversely,
+ FTP implementations must return a file identical to the original
+ if the parameters used to store and retrieve a file are the same.
+
+ 3.2. ESTABLISHING DATA CONNECTIONS
+
+ The mechanics of transferring data consists of setting up the data
+ connection to the appropriate ports and choosing the parameters
+ for transfer. Both the user and the server-DTPs have a default
+ data port. The user-process default data port is the same as the
+ control connection port (i.e., U). The server-process default
+ data port is the port adjacent to the control connection port
+ (i.e., L-1).
+
+ The transfer byte size is 8-bit bytes. This byte size is relevant
+ only for the actual transfer of the data; it has no bearing on
+ representation of the data within a host's file system.
+
+ The passive data transfer process (this may be a user-DTP or a
+ second server-DTP) shall "listen" on the data port prior to
+ sending a transfer request command. The FTP request command
+ determines the direction of the data transfer. The server, upon
+ receiving the transfer request, will initiate the data connection
+ to the port. When the connection is established, the data
+ transfer begins between DTP's, and the server-PI sends a
+ confirming reply to the user-PI.
+
+ Every FTP implementation must support the use of the default data
+ ports, and only the USER-PI can initiate a change to non-default
+ ports.
+
+ It is possible for the user to specify an alternate data port by
+ use of the PORT command. The user may want a file dumped on a TAC
+ line printer or retrieved from a third party host. In the latter
+ case, the user-PI sets up control connections with both
+ server-PI's. One server is then told (by an FTP command) to
+ "listen" for a connection which the other will initiate. The
+ user-PI sends one server-PI a PORT command indicating the data
+ port of the other. Finally, both are sent the appropriate
+ transfer commands. The exact sequence of commands and replies
+ sent between the user-controller and the servers is defined in the
+ Section on FTP Replies.
+
+ In general, it is the server's responsibility to maintain the data
+ connection--to initiate it and to close it. The exception to this
+
+
+
+
+Postel & Reynolds [Page 18]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ is when the user-DTP is sending the data in a transfer mode that
+ requires the connection to be closed to indicate EOF. The server
+ MUST close the data connection under the following conditions:
+
+ 1. The server has completed sending data in a transfer mode
+ that requires a close to indicate EOF.
+
+ 2. The server receives an ABORT command from the user.
+
+ 3. The port specification is changed by a command from the
+ user.
+
+ 4. The control connection is closed legally or otherwise.
+
+ 5. An irrecoverable error condition occurs.
+
+ Otherwise the close is a server option, the exercise of which the
+ server must indicate to the user-process by either a 250 or 226
+ reply only.
+
+ 3.3. DATA CONNECTION MANAGEMENT
+
+ Default Data Connection Ports: All FTP implementations must
+ support use of the default data connection ports, and only the
+ User-PI may initiate the use of non-default ports.
+
+ Negotiating Non-Default Data Ports: The User-PI may specify a
+ non-default user side data port with the PORT command. The
+ User-PI may request the server side to identify a non-default
+ server side data port with the PASV command. Since a connection
+ is defined by the pair of addresses, either of these actions is
+ enough to get a different data connection, still it is permitted
+ to do both commands to use new ports on both ends of the data
+ connection.
+
+ Reuse of the Data Connection: When using the stream mode of data
+ transfer the end of the file must be indicated by closing the
+ connection. This causes a problem if multiple files are to be
+ transfered in the session, due to need for TCP to hold the
+ connection record for a time out period to guarantee the reliable
+ communication. Thus the connection can not be reopened at once.
+
+ There are two solutions to this problem. The first is to
+ negotiate a non-default port. The second is to use another
+ transfer mode.
+
+ A comment on transfer modes. The stream transfer mode is
+
+
+Postel & Reynolds [Page 19]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ inherently unreliable, since one can not determine if the
+ connection closed prematurely or not. The other transfer modes
+ (Block, Compressed) do not close the connection to indicate the
+ end of file. They have enough FTP encoding that the data
+ connection can be parsed to determine the end of the file.
+ Thus using these modes one can leave the data connection open
+ for multiple file transfers.
+
+ 3.4. TRANSMISSION MODES
+
+ The next consideration in transferring data is choosing the
+ appropriate transmission mode. There are three modes: one which
+ formats the data and allows for restart procedures; one which also
+ compresses the data for efficient transfer; and one which passes
+ the data with little or no processing. In this last case the mode
+ interacts with the structure attribute to determine the type of
+ processing. In the compressed mode, the representation type
+ determines the filler byte.
+
+ All data transfers must be completed with an end-of-file (EOF)
+ which may be explicitly stated or implied by the closing of the
+ data connection. For files with record structure, all the
+ end-of-record markers (EOR) are explicit, including the final one.
+ For files transmitted in page structure a "last-page" page type is
+ used.
+
+ NOTE: In the rest of this section, byte means "transfer byte"
+ except where explicitly stated otherwise.
+
+ For the purpose of standardized transfer, the sending host will
+ translate its internal end of line or end of record denotation
+ into the representation prescribed by the transfer mode and file
+ structure, and the receiving host will perform the inverse
+ translation to its internal denotation. An IBM Mainframe record
+ count field may not be recognized at another host, so the
+ end-of-record information may be transferred as a two byte control
+ code in Stream mode or as a flagged bit in a Block or Compressed
+ mode descriptor. End-of-line in an ASCII or EBCDIC file with no
+ record structure should be indicated by <CRLF> or <NL>,
+ respectively. Since these transformations imply extra work for
+ some systems, identical systems transferring non-record structured
+ text files might wish to use a binary representation and stream
+ mode for the transfer.
+
+
+
+
+
+
+Postel & Reynolds [Page 20]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The following transmission modes are defined in FTP:
+
+ 3.4.1. STREAM MODE
+
+ The data is transmitted as a stream of bytes. There is no
+ restriction on the representation type used; record structures
+ are allowed.
+
+ In a record structured file EOR and EOF will each be indicated
+ by a two-byte control code. The first byte of the control code
+ will be all ones, the escape character. The second byte will
+ have the low order bit on and zeros elsewhere for EOR and the
+ second low order bit on for EOF; that is, the byte will have
+ value 1 for EOR and value 2 for EOF. EOR and EOF may be
+ indicated together on the last byte transmitted by turning both
+ low order bits on (i.e., the value 3). If a byte of all ones
+ was intended to be sent as data, it should be repeated in the
+ second byte of the control code.
+
+ If the structure is a file structure, the EOF is indicated by
+ the sending host closing the data connection and all bytes are
+ data bytes.
+
+ 3.4.2. BLOCK MODE
+
+ The file is transmitted as a series of data blocks preceded by
+ one or more header bytes. The header bytes contain a count
+ field, and descriptor code. The count field indicates the
+ total length of the data block in bytes, thus marking the
+ beginning of the next data block (there are no filler bits).
+ The descriptor code defines: last block in the file (EOF) last
+ block in the record (EOR), restart marker (see the Section on
+ Error Recovery and Restart) or suspect data (i.e., the data
+ being transferred is suspected of errors and is not reliable).
+ This last code is NOT intended for error control within FTP.
+ It is motivated by the desire of sites exchanging certain types
+ of data (e.g., seismic or weather data) to send and receive all
+ the data despite local errors (such as "magnetic tape read
+ errors"), but to indicate in the transmission that certain
+ portions are suspect). Record structures are allowed in this
+ mode, and any representation type may be used.
+
+ The header consists of the three bytes. Of the 24 bits of
+ header information, the 16 low order bits shall represent byte
+ count, and the 8 high order bits shall represent descriptor
+ codes as shown below.
+
+
+
+Postel & Reynolds [Page 21]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Block Header
+
+ +----------------+----------------+----------------+
+ | Descriptor | Byte Count |
+ | 8 bits | 16 bits |
+ +----------------+----------------+----------------+
+
+
+ The descriptor codes are indicated by bit flags in the
+ descriptor byte. Four codes have been assigned, where each
+ code number is the decimal value of the corresponding bit in
+ the byte.
+
+ Code Meaning
+
+ 128 End of data block is EOR
+ 64 End of data block is EOF
+ 32 Suspected errors in data block
+ 16 Data block is a restart marker
+
+ With this encoding, more than one descriptor coded condition
+ may exist for a particular block. As many bits as necessary
+ may be flagged.
+
+ The restart marker is embedded in the data stream as an
+ integral number of 8-bit bytes representing printable
+ characters in the language being used over the control
+ connection (e.g., default--NVT-ASCII). <SP> (Space, in the
+ appropriate language) must not be used WITHIN a restart marker.
+
+ For example, to transmit a six-character marker, the following
+ would be sent:
+
+ +--------+--------+--------+
+ |Descrptr| Byte count |
+ |code= 16| = 6 |
+ +--------+--------+--------+
+
+ +--------+--------+--------+
+ | Marker | Marker | Marker |
+ | 8 bits | 8 bits | 8 bits |
+ +--------+--------+--------+
+
+ +--------+--------+--------+
+ | Marker | Marker | Marker |
+ | 8 bits | 8 bits | 8 bits |
+ +--------+--------+--------+
+
+
+Postel & Reynolds [Page 22]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 3.4.3. COMPRESSED MODE
+
+ There are three kinds of information to be sent: regular data,
+ sent in a byte string; compressed data, consisting of
+ replications or filler; and control information, sent in a
+ two-byte escape sequence. If n>0 bytes (up to 127) of regular
+ data are sent, these n bytes are preceded by a byte with the
+ left-most bit set to 0 and the right-most 7 bits containing the
+ number n.
+
+ Byte string:
+
+ 1 7 8 8
+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
+ |0| n | | d(1) | ... | d(n) |
+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
+ ^ ^
+ |---n bytes---|
+ of data
+
+ String of n data bytes d(1),..., d(n)
+ Count n must be positive.
+
+ To compress a string of n replications of the data byte d, the
+ following 2 bytes are sent:
+
+ Replicated Byte:
+
+ 2 6 8
+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
+ |1 0| n | | d |
+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
+
+ A string of n filler bytes can be compressed into a single
+ byte, where the filler byte varies with the representation
+ type. If the type is ASCII or EBCDIC the filler byte is <SP>
+ (Space, ASCII code 32, EBCDIC code 64). If the type is Image
+ or Local byte the filler is a zero byte.
+
+ Filler String:
+
+ 2 6
+ +-+-+-+-+-+-+-+-+
+ |1 1| n |
+ +-+-+-+-+-+-+-+-+
+
+ The escape sequence is a double byte, the first of which is the
+
+
+Postel & Reynolds [Page 23]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ escape byte (all zeros) and the second of which contains
+ descriptor codes as defined in Block mode. The descriptor
+ codes have the same meaning as in Block mode and apply to the
+ succeeding string of bytes.
+
+ Compressed mode is useful for obtaining increased bandwidth on
+ very large network transmissions at a little extra CPU cost.
+ It can be most effectively used to reduce the size of printer
+ files such as those generated by RJE hosts.
+
+ 3.5. ERROR RECOVERY AND RESTART
+
+ There is no provision for detecting bits lost or scrambled in data
+ transfer; this level of error control is handled by the TCP.
+ However, a restart procedure is provided to protect users from
+ gross system failures (including failures of a host, an
+ FTP-process, or the underlying network).
+
+ The restart procedure is defined only for the block and compressed
+ modes of data transfer. It requires the sender of data to insert
+ a special marker code in the data stream with some marker
+ information. The marker information has meaning only to the
+ sender, but must consist of printable characters in the default or
+ negotiated language of the control connection (ASCII or EBCDIC).
+ The marker could represent a bit-count, a record-count, or any
+ other information by which a system may identify a data
+ checkpoint. The receiver of data, if it implements the restart
+ procedure, would then mark the corresponding position of this
+ marker in the receiving system, and return this information to the
+ user.
+
+ In the event of a system failure, the user can restart the data
+ transfer by identifying the marker point with the FTP restart
+ procedure. The following example illustrates the use of the
+ restart procedure.
+
+ The sender of the data inserts an appropriate marker block in the
+ data stream at a convenient point. The receiving host marks the
+ corresponding data point in its file system and conveys the last
+ known sender and receiver marker information to the user, either
+ directly or over the control connection in a 110 reply (depending
+ on who is the sender). In the event of a system failure, the user
+ or controller process restarts the server at the last server
+ marker by sending a restart command with server's marker code as
+ its argument. The restart command is transmitted over the control
+
+
+
+
+Postel & Reynolds [Page 24]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ connection and is immediately followed by the command (such as
+ RETR, STOR or LIST) which was being executed when the system
+ failure occurred.
+
+4. FILE TRANSFER FUNCTIONS
+
+ The communication channel from the user-PI to the server-PI is
+ established as a TCP connection from the user to the standard server
+ port. The user protocol interpreter is responsible for sending FTP
+ commands and interpreting the replies received; the server-PI
+ interprets commands, sends replies and directs its DTP to set up the
+ data connection and transfer the data. If the second party to the
+ data transfer (the passive transfer process) is the user-DTP, then it
+ is governed through the internal protocol of the user-FTP host; if it
+ is a second server-DTP, then it is governed by its PI on command from
+ the user-PI. The FTP replies are discussed in the next section. In
+ the description of a few of the commands in this section, it is
+ helpful to be explicit about the possible replies.
+
+ 4.1. FTP COMMANDS
+
+ 4.1.1. ACCESS CONTROL COMMANDS
+
+ The following commands specify access control identifiers
+ (command codes are shown in parentheses).
+
+ USER NAME (USER)
+
+ The argument field is a Telnet string identifying the user.
+ The user identification is that which is required by the
+ server for access to its file system. This command will
+ normally be the first command transmitted by the user after
+ the control connections are made (some servers may require
+ this). Additional identification information in the form of
+ a password and/or an account command may also be required by
+ some servers. Servers may allow a new USER command to be
+ entered at any point in order to change the access control
+ and/or accounting information. This has the effect of
+ flushing any user, password, and account information already
+ supplied and beginning the login sequence again. All
+ transfer parameters are unchanged and any file transfer in
+ progress is completed under the old access control
+ parameters.
+
+
+
+
+
+
+Postel & Reynolds [Page 25]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ PASSWORD (PASS)
+
+ The argument field is a Telnet string specifying the user's
+ password. This command must be immediately preceded by the
+ user name command, and, for some sites, completes the user's
+ identification for access control. Since password
+ information is quite sensitive, it is desirable in general
+ to "mask" it or suppress typeout. It appears that the
+ server has no foolproof way to achieve this. It is
+ therefore the responsibility of the user-FTP process to hide
+ the sensitive password information.
+
+ ACCOUNT (ACCT)
+
+ The argument field is a Telnet string identifying the user's
+ account. The command is not necessarily related to the USER
+ command, as some sites may require an account for login and
+ others only for specific access, such as storing files. In
+ the latter case the command may arrive at any time.
+
+ There are reply codes to differentiate these cases for the
+ automation: when account information is required for login,
+ the response to a successful PASSword command is reply code
+ 332. On the other hand, if account information is NOT
+ required for login, the reply to a successful PASSword
+ command is 230; and if the account information is needed for
+ a command issued later in the dialogue, the server should
+ return a 332 or 532 reply depending on whether it stores
+ (pending receipt of the ACCounT command) or discards the
+ command, respectively.
+
+ CHANGE WORKING DIRECTORY (CWD)
+
+ This command allows the user to work with a different
+ directory or dataset for file storage or retrieval without
+ altering his login or accounting information. Transfer
+ parameters are similarly unchanged. The argument is a
+ pathname specifying a directory or other system dependent
+ file group designator.
+
+ CHANGE TO PARENT DIRECTORY (CDUP)
+
+ This command is a special case of CWD, and is included to
+ simplify the implementation of programs for transferring
+ directory trees between operating systems having different
+
+
+
+
+Postel & Reynolds [Page 26]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ syntaxes for naming the parent directory. The reply codes
+ shall be identical to the reply codes of CWD. See
+ Appendix II for further details.
+
+ STRUCTURE MOUNT (SMNT)
+
+ This command allows the user to mount a different file
+ system data structure without altering his login or
+ accounting information. Transfer parameters are similarly
+ unchanged. The argument is a pathname specifying a
+ directory or other system dependent file group designator.
+
+ REINITIALIZE (REIN)
+
+ This command terminates a USER, flushing all I/O and account
+ information, except to allow any transfer in progress to be
+ completed. All parameters are reset to the default settings
+ and the control connection is left open. This is identical
+ to the state in which a user finds himself immediately after
+ the control connection is opened. A USER command may be
+ expected to follow.
+
+ LOGOUT (QUIT)
+
+ This command terminates a USER and if file transfer is not
+ in progress, the server closes the control connection. If
+ file transfer is in progress, the connection will remain
+ open for result response and the server will then close it.
+ If the user-process is transferring files for several USERs
+ but does not wish to close and then reopen connections for
+ each, then the REIN command should be used instead of QUIT.
+
+ An unexpected close on the control connection will cause the
+ server to take the effective action of an abort (ABOR) and a
+ logout (QUIT).
+
+ 4.1.2. TRANSFER PARAMETER COMMANDS
+
+ All data transfer parameters have default values, and the
+ commands specifying data transfer parameters are required only
+ if the default parameter values are to be changed. The default
+ value is the last specified value, or if no value has been
+ specified, the standard default value is as stated here. This
+ implies that the server must "remember" the applicable default
+ values. The commands may be in any order except that they must
+ precede the FTP service request. The following commands
+ specify data transfer parameters:
+
+
+Postel & Reynolds [Page 27]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ DATA PORT (PORT)
+
+ The argument is a HOST-PORT specification for the data port
+ to be used in data connection. There are defaults for both
+ the user and server data ports, and under normal
+ circumstances this command and its reply are not needed. If
+ this command is used, the argument is the concatenation of a
+ 32-bit internet host address and a 16-bit TCP port address.
+ This address information is broken into 8-bit fields and the
+ value of each field is transmitted as a decimal number (in
+ character string representation). The fields are separated
+ by commas. A port command would be:
+
+ PORT h1,h2,h3,h4,p1,p2
+
+ where h1 is the high order 8 bits of the internet host
+ address.
+
+ PASSIVE (PASV)
+
+ This command requests the server-DTP to "listen" on a data
+ port (which is not its default data port) and to wait for a
+ connection rather than initiate one upon receipt of a
+ transfer command. The response to this command includes the
+ host and port address this server is listening on.
+
+ REPRESENTATION TYPE (TYPE)
+
+ The argument specifies the representation type as described
+ in the Section on Data Representation and Storage. Several
+ types take a second parameter. The first parameter is
+ denoted by a single Telnet character, as is the second
+ Format parameter for ASCII and EBCDIC; the second parameter
+ for local byte is a decimal integer to indicate Bytesize.
+ The parameters are separated by a <SP> (Space, ASCII code
+ 32).
+
+ The following codes are assigned for type:
+
+ \ /
+ A - ASCII | | N - Non-print
+ |-><-| T - Telnet format effectors
+ E - EBCDIC| | C - Carriage Control (ASA)
+ / \
+ I - Image
+
+ L <byte size> - Local byte Byte size
+
+
+Postel & Reynolds [Page 28]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The default representation type is ASCII Non-print. If the
+ Format parameter is changed, and later just the first
+ argument is changed, Format then returns to the Non-print
+ default.
+
+ FILE STRUCTURE (STRU)
+
+ The argument is a single Telnet character code specifying
+ file structure described in the Section on Data
+ Representation and Storage.
+
+ The following codes are assigned for structure:
+
+ F - File (no record structure)
+ R - Record structure
+ P - Page structure
+
+ The default structure is File.
+
+ TRANSFER MODE (MODE)
+
+ The argument is a single Telnet character code specifying
+ the data transfer modes described in the Section on
+ Transmission Modes.
+
+ The following codes are assigned for transfer modes:
+
+ S - Stream
+ B - Block
+ C - Compressed
+
+ The default transfer mode is Stream.
+
+ 4.1.3. FTP SERVICE COMMANDS
+
+ The FTP service commands define the file transfer or the file
+ system function requested by the user. The argument of an FTP
+ service command will normally be a pathname. The syntax of
+ pathnames must conform to server site conventions (with
+ standard defaults applicable), and the language conventions of
+ the control connection. The suggested default handling is to
+ use the last specified device, directory or file name, or the
+ standard default defined for local users. The commands may be
+ in any order except that a "rename from" command must be
+ followed by a "rename to" command and the restart command must
+ be followed by the interrupted service command (e.g., STOR or
+ RETR). The data, when transferred in response to FTP service
+
+
+Postel & Reynolds [Page 29]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ commands, shall always be sent over the data connection, except
+ for certain informative replies. The following commands
+ specify FTP service requests:
+
+ RETRIEVE (RETR)
+
+ This command causes the server-DTP to transfer a copy of the
+ file, specified in the pathname, to the server- or user-DTP
+ at the other end of the data connection. The status and
+ contents of the file at the server site shall be unaffected.
+
+ STORE (STOR)
+
+ This command causes the server-DTP to accept the data
+ transferred via the data connection and to store the data as
+ a file at the server site. If the file specified in the
+ pathname exists at the server site, then its contents shall
+ be replaced by the data being transferred. A new file is
+ created at the server site if the file specified in the
+ pathname does not already exist.
+
+ STORE UNIQUE (STOU)
+
+ This command behaves like STOR except that the resultant
+ file is to be created in the current directory under a name
+ unique to that directory. The 250 Transfer Started response
+ must include the name generated.
+
+ APPEND (with create) (APPE)
+
+ This command causes the server-DTP to accept the data
+ transferred via the data connection and to store the data in
+ a file at the server site. If the file specified in the
+ pathname exists at the server site, then the data shall be
+ appended to that file; otherwise the file specified in the
+ pathname shall be created at the server site.
+
+ ALLOCATE (ALLO)
+
+ This command may be required by some servers to reserve
+ sufficient storage to accommodate the new file to be
+ transferred. The argument shall be a decimal integer
+ representing the number of bytes (using the logical byte
+ size) of storage to be reserved for the file. For files
+ sent with record or page structure a maximum record or page
+ size (in logical bytes) might also be necessary; this is
+ indicated by a decimal integer in a second argument field of
+
+
+Postel & Reynolds [Page 30]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ the command. This second argument is optional, but when
+ present should be separated from the first by the three
+ Telnet characters <SP> R <SP>. This command shall be
+ followed by a STORe or APPEnd command. The ALLO command
+ should be treated as a NOOP (no operation) by those servers
+ which do not require that the maximum size of the file be
+ declared beforehand, and those servers interested in only
+ the maximum record or page size should accept a dummy value
+ in the first argument and ignore it.
+
+ RESTART (REST)
+
+ The argument field represents the server marker at which
+ file transfer is to be restarted. This command does not
+ cause file transfer but skips over the file to the specified
+ data checkpoint. This command shall be immediately followed
+ by the appropriate FTP service command which shall cause
+ file transfer to resume.
+
+ RENAME FROM (RNFR)
+
+ This command specifies the old pathname of the file which is
+ to be renamed. This command must be immediately followed by
+ a "rename to" command specifying the new file pathname.
+
+ RENAME TO (RNTO)
+
+ This command specifies the new pathname of the file
+ specified in the immediately preceding "rename from"
+ command. Together the two commands cause a file to be
+ renamed.
+
+ ABORT (ABOR)
+
+ This command tells the server to abort the previous FTP
+ service command and any associated transfer of data. The
+ abort command may require "special action", as discussed in
+ the Section on FTP Commands, to force recognition by the
+ server. No action is to be taken if the previous command
+ has been completed (including data transfer). The control
+ connection is not to be closed by the server, but the data
+ connection must be closed.
+
+ There are two cases for the server upon receipt of this
+ command: (1) the FTP service command was already completed,
+ or (2) the FTP service command is still in progress.
+
+
+
+Postel & Reynolds [Page 31]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ In the first case, the server closes the data connection
+ (if it is open) and responds with a 226 reply, indicating
+ that the abort command was successfully processed.
+
+ In the second case, the server aborts the FTP service in
+ progress and closes the data connection, returning a 426
+ reply to indicate that the service request terminated
+ abnormally. The server then sends a 226 reply,
+ indicating that the abort command was successfully
+ processed.
+
+ DELETE (DELE)
+
+ This command causes the file specified in the pathname to be
+ deleted at the server site. If an extra level of protection
+ is desired (such as the query, "Do you really wish to
+ delete?"), it should be provided by the user-FTP process.
+
+ REMOVE DIRECTORY (RMD)
+
+ This command causes the directory specified in the pathname
+ to be removed as a directory (if the pathname is absolute)
+ or as a subdirectory of the current working directory (if
+ the pathname is relative). See Appendix II.
+
+ MAKE DIRECTORY (MKD)
+
+ This command causes the directory specified in the pathname
+ to be created as a directory (if the pathname is absolute)
+ or as a subdirectory of the current working directory (if
+ the pathname is relative). See Appendix II.
+
+ PRINT WORKING DIRECTORY (PWD)
+
+ This command causes the name of the current working
+ directory to be returned in the reply. See Appendix II.
+
+ LIST (LIST)
+
+ This command causes a list to be sent from the server to the
+ passive DTP. If the pathname specifies a directory or other
+ group of files, the server should transfer a list of files
+ in the specified directory. If the pathname specifies a
+ file then the server should send current information on the
+ file. A null argument implies the user's current working or
+ default directory. The data transfer is over the data
+ connection in type ASCII or type EBCDIC. (The user must
+
+
+Postel & Reynolds [Page 32]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ ensure that the TYPE is appropriately ASCII or EBCDIC).
+ Since the information on a file may vary widely from system
+ to system, this information may be hard to use automatically
+ in a program, but may be quite useful to a human user.
+
+ NAME LIST (NLST)
+
+ This command causes a directory listing to be sent from
+ server to user site. The pathname should specify a
+ directory or other system-specific file group descriptor; a
+ null argument implies the current directory. The server
+ will return a stream of names of files and no other
+ information. The data will be transferred in ASCII or
+ EBCDIC type over the data connection as valid pathname
+ strings separated by <CRLF> or <NL>. (Again the user must
+ ensure that the TYPE is correct.) This command is intended
+ to return information that can be used by a program to
+ further process the files automatically. For example, in
+ the implementation of a "multiple get" function.
+
+ SITE PARAMETERS (SITE)
+
+ This command is used by the server to provide services
+ specific to his system that are essential to file transfer
+ but not sufficiently universal to be included as commands in
+ the protocol. The nature of these services and the
+ specification of their syntax can be stated in a reply to
+ the HELP SITE command.
+
+ SYSTEM (SYST)
+
+ This command is used to find out the type of operating
+ system at the server. The reply shall have as its first
+ word one of the system names listed in the current version
+ of the Assigned Numbers document [4].
+
+ STATUS (STAT)
+
+ This command shall cause a status response to be sent over
+ the control connection in the form of a reply. The command
+ may be sent during a file transfer (along with the Telnet IP
+ and Synch signals--see the Section on FTP Commands) in which
+ case the server will respond with the status of the
+ operation in progress, or it may be sent between file
+ transfers. In the latter case, the command may have an
+ argument field. If the argument is a pathname, the command
+ is analogous to the "list" command except that data shall be
+
+
+Postel & Reynolds [Page 33]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ transferred over the control connection. If a partial
+ pathname is given, the server may respond with a list of
+ file names or attributes associated with that specification.
+ If no argument is given, the server should return general
+ status information about the server FTP process. This
+ should include current values of all transfer parameters and
+ the status of connections.
+
+ HELP (HELP)
+
+ This command shall cause the server to send helpful
+ information regarding its implementation status over the
+ control connection to the user. The command may take an
+ argument (e.g., any command name) and return more specific
+ information as a response. The reply is type 211 or 214.
+ It is suggested that HELP be allowed before entering a USER
+ command. The server may use this reply to specify
+ site-dependent parameters, e.g., in response to HELP SITE.
+
+ NOOP (NOOP)
+
+ This command does not affect any parameters or previously
+ entered commands. It specifies no action other than that the
+ server send an OK reply.
+
+ The File Transfer Protocol follows the specifications of the Telnet
+ protocol for all communications over the control connection. Since
+ the language used for Telnet communication may be a negotiated
+ option, all references in the next two sections will be to the
+ "Telnet language" and the corresponding "Telnet end-of-line code".
+ Currently, one may take these to mean NVT-ASCII and <CRLF>. No other
+ specifications of the Telnet protocol will be cited.
+
+ FTP commands are "Telnet strings" terminated by the "Telnet end of
+ line code". The command codes themselves are alphabetic characters
+ terminated by the character <SP> (Space) if parameters follow and
+ Telnet-EOL otherwise. The command codes and the semantics of
+ commands are described in this section; the detailed syntax of
+ commands is specified in the Section on Commands, the reply sequences
+ are discussed in the Section on Sequencing of Commands and Replies,
+ and scenarios illustrating the use of commands are provided in the
+ Section on Typical FTP Scenarios.
+
+ FTP commands may be partitioned as those specifying access-control
+ identifiers, data transfer parameters, or FTP service requests.
+ Certain commands (such as ABOR, STAT, QUIT) may be sent over the
+ control connection while a data transfer is in progress. Some
+
+
+Postel & Reynolds [Page 34]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ servers may not be able to monitor the control and data connections
+ simultaneously, in which case some special action will be necessary
+ to get the server's attention. The following ordered format is
+ tentatively recommended:
+
+ 1. User system inserts the Telnet "Interrupt Process" (IP) signal
+ in the Telnet stream.
+
+ 2. User system sends the Telnet "Synch" signal.
+
+ 3. User system inserts the command (e.g., ABOR) in the Telnet
+ stream.
+
+ 4. Server PI, after receiving "IP", scans the Telnet stream for
+ EXACTLY ONE FTP command.
+
+ (For other servers this may not be necessary but the actions listed
+ above should have no unusual effect.)
+
+ 4.2. FTP REPLIES
+
+ Replies to File Transfer Protocol commands are devised to ensure
+ the synchronization of requests and actions in the process of file
+ transfer, and to guarantee that the user process always knows the
+ state of the Server. Every command must generate at least one
+ reply, although there may be more than one; in the latter case,
+ the multiple replies must be easily distinguished. In addition,
+ some commands occur in sequential groups, such as USER, PASS and
+ ACCT, or RNFR and RNTO. The replies show the existence of an
+ intermediate state if all preceding commands have been successful.
+ A failure at any point in the sequence necessitates the repetition
+ of the entire sequence from the beginning.
+
+ The details of the command-reply sequence are made explicit in
+ a set of state diagrams below.
+
+ An FTP reply consists of a three digit number (transmitted as
+ three alphanumeric characters) followed by some text. The number
+ is intended for use by automata to determine what state to enter
+ next; the text is intended for the human user. It is intended
+ that the three digits contain enough encoded information that the
+ user-process (the User-PI) will not need to examine the text and
+ may either discard it or pass it on to the user, as appropriate.
+ In particular, the text may be server-dependent, so there are
+ likely to be varying texts for each reply code.
+
+ A reply is defined to contain the 3-digit code, followed by Space
+
+
+Postel & Reynolds [Page 35]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ <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,
+
+
+Postel & Reynolds [Page 36]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ redo, retrench, etc.) by simply examining this first digit. A
+ user-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
+
+
+Postel & Reynolds [Page 37]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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
+
+
+Postel & Reynolds [Page 38]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 39]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 40]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 41]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 42]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 43]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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:
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 44]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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
+
+ Figure 3
+
+ 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:
+
+
+Postel & Reynolds [Page 45]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 46]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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>
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 47]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 48]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ 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.
+
+ Spontaneous Replies
+
+ Sometimes "the system" spontaneously has a message to be sent
+ to a user (usually all users). For example, "System going down
+ in 15 minutes". There is no provision in FTP for such
+ spontaneous information to be sent from the server to the user.
+ It is recommended that such information be queued in the
+ server-PI and delivered to the user-PI in the next reply
+ (possibly making it a multi-line reply).
+
+ The table below lists alternative success and failure replies for
+ each command. These must be strictly adhered to; a server may
+ substitute text in the replies, but the meaning and action implied
+ by the code numbers and by the specific command reply sequence
+ cannot be altered.
+
+ Command-Reply Sequences
+
+ In this section, the command-reply sequence is presented. Each
+ command is listed with its possible replies; command groups are
+ listed together. Preliminary replies are listed first (with
+ their succeeding replies indented and under them), then
+ positive and negative completion, and finally intermediary
+
+
+
+
+Postel & Reynolds [Page 49]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ replies with the remaining commands from the sequence
+ following. This listing forms the basis for the state
+ diagrams, which will be presented separately.
+
+ Connection Establishment
+ 120
+ 220
+ 220
+ 421
+ Login
+ USER
+ 230
+ 530
+ 500, 501, 421
+ 331, 332
+ PASS
+ 230
+ 202
+ 530
+ 500, 501, 503, 421
+ 332
+ ACCT
+ 230
+ 202
+ 530
+ 500, 501, 503, 421
+ CWD
+ 250
+ 500, 501, 502, 421, 530, 550
+ CDUP
+ 200
+ 500, 501, 502, 421, 530, 550
+ SMNT
+ 202, 250
+ 500, 501, 502, 421, 530, 550
+ Logout
+ REIN
+ 120
+ 220
+ 220
+ 421
+ 500, 502
+ QUIT
+ 221
+ 500
+
+
+
+
+Postel & Reynolds [Page 50]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Transfer parameters
+ PORT
+ 200
+ 500, 501, 421, 530
+ PASV
+ 227
+ 500, 501, 502, 421, 530
+ MODE
+ 200
+ 500, 501, 504, 421, 530
+ TYPE
+ 200
+ 500, 501, 504, 421, 530
+ STRU
+ 200
+ 500, 501, 504, 421, 530
+ File action commands
+ ALLO
+ 200
+ 202
+ 500, 501, 504, 421, 530
+ REST
+ 500, 501, 502, 421, 530
+ 350
+ STOR
+ 125, 150
+ (110)
+ 226, 250
+ 425, 426, 451, 551, 552
+ 532, 450, 452, 553
+ 500, 501, 421, 530
+ STOU
+ 125, 150
+ (110)
+ 226, 250
+ 425, 426, 451, 551, 552
+ 532, 450, 452, 553
+ 500, 501, 421, 530
+ RETR
+ 125, 150
+ (110)
+ 226, 250
+ 425, 426, 451
+ 450, 550
+ 500, 501, 421, 530
+
+
+
+
+Postel & Reynolds [Page 51]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ LIST
+ 125, 150
+ 226, 250
+ 425, 426, 451
+ 450
+ 500, 501, 502, 421, 530
+ NLST
+ 125, 150
+ 226, 250
+ 425, 426, 451
+ 450
+ 500, 501, 502, 421, 530
+ APPE
+ 125, 150
+ (110)
+ 226, 250
+ 425, 426, 451, 551, 552
+ 532, 450, 550, 452, 553
+ 500, 501, 502, 421, 530
+ RNFR
+ 450, 550
+ 500, 501, 502, 421, 530
+ 350
+ RNTO
+ 250
+ 532, 553
+ 500, 501, 502, 503, 421, 530
+ DELE
+ 250
+ 450, 550
+ 500, 501, 502, 421, 530
+ RMD
+ 250
+ 500, 501, 502, 421, 530, 550
+ MKD
+ 257
+ 500, 501, 502, 421, 530, 550
+ PWD
+ 257
+ 500, 501, 502, 421, 550
+ ABOR
+ 225, 226
+ 500, 501, 502, 421
+
+
+
+
+
+
+Postel & Reynolds [Page 52]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Informational commands
+ SYST
+ 215
+ 500, 501, 502, 421
+ STAT
+ 211, 212, 213
+ 450
+ 500, 501, 502, 421, 530
+ HELP
+ 211, 214
+ 500, 501, 502, 421
+ Miscellaneous commands
+ SITE
+ 200
+ 202
+ 500, 501, 530
+ NOOP
+ 200
+ 500 421
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 53]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+6. STATE DIAGRAMS
+
+ Here we present state diagrams for a very simple minded FTP
+ implementation. Only the first digit of the reply codes is used.
+ There is one state diagram for each group of FTP commands or command
+ sequences.
+
+ The command groupings were determined by constructing a model for
+ each command then collecting together the commands with structurally
+ identical models.
+
+ For each command or command sequence there are three possible
+ outcomes: success (S), failure (F), and error (E). In the state
+ diagrams below we use the symbol B for "begin", and the symbol W for
+ "wait for reply".
+
+ We first present the diagram that represents the largest group of FTP
+ commands:
+
+
+ 1,3 +---+
+ ----------->| E |
+ | +---+
+ |
+ +---+ cmd +---+ 2 +---+
+ | B |---------->| W |---------->| S |
+ +---+ +---+ +---+
+ |
+ | 4,5 +---+
+ ----------->| F |
+ +---+
+
+
+ This diagram models the commands:
+
+ ABOR, ALLO, DELE, CWD, CDUP, SMNT, HELP, MODE, NOOP, PASV,
+ QUIT, SITE, PORT, SYST, STAT, RMD, MKD, PWD, STRU, and TYPE.
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 54]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The other large group of commands is represented by a very similar
+ diagram:
+
+
+ 3 +---+
+ ----------->| E |
+ | +---+
+ |
+ +---+ cmd +---+ 2 +---+
+ | B |---------->| W |---------->| S |
+ +---+ --->+---+ +---+
+ | | |
+ | | | 4,5 +---+
+ | 1 | ----------->| F |
+ ----- +---+
+
+
+ This diagram models the commands:
+
+ APPE, LIST, NLST, REIN, RETR, STOR, and STOU.
+
+ Note that this second model could also be used to represent the first
+ group of commands, the only difference being that in the first group
+ the 100 series replies are unexpected and therefore treated as error,
+ while the second group expects (some may require) 100 series replies.
+ Remember that at most, one 100 series reply is allowed per command.
+
+ The remaining diagrams model command sequences, perhaps the simplest
+ of these is the rename sequence:
+
+
+ +---+ RNFR +---+ 1,2 +---+
+ | B |---------->| W |---------->| E |
+ +---+ +---+ -->+---+
+ | | |
+ 3 | | 4,5 |
+ -------------- ------ |
+ | | | +---+
+ | ------------->| S |
+ | | 1,3 | | +---+
+ | 2| --------
+ | | | |
+ V | | |
+ +---+ RNTO +---+ 4,5 ----->+---+
+ | |---------->| W |---------->| F |
+ +---+ +---+ +---+
+
+
+
+Postel & Reynolds [Page 55]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The next diagram is a simple model of the Restart command:
+
+
+ +---+ REST +---+ 1,2 +---+
+ | B |---------->| W |---------->| E |
+ +---+ +---+ -->+---+
+ | | |
+ 3 | | 4,5 |
+ -------------- ------ |
+ | | | +---+
+ | ------------->| S |
+ | | 3 | | +---+
+ | 2| --------
+ | | | |
+ V | | |
+ +---+ cmd +---+ 4,5 ----->+---+
+ | |---------->| W |---------->| F |
+ +---+ -->+---+ +---+
+ | |
+ | 1 |
+ ------
+
+
+ Where "cmd" is APPE, STOR, or RETR.
+
+ We note that the above three models are similar. The Restart differs
+ from the Rename two only in the treatment of 100 series replies at
+ the second stage, while the second group expects (some may require)
+ 100 series replies. Remember that at most, one 100 series reply is
+ allowed per command.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 56]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The most complicated diagram is for the Login sequence:
+
+
+ 1
+ +---+ USER +---+------------->+---+
+ | B |---------->| W | 2 ---->| E |
+ +---+ +---+------ | -->+---+
+ | | | | |
+ 3 | | 4,5 | | |
+ -------------- ----- | | |
+ | | | | |
+ | | | | |
+ | --------- |
+ | 1| | | |
+ V | | | |
+ +---+ PASS +---+ 2 | ------>+---+
+ | |---------->| W |------------->| S |
+ +---+ +---+ ---------->+---+
+ | | | | |
+ 3 | |4,5| | |
+ -------------- -------- |
+ | | | | |
+ | | | | |
+ | -----------
+ | 1,3| | | |
+ V | 2| | |
+ +---+ ACCT +---+-- | ----->+---+
+ | |---------->| W | 4,5 -------->| F |
+ +---+ +---+------------->+---+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 57]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Finally, we present a generalized diagram that could be used to model
+ the command and reply interchange:
+
+
+ ------------------------------------
+ | |
+ Begin | |
+ | V |
+ | +---+ cmd +---+ 2 +---+ |
+ -->| |------->| |---------->| | |
+ | | | W | | S |-----|
+ -->| | -->| |----- | | |
+ | +---+ | +---+ 4,5 | +---+ |
+ | | | | | | |
+ | | | 1| |3 | +---+ |
+ | | | | | | | | |
+ | | ---- | ---->| F |-----
+ | | | | |
+ | | | +---+
+ -------------------
+ |
+ |
+ V
+ End
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 58]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+7. TYPICAL FTP SCENARIO
+
+ User at host U wanting to transfer files to/from host S:
+
+ In general, the user will communicate to the server via a mediating
+ user-FTP process. The following may be a typical scenario. The
+ user-FTP prompts are shown in parentheses, '---->' represents
+ commands from host U to host S, and '<----' represents replies from
+ host S to host U.
+
+ LOCAL COMMANDS BY USER ACTION INVOLVED
+
+ ftp (host) multics<CR> Connect to host S, port L,
+ establishing control connections.
+ <---- 220 Service ready <CRLF>.
+ username Doe <CR> USER Doe<CRLF>---->
+ <---- 331 User name ok,
+ need password<CRLF>.
+ password mumble <CR> PASS mumble<CRLF>---->
+ <---- 230 User logged in<CRLF>.
+ retrieve (local type) ASCII<CR>
+ (local pathname) test 1 <CR> User-FTP opens local file in ASCII.
+ (for. pathname) test.pl1<CR> RETR test.pl1<CRLF> ---->
+ <---- 150 File status okay;
+ about to open data
+ connection<CRLF>.
+ Server makes data connection
+ to port U.
+
+ <---- 226 Closing data connection,
+ file transfer successful<CRLF>.
+ type Image<CR> TYPE I<CRLF> ---->
+ <---- 200 Command OK<CRLF>
+ store (local type) image<CR>
+ (local pathname) file dump<CR> User-FTP opens local file in Image.
+ (for.pathname) >udd>cn>fd<CR> STOR >udd>cn>fd<CRLF> ---->
+ <---- 550 Access denied<CRLF>
+ terminate QUIT <CRLF> ---->
+ Server closes all
+ connections.
+
+8. CONNECTION ESTABLISHMENT
+
+ The FTP control connection is established via TCP between the user
+ process port U and the server process port L. This protocol is
+ assigned the service port 21 (25 octal), that is L=21.
+
+
+
+Postel & Reynolds [Page 59]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+APPENDIX I - PAGE STRUCTURE
+
+ The need for FTP to support page structure derives principally from
+ the need to support efficient transmission of files between TOPS-20
+ systems, particularly the files used by NLS.
+
+ The file system of TOPS-20 is based on the concept of pages. The
+ operating system is most efficient at manipulating files as pages.
+ The operating system provides an interface to the file system so that
+ many applications view files as sequential streams of characters.
+ However, a few applications use the underlying page structures
+ directly, and some of these create holey files.
+
+ A TOPS-20 disk file consists of four things: a pathname, a page
+ table, a (possibly empty) set of pages, and a set of attributes.
+
+ The pathname is specified in the RETR or STOR command. It includes
+ the directory name, file name, file name extension, and generation
+ number.
+
+ The page table contains up to 2**18 entries. Each entry may be
+ EMPTY, or may point to a page. If it is not empty, there are also
+ some page-specific access bits; not all pages of a file need have the
+ same access protection.
+
+ A page is a contiguous set of 512 words of 36 bits each.
+
+ The attributes of the file, in the File Descriptor Block (FDB),
+ contain such things as creation time, write time, read time, writer's
+ byte-size, end-of-file pointer, count of reads and writes, backup
+ system tape numbers, etc.
+
+ Note that there is NO requirement that entries in the page table be
+ contiguous. There may be empty page table slots between occupied
+ ones. Also, the end of file pointer is simply a number. There is no
+ requirement that it in fact point at the "last" datum in the file.
+ Ordinary sequential I/O calls in TOPS-20 will cause the end of file
+ pointer to be left after the last datum written, but other operations
+ may cause it not to be so, if a particular programming system so
+ requires.
+
+ In fact, in both of these special cases, "holey" files and
+ end-of-file pointers NOT at the end of the file, occur with NLS data
+ files.
+
+
+
+
+
+Postel & Reynolds [Page 60]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The TOPS-20 paged files can be sent with the FTP transfer parameters:
+ TYPE L 36, STRU P, and MODE S (in fact, any mode could be used).
+
+ Each page of information has a header. Each header field, which is a
+ logical byte, is a TOPS-20 word, since the TYPE is L 36.
+
+ The header fields are:
+
+ Word 0: Header Length.
+
+ The header length is 5.
+
+ Word 1: Page Index.
+
+ If the data is a disk file page, this is the number of that
+ page in the file's page map. Empty pages (holes) in the file
+ are simply not sent. Note that a hole is NOT the same as a
+ page of zeros.
+
+ Word 2: Data Length.
+
+ The number of data words in this page, following the header.
+ Thus, the total length of the transmission unit is the Header
+ Length plus the Data Length.
+
+ Word 3: Page Type.
+
+ A code for what type of chunk this is. A data page is type 3,
+ the FDB page is type 2.
+
+ Word 4: Page Access Control.
+
+ The access bits associated with the page in the file's page
+ map. (This full word quantity is put into AC2 of an SPACS by
+ the program reading from net to disk.)
+
+ After the header are Data Length data words. Data Length is
+ currently either 512 for a data page or 31 for an FDB. Trailing
+ zeros in a disk file page may be discarded, making Data Length less
+ than 512 in that case.
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 61]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+APPENDIX II - DIRECTORY COMMANDS
+
+ Since UNIX has a tree-like directory structure in which directories
+ are as easy to manipulate as ordinary files, it is useful to expand
+ the FTP servers on these machines to include commands which deal with
+ the creation of directories. Since there are other hosts on the
+ ARPA-Internet which have tree-like directories (including TOPS-20 and
+ Multics), these commands are as general as possible.
+
+ Four directory commands have been added to FTP:
+
+ MKD pathname
+
+ Make a directory with the name "pathname".
+
+ RMD pathname
+
+ Remove the directory with the name "pathname".
+
+ PWD
+
+ Print the current working directory name.
+
+ CDUP
+
+ Change to the parent of the current working directory.
+
+ The "pathname" argument should be created (removed) as a
+ subdirectory of the current working directory, unless the "pathname"
+ string contains sufficient information to specify otherwise to the
+ server, e.g., "pathname" is an absolute pathname (in UNIX and
+ Multics), or pathname is something like "<abso.lute.path>" to
+ TOPS-20.
+
+ REPLY CODES
+
+ The CDUP command is a special case of CWD, and is included to
+ simplify the implementation of programs for transferring directory
+ trees between operating systems having different syntaxes for
+ naming the parent directory. The reply codes for CDUP be
+ identical to the reply codes of CWD.
+
+ The reply codes for RMD be identical to the reply codes for its
+ file analogue, DELE.
+
+ The reply codes for MKD, however, are a bit more complicated. A
+ freshly created directory will probably be the object of a future
+
+
+Postel & Reynolds [Page 62]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ CWD command. Unfortunately, the argument to MKD may not always be
+ a suitable argument for CWD. This is the case, for example, when
+ a TOPS-20 subdirectory is created by giving just the subdirectory
+ name. That is, with a TOPS-20 server FTP, the command sequence
+
+ MKD MYDIR
+ CWD MYDIR
+
+ will fail. The new directory may only be referred to by its
+ "absolute" name; e.g., if the MKD command above were issued while
+ connected to the directory <DFRANKLIN>, the new subdirectory
+ could only be referred to by the name <DFRANKLIN.MYDIR>.
+
+ Even on UNIX and Multics, however, the argument given to MKD may
+ not be suitable. If it is a "relative" pathname (i.e., a pathname
+ which is interpreted relative to the current directory), the user
+ would need to be in the same current directory in order to reach
+ the subdirectory. Depending on the application, this may be
+ inconvenient. It is not very robust in any case.
+
+ To solve these problems, upon successful completion of an MKD
+ command, the server should return a line of the form:
+
+ 257<space>"<directory-name>"<space><commentary>
+
+ That is, the server will tell the user what string to use when
+ referring to the created directory. The directory name can
+ contain any character; embedded double-quotes should be escaped by
+ double-quotes (the "quote-doubling" convention).
+
+ For example, a user connects to the directory /usr/dm, and creates
+ a subdirectory, named pathname:
+
+ CWD /usr/dm
+ 200 directory changed to /usr/dm
+ MKD pathname
+ 257 "/usr/dm/pathname" directory created
+
+ An example with an embedded double quote:
+
+ MKD foo"bar
+ 257 "/usr/dm/foo""bar" directory created
+ CWD /usr/dm/foo"bar
+ 200 directory changed to /usr/dm/foo"bar
+
+
+
+
+
+Postel & Reynolds [Page 63]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ The prior existence of a subdirectory with the same name is an
+ error, and the server must return an "access denied" error reply
+ in that case.
+
+ CWD /usr/dm
+ 200 directory changed to /usr/dm
+ MKD pathname
+ 521-"/usr/dm/pathname" directory already exists;
+ 521 taking no action.
+
+ The failure replies for MKD are analogous to its file creating
+ cousin, STOR. Also, an "access denied" return is given if a file
+ name with the same name as the subdirectory will conflict with the
+ creation of the subdirectory (this is a problem on UNIX, but
+ shouldn't be one on TOPS-20).
+
+ Essentially because the PWD command returns the same type of
+ information as the successful MKD command, the successful PWD
+ command uses the 257 reply code as well.
+
+ SUBTLETIES
+
+ Because these commands will be most useful in transferring
+ subtrees from one machine to another, carefully observe that the
+ argument to MKD is to be interpreted as a sub-directory of the
+ current working directory, unless it contains enough information
+ for the destination host to tell otherwise. A hypothetical
+ example of its use in the TOPS-20 world:
+
+ CWD <some.where>
+ 200 Working directory changed
+ MKD overrainbow
+ 257 "<some.where.overrainbow>" directory created
+ CWD overrainbow
+ 431 No such directory
+ CWD <some.where.overrainbow>
+ 200 Working directory changed
+
+ CWD <some.where>
+ 200 Working directory changed to <some.where>
+ MKD <unambiguous>
+ 257 "<unambiguous>" directory created
+ CWD <unambiguous>
+
+ Note that the first example results in a subdirectory of the
+ connected directory. In contrast, the argument in the second
+ example contains enough information for TOPS-20 to tell that the
+
+
+Postel & Reynolds [Page 64]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ <unambiguous> directory is a top-level directory. Note also that
+ in the first example the user "violated" the protocol by
+ attempting to access the freshly created directory with a name
+ other than the one returned by TOPS-20. Problems could have
+ resulted in this case had there been an <overrainbow> directory;
+ this is an ambiguity inherent in some TOPS-20 implementations.
+ Similar considerations apply to the RMD command. The point is
+ this: except where to do so would violate a host's conventions for
+ denoting relative versus absolute pathnames, the host should treat
+ the operands of the MKD and RMD commands as subdirectories. The
+ 257 reply to the MKD command must always contain the absolute
+ pathname of the created directory.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 65]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+APPENDIX III - RFCs on FTP
+
+ Bhushan, Abhay, "A File Transfer Protocol", RFC 114 (NIC 5823),
+ MIT-Project MAC, 16 April 1971.
+
+ Harslem, Eric, and John Heafner, "Comments on RFC 114 (A File
+ Transfer Protocol)", RFC 141 (NIC 6726), RAND, 29 April 1971.
+
+ Bhushan, Abhay, et al, "The File Transfer Protocol", RFC 172
+ (NIC 6794), MIT-Project MAC, 23 June 1971.
+
+ Braden, Bob, "Comments on DTP and FTP Proposals", RFC 238 (NIC 7663),
+ UCLA/CCN, 29 September 1971.
+
+ Bhushan, Abhay, et al, "The File Transfer Protocol", RFC 265
+ (NIC 7813), MIT-Project MAC, 17 November 1971.
+
+ McKenzie, Alex, "A Suggested Addition to File Transfer Protocol",
+ RFC 281 (NIC 8163), BBN, 8 December 1971.
+
+ Bhushan, Abhay, "The Use of "Set Data Type" Transaction in File
+ Transfer Protocol", RFC 294 (NIC 8304), MIT-Project MAC,
+ 25 January 1972.
+
+ Bhushan, Abhay, "The File Transfer Protocol", RFC 354 (NIC 10596),
+ MIT-Project MAC, 8 July 1972.
+
+ Bhushan, Abhay, "Comments on the File Transfer Protocol (RFC 354)",
+ RFC 385 (NIC 11357), MIT-Project MAC, 18 August 1972.
+
+ Hicks, Greg, "User FTP Documentation", RFC 412 (NIC 12404), Utah,
+ 27 November 1972.
+
+ Bhushan, Abhay, "File Transfer Protocol (FTP) Status and Further
+ Comments", RFC 414 (NIC 12406), MIT-Project MAC, 20 November 1972.
+
+ Braden, Bob, "Comments on File Transfer Protocol", RFC 430
+ (NIC 13299), UCLA/CCN, 7 February 1973.
+
+ Thomas, Bob, and Bob Clements, "FTP Server-Server Interaction",
+ RFC 438 (NIC 13770), BBN, 15 January 1973.
+
+ Braden, Bob, "Print Files in FTP", RFC 448 (NIC 13299), UCLA/CCN,
+ 27 February 1973.
+
+ McKenzie, Alex, "File Transfer Protocol", RFC 454 (NIC 14333), BBN,
+ 16 February 1973.
+
+
+Postel & Reynolds [Page 66]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ Bressler, Bob, and Bob Thomas, "Mail Retrieval via FTP", RFC 458
+ (NIC 14378), BBN-NET and BBN-TENEX, 20 February 1973.
+
+ Neigus, Nancy, "File Transfer Protocol", RFC 542 (NIC 17759), BBN,
+ 12 July 1973.
+
+ Krilanovich, Mark, and George Gregg, "Comments on the File Transfer
+ Protocol", RFC 607 (NIC 21255), UCSB, 7 January 1974.
+
+ Pogran, Ken, and Nancy Neigus, "Response to RFC 607 - Comments on the
+ File Transfer Protocol", RFC 614 (NIC 21530), BBN, 28 January 1974.
+
+ Krilanovich, Mark, George Gregg, Wayne Hathaway, and Jim White,
+ "Comments on the File Transfer Protocol", RFC 624 (NIC 22054), UCSB,
+ Ames Research Center, SRI-ARC, 28 February 1974.
+
+ Bhushan, Abhay, "FTP Comments and Response to RFC 430", RFC 463
+ (NIC 14573), MIT-DMCG, 21 February 1973.
+
+ Braden, Bob, "FTP Data Compression", RFC 468 (NIC 14742), UCLA/CCN,
+ 8 March 1973.
+
+ Bhushan, Abhay, "FTP and Network Mail System", RFC 475 (NIC 14919),
+ MIT-DMCG, 6 March 1973.
+
+ Bressler, Bob, and Bob Thomas "FTP Server-Server Interaction - II",
+ RFC 478 (NIC 14947), BBN-NET and BBN-TENEX, 26 March 1973.
+
+ White, Jim, "Use of FTP by the NIC Journal", RFC 479 (NIC 14948),
+ SRI-ARC, 8 March 1973.
+
+ White, Jim, "Host-Dependent FTP Parameters", RFC 480 (NIC 14949),
+ SRI-ARC, 8 March 1973.
+
+ Padlipsky, Mike, "An FTP Command-Naming Problem", RFC 506
+ (NIC 16157), MIT-Multics, 26 June 1973.
+
+ Day, John, "Memo to FTP Group (Proposal for File Access Protocol)",
+ RFC 520 (NIC 16819), Illinois, 25 June 1973.
+
+ Merryman, Robert, "The UCSD-CC Server-FTP Facility", RFC 532
+ (NIC 17451), UCSD-CC, 22 June 1973.
+
+ Braden, Bob, "TENEX FTP Problem", RFC 571 (NIC 18974), UCLA/CCN,
+ 15 November 1973.
+
+
+
+
+Postel & Reynolds [Page 67]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+ McKenzie, Alex, and Jon Postel, "Telnet and FTP Implementation -
+ Schedule Change", RFC 593 (NIC 20615), BBN and MITRE,
+ 29 November 1973.
+
+ Sussman, Julie, "FTP Error Code Usage for More Reliable Mail
+ Service", RFC 630 (NIC 30237), BBN, 10 April 1974.
+
+ Postel, Jon, "Revised FTP Reply Codes", RFC 640 (NIC 30843),
+ UCLA/NMC, 5 June 1974.
+
+ Harvey, Brian, "Leaving Well Enough Alone", RFC 686 (NIC 32481),
+ SU-AI, 10 May 1975.
+
+ Harvey, Brian, "One More Try on the FTP", RFC 691 (NIC 32700), SU-AI,
+ 28 May 1975.
+
+ Lieb, J., "CWD Command of FTP", RFC 697 (NIC 32963), 14 July 1975.
+
+ Harrenstien, Ken, "FTP Extension: XSEN", RFC 737 (NIC 42217), SRI-KL,
+ 31 October 1977.
+
+ Harrenstien, Ken, "FTP Extension: XRSQ/XRCP", RFC 743 (NIC 42758),
+ SRI-KL, 30 December 1977.
+
+ Lebling, P. David, "Survey of FTP Mail and MLFL", RFC 751, MIT,
+ 10 December 1978.
+
+ Postel, Jon, "File Transfer Protocol Specification", RFC 765, ISI,
+ June 1980.
+
+ Mankins, David, Dan Franklin, and Buzz Owen, "Directory Oriented FTP
+ Commands", RFC 776, BBN, December 1980.
+
+ Padlipsky, Michael, "FTP Unique-Named Store Command", RFC 949, MITRE,
+ July 1985.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 68]
+
+
+
+RFC 959 October 1985
+File Transfer Protocol
+
+
+REFERENCES
+
+ [1] Feinler, Elizabeth, "Internet Protocol Transition Workbook",
+ Network Information Center, SRI International, March 1982.
+
+ [2] Postel, Jon, "Transmission Control Protocol - DARPA Internet
+ Program Protocol Specification", RFC 793, DARPA, September 1981.
+
+ [3] Postel, Jon, and Joyce Reynolds, "Telnet Protocol
+ Specification", RFC 854, ISI, May 1983.
+
+ [4] Reynolds, Joyce, and Jon Postel, "Assigned Numbers", RFC 943,
+ ISI, April 1985.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Postel & Reynolds [Page 69]
+
diff --git a/lib/inets/doc/html/.gitignore b/lib/inets/doc/html/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/inets/doc/html/.gitignore
diff --git a/lib/inets/doc/man3/.gitignore b/lib/inets/doc/man3/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/inets/doc/man3/.gitignore
diff --git a/lib/inets/doc/man6/.gitignore b/lib/inets/doc/man6/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/inets/doc/man6/.gitignore
diff --git a/lib/inets/doc/pdf/.gitignore b/lib/inets/doc/pdf/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/inets/doc/pdf/.gitignore
diff --git a/lib/inets/doc/src/Makefile b/lib/inets/doc/src/Makefile
new file mode 100644
index 0000000000..5b5a818db8
--- /dev/null
+++ b/lib/inets/doc/src/Makefile
@@ -0,0 +1,272 @@
+#
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 1997-2009. All Rights Reserved.
+#
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+#
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+#
+# %CopyrightEnd%
+#
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include ../../vsn.mk
+VSN=$(INETS_VSN)
+APPLICATION=inets
+
+# ----------------------------------------------------
+# Include dependency
+# ----------------------------------------------------
+
+ifndef DOCSUPPORT
+include make.dep
+endif
+
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_APPLICATION_FILES = ref_man.xml
+
+XML_CHAPTER_FILES = \
+ inets_services.xml \
+ http_client.xml \
+ http_server.xml \
+ ftp_client.xml \
+ notes.xml
+
+XML_REF3_FILES = \
+ inets.xml \
+ ftp.xml \
+ tftp.xml \
+ http.xml\
+ httpd.xml \
+ httpd_conf.xml \
+ httpd_socket.xml \
+ httpd_util.xml \
+ mod_alias.xml \
+ mod_auth.xml \
+ mod_esi.xml \
+ mod_security.xml
+
+XML_PART_FILES = \
+ part.xml \
+ part_notes.xml \
+ part_notes_history.xml
+XML_HTML_FILES = \
+ notes_history.xml
+
+BOOK_FILES = book.xml
+
+XML_FILES = $(BOOK_FILES) \
+ $(XML_CHAPTER_FILES) \
+ $(XML_PART_FILES) \
+ $(XML_REF6_FILES) \
+ $(XML_REF3_FILES) \
+ $(XML_APPLICATION_FILES)
+
+GIF_FILES = \
+ inets.gif \
+ notes.gif \
+ ref_man.gif \
+ book.gif \
+ warning.gif \
+ note.gif
+
+
+# ----------------------------------------------------
+
+HTML_FILES = \
+ $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_HTML_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+INFO_FILE = ../../info
+EXTRA_FILES = summary.html.src \
+ $(DEFAULT_GIF_FILES) \
+ $(DEFAULT_HTML_FILES) \
+ $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_REF6_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html)
+
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+
+ifdef DOCSUPPORT
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+else
+
+TEX_FILES_BOOK = \
+ $(BOOK_FILES:%.xml=%.tex)
+TEX_FILES_REF_MAN = \
+ $(XML_PART_FILES:%.xml=%.tex) \
+ $(XML_REF3_FILES:%.xml=%.tex) \
+ $(XML_REF6_FILES:%.xml=%.tex) \
+ $(XML_APPLICATION_FILES:%.xml=%.tex)
+TEX_FILES_USERS_GUIDE = \
+ $(XML_CHAPTER_FILES:%.xml=%.tex)
+
+TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf
+TOP_PS_FILE = $(APPLICATION)-$(VSN).ps
+
+$(TOP_PDF_FILE): book.dvi ../../vsn.mk
+ $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@
+
+$(TOP_PS_FILE): book.dvi ../../vsn.mk
+ $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@
+
+TOP_HTML_FILES =
+
+endif
+
+# ----------------------------------------------------
+# FLAGS
+# ----------------------------------------------------
+XML_FLAGS +=
+DVIPS_FLAGS +=
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+$(HTMLDIR)/%.gif: %.gif
+ $(INSTALL_DATA) $< $@
+
+ifdef DOCSUPPORT
+
+docs: pdf html man
+
+ldocs: local_docs
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: gifs $(HTML_REF_MAN_FILE)
+
+clean clean_docs: clean_html clean_man clean_pdf
+ rm -f errs core *~
+
+else
+
+ifeq ($(DOCTYPE),pdf)
+docs: pdf
+else
+ifeq ($(DOCTYPE),ps)
+docs: ps
+else
+docs: html man
+endif
+endif
+
+pdf: $(TOP_PDF_FILE)
+
+ps: $(TOP_PS_FILE)
+
+html: $(HTML_FILES) $(TOP_HTML_FILES) gifs
+
+clean_tex:
+ rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK)
+
+clean: clean_tex clean_html clean_man
+ rm -f *.xmls_output *.xmls_errs
+ rm -f $(TOP_PDF_FILE)
+ rm -f errs core *~
+endif
+
+man: $(MAN3_FILES)
+
+gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
+
+debug opt:
+
+clean_pdf:
+ rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+
+clean_html:
+ rm -rf $(TOP_HTML_FILES) $(HTMLDIR)/*
+
+clean_man:
+ rm -f $(MAN3_FILES)
+
+# ----------------------------------------------------
+# Release Target
+# ----------------------------------------------------
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+ifdef DOCSUPPORT
+
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(HTMLDIR)/* \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3
+else
+
+ifeq ($(DOCTYPE),pdf)
+release_docs_spec: pdf
+ $(INSTALL_DIR) $(RELEASE_PATH)/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf
+else
+ifeq ($(DOCTYPE),ps)
+release_docs_spec: ps
+ $(INSTALL_DIR) $(RELEASE_PATH)/ps
+ $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps
+else
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3
+
+endif
+endif
+
+endif
+
+release_spec:
+
+info:
+ @echo "GIF_FILES:\n$(GIF_FILES)"
+ @echo ""
+ @echo "EXTRA_FILES:\n$(EXTRA_FILES)"
+ @echo ""
+ @echo "HTML_FILES:\n$(HTML_FILES)"
+ @echo ""
+ @echo "TOP_HTML_FILES:\n$(TOP_HTML_FILES)"
+ @echo ""
+ @echo "DEFAULT_GIF_FILES:\n$(DEFAULT_GIF_FILES)"
+ @echo ""
+ @echo "DEFAULT_HTML_FILES:\n$(DEFAULT_HTML_FILES)"
+ @echo ""
+ @echo "XML_REF3_FILES:\n$(XML_REF3_FILES)"
+ @echo ""
+ @echo "XML_REF6_FILES:\n$(XML_REF6_FILES)"
+ @echo ""
+ @echo "XML_CHAPTER_FILES:\n$(XML_CHAPTER_FILES)"
+ @echo ""
diff --git a/lib/inets/doc/src/book.gif b/lib/inets/doc/src/book.gif
new file mode 100644
index 0000000000..94b3868792
--- /dev/null
+++ b/lib/inets/doc/src/book.gif
Binary files differ
diff --git a/lib/inets/doc/src/book.xml b/lib/inets/doc/src/book.xml
new file mode 100644
index 0000000000..7da0abd98f
--- /dev/null
+++ b/lib/inets/doc/src/book.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header titlestyle="normal">
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>inets</title>
+ <prepared>Mattias Nilsson</prepared>
+ <docno></docno>
+ <date>1997-07-16</date>
+ <rev>2.3</rev>
+ <file>book.sgml</file>
+ </header>
+ <insidecover>
+ </insidecover>
+ <pagetext>Inets</pagetext>
+ <preamble>
+ <contents level="2"></contents>
+ </preamble>
+ <parts lift="no">
+ <xi:include href="part.xml"/>
+ </parts>
+ <applications>
+ <xi:include href="ref_man.xml"/>
+ </applications>
+ <releasenotes>
+ <xi:include href="notes.xml"/>
+ </releasenotes>
+ <listofterms></listofterms>
+ <index></index>
+</book>
+
+
diff --git a/lib/inets/doc/src/fascicules.xml b/lib/inets/doc/src/fascicules.xml
new file mode 100644
index 0000000000..101e745722
--- /dev/null
+++ b/lib/inets/doc/src/fascicules.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
+
+<fascicules>
+ <fascicule file="part" href="part_frame.html" entry="no">
+ User's Guide
+ </fascicule>
+ <fascicule file="ref_man" href="ref_man_frame.html" entry="yes">
+ Reference Manual
+ </fascicule>
+ <fascicule file="part_notes" href="part_notes_frame.html" entry="no">
+ Release Notes
+ </fascicule>
+ <fascicule file="" href="../../../../doc/print.html" entry="no">
+ Off-Print
+ </fascicule>
+</fascicules>
+
+
diff --git a/lib/inets/doc/src/ftp.xml b/lib/inets/doc/src/ftp.xml
new file mode 100644
index 0000000000..9ecca3dde1
--- /dev/null
+++ b/lib/inets/doc/src/ftp.xml
@@ -0,0 +1,939 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>ftp</title>
+ <prepared>Peter H&ouml;gfeldt</prepared>
+ <docno></docno>
+ <date>1997-11-05</date>
+ <rev>B</rev>
+ <file>ftp.xml</file>
+ </header>
+ <module>ftp</module>
+ <modulesummary>A File Transfer Protocol client</modulesummary>
+
+ <description>
+
+ <p>The <c>ftp</c> module implements a client for file transfer
+ according to a subset of the File Transfer Protocol (see <term
+ id="RFC"></term>959). </p>
+
+ <p>Starting from inets version 4.4.1 the ftp
+ client will always try to use passive ftp mode and only resort
+ to active ftp mode if this fails. There is a start option
+ <seealso marker="#mode">mode</seealso> where this default behavior
+ may be changed. </p>
+
+ <marker id="two_start"></marker>
+
+ <p>There are two ways to start an ftp client. One is using the
+ <seealso marker="#service_start">Inets service framework</seealso>
+ and the other is to start it directy as a standalone process
+ using the <seealso marker="#open">open</seealso> function. </p>
+
+ <p>For a simple example of an ftp session see
+ <seealso marker="ftp_client">Inets User's Guide.</seealso></p>
+
+ <p>In addition to the ordinary functions for receiving and sending
+ files (see <c>recv/2</c>, <c>recv/3</c>, <c>send/2</c> and
+ <c>send/3</c>) there are functions for receiving remote files as
+ binaries (see <c>recv_bin/2</c>) and for sending binaries to to be
+ stored as remote files (see <c>send_bin/3</c>).</p>
+
+ <p>There is also a set of functions for sending and receiving
+ contiguous parts of a file to be stored in a remote file (for send
+ see <c>send_chunk_start/2</c>, <c>send_chunk/2</c> and
+ <c>send_chunk_end/1</c> and for receive see
+ <c>recv_chunk_start/2</c> and <c>recv_chunk/</c>).</p>
+
+ <p>The particular return values of the functions below depend very
+ much on the implementation of the FTP server at the remote
+ host. In particular the results from <c>ls</c> and <c>nlist</c>
+ varies. Often real errors are not reported as errors by <c>ls</c>,
+ even if for instance a file or directory does not
+ exist. <c>nlist</c> is usually more strict, but some
+ implementations have the peculiar behaviour of responding with an
+ error, if the request is a listing of the contents of directory
+ which exists but is empty.</p>
+
+ <marker id="service_start"></marker>
+ </description>
+
+ <section>
+ <title>FTP CLIENT SERVICE START/STOP </title>
+
+ <p>The FTP client can be started and stopped dynamically in runtime by
+ calling the Inets application API
+ <c>inets:start(ftpc, ServiceConfig)</c>,
+ or <c>inets:start(ftpc, ServiceConfig, How)</c>, and
+ <c>inets:stop(ftpc, Pid)</c>.
+ See <seealso marker="inets">inets(3)</seealso> for more info. </p>
+ <p>Below follows a description of
+ the available configuration options.</p>
+
+ <taglist>
+ <tag>{host, Host}</tag>
+ <item>
+ <marker id="host"></marker>
+ <p>Host = <c>string() | ip_address()</c> </p>
+ </item>
+
+ <tag>{port, Port}</tag>
+ <item>
+ <marker id="port"></marker>
+ <p>Port = <c>integer() > 0</c> </p>
+ <p>Default is 21.</p>
+ </item>
+
+ <tag>{mode, Mode}</tag>
+ <item>
+ <marker id="mode"></marker>
+ <p>Mode = <c>active | passive</c> </p>>
+ <p>Default is <c>passive</c>. </p>
+ </item>
+
+ <tag>{verbose, Verbose}</tag>
+ <item>
+ <marker id="verbose"></marker>
+ <p>Verbose = <c>boolean()</c> </p>
+ <p>This determines if the FTP communication should be
+ verbose or not. </p>
+ <p>Default is <c>false</c>. </p>
+ </item>
+
+ <tag>{debug, Debug}</tag>
+ <item>
+ <marker id="debug"></marker>
+ <p>Debug = <c>trace | debug | disable</c> </p>
+ <p>Debugging using the dbg toolkit. </p>
+ <p>Default is <c>disable</c>. </p>
+ </item>
+
+ <tag>{ipfamily, IpFamily}</tag>
+ <item>
+ <marker id="ipfamily"></marker>
+ <p>IpFamily = <c>inet | inet6 | inet6fb4</c> </p>
+ <p>With <c>inet6fb4</c> the client behaves as before
+ (it tries to use IPv6 and only if that does not work, it
+ uses IPv4). </p>
+ <p>Default is <c>inet</c> (IPv4). </p>
+ </item>
+
+ <tag>{timeout, Timeout}</tag>
+ <item>
+ <marker id="timeout"></marker>
+ <p>Timeout = <c>integer() >= 0</c> </p>
+ <p>Connection timeout. </p>
+ <p>Default is 60000 (milliseconds). </p>
+ </item>
+
+ <tag>{progress, Progress}</tag>
+ <item>
+ <marker id="progress"></marker>
+ <p>Progress = <c>ignore | {CBModule, CBFunction, InitProgress}</c></p>
+ <p>CBModule = <c>atom()</c>, CBFunction = <c>atom()</c> </p>
+ <p>InitProgress = <c>term()</c> </p>
+ <p>Default is <c>ignore</c>. </p>
+ </item>
+
+ </taglist>
+
+ <p>The progress option is intended to be used by applications that
+ want to create some type of progress report such as a progress bar in
+ a GUI. The default value for the progress option is ignore
+ e.i. the option is not used. When the progress option is
+ specified the following will happen when ftp:send/[3,4] or
+ ftp:recv/[3,4] are called.</p>
+
+ <list type="bulleted">
+ <item>
+ <p>Before a file is transfered the following call will
+ be made to indicate the start of the file transfer and how big
+ the file is. The return value of the callback function
+ should be a new value for the UserProgressTerm that will
+ bu used as input next time the callback function is
+ called.</p>
+ <br></br>
+ <p><c>
+ CBModule:CBFunction(InitProgress, File, {file_size, FileSize})
+ </c></p>
+ <br></br>
+ </item>
+
+ <item>
+ <p>Every time a chunk of bytes is transfered the
+ following call will be made:</p>
+ <br></br>
+ <p><c>
+ CBModule:CBFunction(UserProgressTerm, File, {transfer_size, TransferSize}) </c></p>
+ <br></br>
+ </item>
+
+ <item>
+ <p>At the end of the file the following call will be
+ made to indicate the end of the transfer.</p>
+ <br></br>
+ <p><c>
+ CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0}) </c></p>
+ <br></br>
+ </item>
+ </list>
+
+ <p>The callback function should be defined as </p>
+
+ <p><c>
+ CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm </c></p>
+
+ <p><c>
+ CBModule = CBFunction = atom()
+ </c></p>
+
+ <p><c>
+ UserProgressTerm = term()
+ </c></p>
+
+ <p><c>
+ File = string()
+ </c></p>
+
+ <p><c>
+ Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown} </c></p>
+
+ <p>Alas for remote files it is not possible for ftp to determine the
+ file size in a platform independent way. In this case the size
+ will be <c>unknown</c> and it is left to the application to find
+ out the size. </p>
+
+ <note>
+ <p>The callback is made by a middleman process, hence the
+ file transfer will not be affected by the code in the progress
+ callback function. If the callback should crash this will be
+ detected by the ftp connection process that will print an
+ info-report and then go one as if the progress option was set
+ to ignore. </p>
+ </note>
+
+ <p>The file transfer type is set to the default of the FTP server
+ when the session is opened. This is usually ASCCI-mode.
+ </p>
+
+ <p>The current local working directory (cf. <c>lpwd/1</c>) is set to
+ the value reported by <c>file:get_cwd/1</c>. the wanted
+ local directory.
+ </p>
+
+ <p>The return value <c>Pid</c> is used as a reference to the
+ newly created ftp client in all other functions, and they should
+ be called by the process that created the connection. The ftp
+ client process monitors the process that created it and
+ will terminate if that process terminates.</p>
+ </section>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Here follows type definitions that are used by more than one
+ function in the FTP client API. </p>
+ <p><c> pid() - identifier of an ftp connection.</c></p>
+ <p><c> string() = list of ASCII characters.</c></p>
+ <p><c> shortage_reason() = etnospc | epnospc</c></p>
+ <p><c> restriction_reason() = epath | efnamena | elogin | enotbinary
+ - note not all restrictions may always relevant to all functions
+ </c></p>
+ <p><c>common_reason() = econn | eclosed | term() - some kind of
+ explanation of what went wrong.</c></p>
+
+ <marker id="account"></marker>
+ </section>
+
+ <funcs>
+ <func>
+ <name>account(Pid, Account) -> ok | {error, Reason}</name>
+ <fsummary>Specify which account to use.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Account = string()</v>
+ <v>Reason = eacct | common_reason()</v>
+ </type>
+ <desc>
+ <p>If an account is needed for an operation set the account
+ with this operation.</p>
+
+ <marker id="append"></marker>
+ <marker id="append2"></marker>
+ <marker id="append3"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>append(Pid, LocalFile) -> </name>
+ <name>append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name>
+ <fsummary>Transfer file to remote server, and append it to Remotefile.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>LocalFile = RemoteFile = string()</v>
+ <v>Reason = epath | elogin | etnospc | epnospc | efnamena | common_reason</v>
+ </type>
+ <desc>
+ <p>Transfers the file <c>LocalFile</c> to the remote server. If
+ <c>RemoteFile</c> is specified, the name of the remote file that the
+ file will be appended to is set to <c>RemoteFile</c>; otherwise
+ the name is set to <c>LocalFile</c> If the file does not exists the
+ file will be created.</p>
+
+ <marker id="append_bin"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name>
+ <fsummary>Transfer a binary into a remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()()</v>
+ <v>RemoteFile = string()</v>
+ <v>Reason = restriction_reason()| shortage_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Transfers the binary <c>Bin</c> to the remote server and append
+ it to the file <c>RemoteFile</c>. If the file does not exists it
+ will be created.</p>
+
+ <marker id="append_chunk"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>append_chunk(Pid, Bin) -> ok | {error, Reason}</name>
+ <fsummary>append a chunk to the remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()</v>
+ <v>Reason = echunk | restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Transfer the chunk <c>Bin</c> to the remote server, which
+ append it into the file specified in the call to
+ <c>append_chunk_start/2</c>. </p>
+ <p>Note that for some errors, e.g. file system full, it is
+ necessary to to call <c>append_chunk_end</c> to get the
+ proper reason.</p>
+
+ <marker id="append_chunk_start"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>append_chunk_start(Pid, File) -> ok | {error, Reason}</name>
+ <fsummary>Start transfer of file chunks for appending to File.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>File = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Start the transfer of chunks for appending to the file
+ <c>File</c> at the remote server. If the file does not exists
+ it will be created.</p>
+
+ <marker id="append_chunk_end"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>append_chunk_end(Pid) -> ok | {error, Reason}</name>
+ <fsummary>Stop transfer of chunks for appending.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = echunk | restriction_reason() | shortage_reason() </v>
+ </type>
+ <desc>
+ <p>Stops transfer of chunks for appending to the remote server.
+ The file at the remote server, specified in the call to
+ <c>append_chunk_start/2</c> is closed by the server.</p>
+
+ <marker id="cd"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>cd(Pid, Dir) -> ok | {error, Reason}</name>
+ <fsummary>Change remote working directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Dir = string()</v>
+ <v>Reason = restriction_reason() | common_reason() </v>
+ </type>
+ <desc>
+ <p>Changes the working directory at the remote server to
+ <c>Dir</c>.</p>
+
+ <marker id="close"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>close(Pid) -> ok</name>
+ <fsummary>End the ftp session.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Ends an ftp session, created using the
+ <seealso marker="#open">open</seealso> function. </p>
+
+ <marker id="delete"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete(Pid, File) -> ok | {error, Reason}</name>
+ <fsummary>Delete a file at the remote server..</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>File = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Deletes the file <c>File</c> at the remote server.</p>
+
+ <marker id="append"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>formaterror(Tag) -> string()</name>
+ <fsummary>Return error diagnostics.</fsummary>
+ <type>
+ <v>Tag = {error, atom()} | atom()</v>
+ </type>
+ <desc>
+ <p>Given an error return value <c>{error, AtomReason}</c>,
+ this function returns a readable string describing the error.</p>
+
+ <marker id="lcd"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>lcd(Pid, Dir) -> ok | {error, Reason}</name>
+ <fsummary>Change local working directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Dir = string()</v>
+ <v>Reason = restriction_reason()</v>
+ </type>
+ <desc>
+ <p>Changes the working directory to <c>Dir</c> for the local client. </p>
+
+ <marker id="lpwd"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>lpwd(Pid) -> {ok, Dir}</name>
+ <fsummary>Get local current working directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Returns the current working directory at the local client.</p>
+
+ <marker id="ls"></marker>
+ <marker id="ls1"></marker>
+ <marker id="ls2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>ls(Pid) -> </name>
+ <name>ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name>
+ <fsummary>List of files.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Pathname = string()</v>
+ <v>Listing = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Returns a list of files in long format. </p>
+ <p><c>Pathname</c> can be a directory, a group of files or
+ even a file. The <c>Pathname</c> string can contain wildcard(s). </p>
+ <p><c>ls/1</c> implies the user's current remote directory. </p>
+ <p>The format of <c>Listing</c> is operating system dependent
+ (on UNIX it is typically produced from the output of the
+ <c>ls -l</c> shell command).</p>
+
+ <marker id="mkdir"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>mkdir(Pid, Dir) -> ok | {error, Reason}</name>
+ <fsummary>Create remote directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Dir = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Creates the directory <c>Dir</c> at the remote server.</p>
+
+ <marker id="nlist"></marker>
+ <marker id="nlist1"></marker>
+ <marker id="nlist2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>nlist(Pid) -> </name>
+ <name>nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name>
+ <fsummary>List of files.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Pathname = string()</v>
+ <v>Listing = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Returns a list of files in short format. </p>
+ <p><c>Pathname</c> can be a directory, a group of files or
+ even a file. The <c>Pathname</c> string can contain wildcard(s). </p>
+ <p><c>nlist/1</c> implies the user's current remote directory. </p>
+ <p>The format of <c>Listing</c> is a stream of
+ file names, where each name is separated by &lt;CRLF&gt; or
+ &lt;NL&gt;. Contrary to the <c>ls</c> function, the purpose of
+ <c>nlist</c> is to make it possible for a program to
+ automatically process file name information.</p>
+
+ <marker id="open"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(Host) -> {ok, Pid} | {error, Reason}</name>
+ <name>open(Host, Opts) -> {ok, Pid} | {error, Reason}</name>
+ <fsummary>Start an standalone ftp client.</fsummary>
+ <type>
+ <v>Host = string() | ip_address()</v>
+ <v>Opts = start_options() | open_options()</v>
+ <v>start_options() = [start_option()]</v>
+ <v>start_option() = {verbose, verbose()} | {debug, debug()}</v>
+ <v>verbose() = boolean() (defaults to false)</v>
+ <v>debug() = disable | debug | trace (defaults to disable)</v>
+ <v>open_options() = [open_option()]</v>
+ <v>open_option() = {ipfamily, ipfamily()} | {port, port()} | {mode, mode()} | {timeout, timeout()} | {progress, progress()}</v>
+ <v>ipfamily() = inet | inet6 | inet6fb4 (defaults to inet)</v>
+ <v>port() = integer() > 0 (defaults to 21)</v>
+ <v>mode() = active | passive (defaults to passive)</v>
+ <v>timeout() = integer() >= 0 (defaults to 60000 milliseconds)</v>
+ <v>pogress() = ignore | {module(), function(), initial_data()} (defaults to ignore)</v>
+ <v>module() = atom()</v>
+ <v>function() = atom()</v>
+ <v>initial_data() = term()</v>
+ <v>Reason = ehost | term()</v>
+ </type>
+
+ <desc>
+ <p>This function is used to start a standalone ftp client process
+ (without the inets service framework) and
+ open a session with the FTP server at <c>Host</c>. </p>
+
+ <p>A session opened in this way, is closed using the
+ <seealso marker="#close">close</seealso> function. </p>
+
+ <marker id="pwd"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>pwd(Pid) -> {ok, Dir} | {error, Reason}</name>
+ <fsummary>Get remote current working directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = restriction_reason() | common_reason() </v>
+ </type>
+ <desc>
+ <p>Returns the current working directory at the remote server. </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pwd(Pid) -> {ok, Dir} | {error, Reason}</name>
+ <fsummary>Get remote current working directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = restriction_reason() | common_reason() </v>
+ </type>
+ <desc>
+ <p>Returns the current working directory at the remote server.</p>
+
+ <marker id="recv"></marker>
+ <marker id="recv2"></marker>
+ <marker id="recv3"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv(Pid, RemoteFile) -> </name>
+ <name>recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}</name>
+ <fsummary>Transfer file from remote server.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>RemoteFile = LocalFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason() | file_write_error_reason() </v>
+ <v>file_write_error_reason() = see file:write/2</v>
+ </type>
+ <desc>
+ <p>Transfer the file <c>RemoteFile</c> from the remote server
+ to the the file system of the local client. If
+ <c>LocalFile</c> is specified, the local file will be
+ <c>LocalFile</c>; otherwise it will be
+ <c>RemoteFile</c>.</p>
+ <p>If the file write fails
+ (e.g. enospc), then the command is aborted and <c>{error, file_write_error_reason()}</c> is returned. The file is
+ however <em>not</em> removed.</p>
+
+ <marker id="recv_bin"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}</name>
+ <fsummary>Transfer file from remote server as a binary.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()</v>
+ <v>RemoteFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Transfers the file <c>RemoteFile</c> from the remote server and
+ receives it as a binary.</p>
+
+ <marker id="recv_chunk_start"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}</name>
+ <fsummary>Start chunk-reading of the remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>RemoteFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Start transfer of the file <c>RemoteFile</c> from the
+ remote server.</p>
+
+ <marker id="recv_chunk"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}</name>
+ <fsummary>Receive a chunk of the remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Receive a chunk of the remote file (<c>RemoteFile</c> of
+ <c>recv_chunk_start</c>). The return values has the following
+ meaning:</p>
+ <list type="bulleted">
+ <item><c>ok</c> the transfer is complete.</item>
+ <item><c>{ok, Bin}</c> just another chunk of the file.</item>
+ <item><c>{error, Reason}</c> transfer failed.</item>
+ </list>
+
+ <marker id="rename"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>rename(Pid, Old, New) -> ok | {error, Reason}</name>
+ <fsummary>Rename a file at the remote server..</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>CurrFile = NewFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Renames <c>Old</c> to <c>New</c> at the remote server.</p>
+
+ <marker id="rmdir"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>rmdir(Pid, Dir) -> ok | {error, Reason}</name>
+ <fsummary>Remove a remote directory.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Dir = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Removes directory <c>Dir</c> at the remote server.</p>
+
+ <marker id="send"></marker>
+ <marker id="send2"></marker>
+ <marker id="send3"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Pid, LocalFile) -></name>
+ <name>send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name>
+ <fsummary>Transfer file to remote server.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>LocalFile = RemoteFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
+ </type>
+ <desc>
+ <p>Transfers the file <c>LocalFile</c> to the remote server. If
+ <c>RemoteFile</c> is specified, the name of the remote file is set
+ to <c>RemoteFile</c>; otherwise the name is set to <c>LocalFile</c>.</p>
+
+ <marker id="send_bin"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name>
+ <fsummary>Transfer a binary into a remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()()</v>
+ <v>RemoteFile = string()</v>
+ <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
+ </type>
+ <desc>
+ <p>Transfers the binary <c>Bin</c> into the file <c>RemoteFile</c>
+ at the remote server.</p>
+
+ <marker id="send_chunk"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_chunk(Pid, Bin) -> ok | {error, Reason}</name>
+ <fsummary>Write a chunk to the remote file.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Bin = binary()</v>
+ <v>Reason = echunk | restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Transfer the chunk <c>Bin</c> to the remote server, which
+ writes it into the file specified in the call to
+ <c>send_chunk_start/2</c>. </p>
+ <p>Note that for some errors, e.g. file system full, it is
+ necessary to to call <c>send_chunk_end</c> to get the
+ proper reason.</p>
+
+ <marker id="send_chunk_start"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_chunk_start(Pid, File) -> ok | {error, Reason}</name>
+ <fsummary>Start transfer of file chunks.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>File = string()</v>
+ <v>Reason = restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Start transfer of chunks into the file <c>File</c> at the
+ remote server.</p>
+
+ <marker id="send_chunk_end"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_chunk_end(Pid) -> ok | {error, Reason}</name>
+ <fsummary>Stop transfer of chunks.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v>
+ </type>
+ <desc>
+ <p>Stops transfer of chunks to the remote server. The file at the
+ remote server, specified in the call to <c>send_chunk_start/2</c>
+ is closed by the server.</p>
+
+ <marker id="type"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>type(Pid, Type) -> ok | {error, Reason}</name>
+ <fsummary>Set transfer type to <c>ascii</c>or <c>binary</c>.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Type = ascii | binary</v>
+ <v>Reason = etype | restriction_reason() | common_reason()</v>
+ </type>
+ <desc>
+ <p>Sets the file transfer type to <c>ascii</c> or <c>binary</c>. When
+ an ftp session is opened, the default transfer type of the
+ server is used, most often <c>ascii</c>, which is the default
+ according to RFC 959.</p>
+
+ <marker id="user3"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>user(Pid, User, Password) -> ok | {error, Reason}</name>
+ <fsummary>User login.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>User = Password = string()</v>
+ <v>Reason = euser | common_reason()</v>
+ </type>
+ <desc>
+ <p>Performs login of <c>User</c> with <c>Password</c>.</p>
+
+ <marker id="user4"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>user(Pid, User, Password, Account) -> ok | {error, Reason}</name>
+ <fsummary>User login.</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>User = Password = string()</v>
+ <v>Reason = euser | common_reason() </v>
+ </type>
+ <desc>
+ <p>Performs login of <c>User</c> with <c>Password</c> to the account
+ specified by <c>Account</c>.</p>
+
+ <marker id="quote"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>quote(Pid, Command) -> [FTPLine]</name>
+ <fsummary>Sends an arbitrary FTP command. </fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Command = string()</v>
+ <v>FTPLine = string() - Note the telnet end of line characters, from the ftp protocol definition, CRLF e.g. "\\r\ " has been removed.</v>
+ </type>
+ <desc>
+ <p>Sends an arbitrary FTP command and returns verbatimly a list
+ of the lines sent back by the FTP server. This functions is
+ intended to give an application accesses to FTP commands
+ that are server specific or that may not be provided by
+ this FTP client. </p>
+ <note>
+ <p>FTP commands that require a data connection can not be
+ successfully issued with this function. </p>
+ </note>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ERRORS</title>
+ <p>The possible error reasons and the corresponding diagnostic strings
+ returned by <c>formaterror/1</c> are as follows:
+ </p>
+ <taglist>
+ <tag><c>echunk</c></tag>
+ <item>
+ <p>Synchronisation error during chunk sending.
+ </p>
+ <p>A call has been made to <c>send_chunk/2</c> or
+ <c>send_chunk_end/1</c>, before a call to
+ <c>send_chunk_start/2</c>; or a call has been made to another
+ transfer function during chunk sending, i.e. before a call
+ to <c>send_chunk_end/1</c>.</p>
+ </item>
+ <tag><c>eclosed</c></tag>
+ <item>
+ <p>The session has been closed.</p>
+ </item>
+ <tag><c>econn</c></tag>
+ <item>
+ <p>Connection to remote server prematurely closed.</p>
+ </item>
+ <tag><c>ehost</c></tag>
+ <item>
+ <p>Host not found, FTP server not found, or connection rejected
+ by FTP server.</p>
+ </item>
+ <tag><c>elogin</c></tag>
+ <item>
+ <p>User not logged in.</p>
+ </item>
+ <tag><c>enotbinary</c></tag>
+ <item>
+ <p>Term is not a binary.</p>
+ </item>
+ <tag><c>epath</c></tag>
+ <item>
+ <p>No such file or directory, or directory already exists, or
+ permission denied.</p>
+ </item>
+ <tag><c>etype</c></tag>
+ <item>
+ <p>No such type.</p>
+ </item>
+ <tag><c>euser</c></tag>
+ <item>
+ <p>User name or password not valid.</p>
+ </item>
+ <tag><c>etnospc</c></tag>
+ <item>
+ <p>Insufficient storage space in system [452].</p>
+ </item>
+ <tag><c>epnospc</c></tag>
+ <item>
+ <p>Exceeded storage allocation (for current directory or
+ dataset) [552].</p>
+ </item>
+ <tag><c>efnamena</c></tag>
+ <item>
+ <p>File name not allowed [553].</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>file, filename, J. Postel and J. Reynolds: File Transfer Protocol
+ (RFC 959).
+ </p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/ftp_client.xml b/lib/inets/doc/src/ftp_client.xml
new file mode 100644
index 0000000000..7f62a453a6
--- /dev/null
+++ b/lib/inets/doc/src/ftp_client.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>FTP Client</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>ftp_client.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+
+ <p>Ftp clients are consider to be rather temporary and are
+ for that reason only started and stopped during
+ runtime and can not be started at application startup.
+ Due to the design of FTP client API, letting some
+ functions return intermediate results, only the process
+ that started the ftp client will be able to access it in
+ order to preserve sane semantics. (This could be solved
+ by changing the API and using the concept of a controlling
+ process more in line with other OTP applications, but
+ that is perhaps something for the future.)
+ If the process that started the ftp session
+ dies the ftp client process will terminate.</p>
+
+ <p>The client supports ipv6 as long as the underlying mechanisms
+ also do so. </p>
+
+ </section>
+
+ <section>
+ <title>Using the FTP Client API</title>
+ <p>The following is a simple example of an ftp session, where
+ the user <c>guest</c> with password <c>password</c> logs on to
+ the remote host <c>erlang.org</c>, and where the file
+ <c>appl.erl</c> is transferred from the remote to the local
+ host. When the session is opened, the current directory at
+ the remote host is <c>/home/guest</c>, and <c>/home/fred</c>
+ at the local host. Before transferring the file, the current
+ local directory is changed to <c>/home/eproj/examples</c>, and
+ the remote directory is set to
+ <c>/home/guest/appl/examples</c>.</p>
+ <code type="erl"><![CDATA[
+ 1> inets:start().
+ ok
+ 2> {ok, Pid} = inets:start(ftpc, [{host, "erlang.org"}]).
+ {ok,<0.22.0>}
+ 3> ftp:user(Pid, "guest", "password").
+ ok
+ 4> ftp:pwd(Pid).
+ {ok, "/home/guest"}
+ 5> ftp:cd(Pid, "appl/examples").
+ ok
+ 6> ftp:lpwd(Pid).
+ {ok, "/home/fred"}.
+ 7> ftp:lcd(Pid, "/home/eproj/examples").
+ ok
+ 8> ftp:recv(Pid, "appl.erl").
+ ok
+ 9> inets:stop(ftpc, Pid).
+ ok
+ ]]></code>
+ </section>
+</chapter>
+
+
diff --git a/lib/inets/doc/src/http.xml b/lib/inets/doc/src/http.xml
new file mode 100644
index 0000000000..f6f8338113
--- /dev/null
+++ b/lib/inets/doc/src/http.xml
@@ -0,0 +1,491 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>http</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>http</module>
+ <modulesummary>An HTTP/1.1 client </modulesummary>
+ <description>
+ <p>This module provides the API to a HTTP/1.1 client according to
+ RFC 2616, caching is currently not supported.</p>
+ <note>
+ <p>When starting the Inets application a manager process for the
+ default profile will be started. The functions in this API
+ that does not explicitly use a profile will accesses the
+ default profile. A profile keeps track of proxy options,
+ cookies and other options that can be applied to more than one
+ request. </p>
+
+ <p>If the scheme
+ https is used the ssl application needs to be started.</p>
+
+ <p>Also note that pipelining will only be used if the pipeline
+ timeout is set, otherwise persistent connections without
+ pipelining will be used e.i. the client always waits for
+ the previous response before sending the next request.</p>
+ </note>
+ <p>There are some usage examples in the <seealso
+ marker="http_client">Inets User's Guide.</seealso></p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in
+ this module:</p>
+ <code type="none"><![CDATA[
+boolean() = true | false
+string() = list of ASCII characters
+request_id() = ref()
+profile() = atom()
+path() = string() representing a file path or directory path
+ip_address() = See inet(3)
+ ]]></code>
+
+ </section>
+
+ <section>
+ <title>HTTP DATA TYPES </title>
+ <p>Type definitions that are related to HTTP:</p>
+ <p>For more information about HTTP see rfc 2616</p>
+
+ <code type="none"><![CDATA[
+method() = head | get | put | post | trace | options | delete
+request() = {url(), headers()} |
+ {url(), headers(), content_type(), body()}
+url() = string() - Syntax according to the URI definition in rfc 2396, ex: "http://www.erlang.org"
+status_line() = {http_version(), status_code(), reason_phrase()}
+http_version() = string() ex: "HTTP/1.1"
+status_code() = integer()
+reason_phrase() = string()
+content_type() = string()
+headers() = [header()]
+header() = {field(), value()}
+field() = string()
+value() = string()
+body() = string() | binary()
+filename() = string()
+ ]]></code>
+
+ </section>
+
+ <section>
+ <title>SSL DATA TYPES </title>
+ <p>Some type definitions relevant when using https,
+ for details <seealso marker="ssl:ssl">ssl(3)</seealso>: </p>
+ <code type="none"><![CDATA[
+ssl_options() = {verify, code()} |
+ {depth, depth()} |
+ {certfile, path()} |
+ {keyfile, path()} |
+ {password, string()} |
+ {cacertfile, path()} |
+ {ciphers, string()}
+ ]]></code>
+ </section>
+
+ <section>
+ <title>HTTP CLIENT SERVICE START/STOP </title>
+
+ <p>A HTTP client can be configured to start when starting the inets
+ application or started dynamically in runtime by calling the
+ inets application API <c>inets:start(httpc, ServiceConfig)</c>, or
+ <c>inets:start(httpc, ServiceConfig, How)</c>
+ see <seealso marker="inets">inets(3)</seealso> Below follows a
+ description of the available configuration options.</p>
+ <taglist>
+ <tag>{profile, profile()}</tag>
+ <item>Name of the profile, see
+ common data types below, this option is mandatory.</item>
+ <tag>{data_dir, path()}</tag>
+ <item>Directory where the profile
+ may save persistent data, if omitted all cookies will be treated
+ as session cookies.</item>
+ </taglist>
+
+ <p>The client can be stopped using inets:stop(httpc, Pid) or
+ inets:stop(httpc, Profile).</p>
+
+ <marker id="cancel_request"></marker>
+ </section>
+
+ <funcs>
+ <func>
+ <name>cancel_request(RequestId) -> </name>
+ <name>cancel_request(RequestId, Profile) -> ok</name>
+ <fsummary>Cancels an asynchronous HTTP-request.</fsummary>
+ <type>
+ <v>RequestId = request_id() - A unique identifier as returned
+ by request/4</v>
+ <v>Profile = profile()</v>
+ </type>
+ <desc>
+ <p>Cancels an asynchronous HTTP-request. </p>
+
+ <marker id="request1"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>request(Url) -> </name>
+ <name>request(Url, Profile) -> {ok, Result} | {error, Reason}</name>
+ <fsummary>Sends a get HTTP-request</fsummary>
+ <type>
+ <v>Url = url() </v> <v>Result = {status_line(), headers(),
+ body()} | {status_code(), body()} | request_id() </v>
+ <v>Profile = profile()</v>
+ <v>Reason = term() </v>
+ </type>
+ <desc>
+ <p>Equivalent to http:request(get, {Url, []}, [], []).</p>
+
+ <marker id="request2"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>request(Method, Request, HTTPOptions, Options) -> </name>
+ <name>request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}</name>
+
+ <fsummary>Sends a HTTP-request</fsummary>
+ <type>
+ <v>Method = method() </v>
+ <v>Request = request()</v>
+ <v>HTTPOptions = http_options()</v>
+ <v>http_options() = [http_option()]</v>
+ <v>http_option() = {timeout, timeout()} |
+ {connect_timeout, timeout()} |
+ {ssl, ssl_options()} |
+ {autoredirect, boolean()} |
+ {proxy_auth, {userstring(), passwordstring()}} |
+ {version, http_version()} |
+ {relaxed, boolean()}</v>
+ <v>timeout() = integer() >= 0 | infinity</v>
+ <v>Options = options()</v>
+ <v>options() = [option()]</v>
+ <v>option() = {sync, boolean()} |
+ {stream, stream_to()} |
+ {body_format, body_format()} |
+ {full_result, boolean()} |
+ {headers_as_is, boolean()}</v>
+ <v>stream_to() = self | {self, once} | filename() </v>
+ <v>body_format() = string() | binary() </v>
+ <v>Result = {status_line(), headers(), body()} |
+ {status_code(), body()} | request_id() </v>
+ <v>Profile = profile() </v>
+ <v>Reason = term() </v>
+ </type>
+
+ <desc>
+ <p>Sends a HTTP-request. The function can be both synchronous
+ and asynchronous. In the later case the function will return
+ {ok, RequestId} and later on message(s) will be sent to the
+ calling process on the format: </p>
+<pre>
+ {http, {RequestId, Result}}
+ {http, {RequestId, {error, Reason}}}
+ {http, {RequestId, stream_start, Headers}
+ {http, {RequestId, stream, BinBodyPart}
+ {http, {RequestId, stream_end, Headers}
+ {http, {RequestId, saved_to_file}}.
+</pre>
+
+ <p>Http option (<c>http_option()</c>) details: </p>
+ <taglist>
+ <tag><c><![CDATA[timeout]]></c></tag>
+ <item>
+ <p>Timeout time for the request. </p>
+ <p>Defaults to <c>infinity</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[connect_timeout]]></c></tag>
+ <item>
+ <p>Connection timeout time, used during the initial request,
+ when the client is connecting to the server. </p>
+ <p>Defaults to the value of the <c>timeout</c> option. </p>
+ </item>
+
+ <tag><c><![CDATA[ssl]]></c></tag>
+ <item>
+ <p>If using SSL, these SSL-specific options are used. </p>
+ <p>Defaults to <c>[]</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[autoredirect]]></c></tag>
+ <item>
+ <p>Should the client automatically retreive the information
+ from the new URI and return that as the result instead
+ of a 30X-result code. </p>
+ <p>Note that for some 30X-result codes automatic redirect
+ is not allowed in these cases the 30X-result will always
+ be returned. </p>
+ <p>Defaults to <c>true</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[proxy_auth]]></c></tag>
+ <item>
+ <p>A proxy-authorization header using the provided user name and
+ password will be added to the request. </p>
+ </item>
+
+ <tag><c><![CDATA[version]]></c></tag>
+ <item>
+ <p>Can be used to make the client act as an <c>HTTP/1.0</c> or
+ <c>HTTP/0.9</c> client. By default this is an <c>HTTP/1.1</c>
+ client. When using <c>HTTP/1.0</c> persistent connections will
+ not be used. </p>
+ <p>Defaults to the trsing <c>"HTTP/1.1"</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[relaxed]]></c></tag>
+ <item>
+ <p>If set to true workarounds for known server deviations from
+ the HTTP-standard are enabled. </p>
+ <p>Defaults to <c>false</c>. </p>
+ </item>
+
+ </taglist>
+
+ <p>Option (<c>option()</c>) details: </p>
+ <taglist>
+ <tag><c><![CDATA[sync]]></c></tag>
+ <item>
+ <p>Shall the request be synchronous or asynchronous. </p>
+ <p>Defaults to <c>true</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[stream]]></c></tag>
+ <item>
+ <p>Streams the body of a 200 or 206 response to the calling
+ process or to a file. When streaming to the calling process
+ using the option <c>self</c> the the following stream messages
+ will be sent to that process: {http, {RequestId,
+ stream_start, Headers}, {http, {RequestId, stream,
+ BinBodyPart}, {http, {RequestId, stream_end, Headers}. When
+ streaming to to the calling processes using the option
+ <c>{self once}</c> the first message will have an additional
+ element e.i. {http, {RequestId, stream_start, Headers, Pid},
+ this is the process id that should be used as an argument to
+ http:stream_next/1 to trigger the next message to be sent to
+ the calling process. </p>
+ <p>Note that it is possible that chunked encoding will add
+ headers so that there are more headers in the stream_end
+ message than in the stream_start.
+ When streaming to a file and the request is asynchronous the
+ message {http, {RequestId, saved_to_file}} will be sent. </p>
+ <p>Defaults to <c>none</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[body_format]]></c></tag>
+ <item>
+ <p>Defines if the body shall be delivered as a string or as a
+ binary. This option is only valid for the synchronous
+ request. </p>
+ <p>Defaults to <c>string</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[full_result]]></c></tag>
+ <item>
+ <p>Should a "full result" be returned to the caller (that is,
+ the body, the headers and the entire status-line) or not
+ (the body and the status code). </p>
+ <p>Defaults to <c>true</c>. </p>
+ </item>
+
+ <tag><c><![CDATA[header_as_is]]></c></tag>
+ <item>
+ <p>Shall the headers provided by the user be made
+ lower case or be regarded as case sensitive. </p>
+ <p>Note that the http standard requires them to be
+ case insenstive. This feature should only be used if there is
+ no other way to communicate with the server or for testing
+ purpose. Also note that when this option is used no headers
+ will be automatically added, all necessary headers has to be
+ provided by the user. </p>
+ <p>Defaults to <c>false</c>. </p>
+ </item>
+
+ </taglist>
+
+ <marker id="set_options"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>set_options(Options) -> </name>
+ <name>set_options(Options, Profile) -> ok | {error, Reason}</name>
+ <fsummary>Sets options to be used for subsequent requests.</fsummary>
+ <type>
+ <v>Options = [Option]</v>
+ <v>Option = {proxy, {Proxy, NoProxy}} | {max_sessions, MaxSessions} |
+ {max_keep_alive_length, MaxKeepAlive} | {keep_alive_timeout, KeepAliveTimeout} |
+ {max_pipeline_length, MaxPipeline} | {pipeline_timeout, PipelineTimeout} |
+ {cookies | CookieMode} |
+ {ipfamily, IpFamily} | {ip, IpAddress} | {port, Port} |
+ {verbose, VerboseMode} </v>
+ <v>Proxy = {Hostname, Port}</v>
+ <v>Hostname = string() </v>
+ <d>ex: "localhost" or "foo.bar.se"</d>
+ <v>Port = integer()</v>
+ <d>ex: 8080 </d>
+ <v>NoProxy = [NoProxyDesc]</v>
+ <v>NoProxyDesc = DomainDesc | HostName | IPDesc</v>
+ <v>DomainDesc = "*.Domain"</v>
+ <d>ex: "*.ericsson.se"</d>
+ <v>IpDesc = string()</v>
+ <d>ex: "134.138" or "[FEDC:BA98" (all IP-addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP-address).</d>
+ <v>MaxSessions = integer() </v>
+ <d>Default is <em>2</em>.
+ Maximum number of persistent connections to a host.</d>
+ <v>MaxKeepAlive = integer() </v>
+ <d>Default is <em>5</em>.
+ Maximum number of outstanding requests on the same connection to
+ a host.</d>
+ <v>KeepAliveTimeout = integer() </v>
+ <d>Default is <em>120000</em> (= 2 min).
+ If a persistent connection is idle longer than the
+ keep_alive_timeout the client will close the connection.
+ The server may also have a such a time out but you should
+ not count on it!</d>
+ <v>MaxPipeline = integer() </v>
+ <d>Default is <em>2</em>.
+ Maximum number of outstanding requests on a pipelined connection to a host.</d>
+ <v>PipelineTimeout = integer() </v>
+ <d>Default is <em>0</em>,
+ which will result in pipelining not being used.
+ If a persistent connection is idle longer than the
+ pipeline_timeout the client will close the connection. </d>
+ <v>CookieMode = enabled | disabled | verify </v>
+ <d>Default is <em>disabled</em>.
+ If Cookies are enabled all valid cookies will automatically be
+ saved in the client manager's cookie database.
+ If the option verify is used the function http:verify_cookie/2
+ has to be called for the cookie to be saved.</d>
+ <v>IpFamily = inet | inet6 | inet6fb4 </v>
+ <d>By default <em>inet</em>.
+ When it is set to <c>inet6fb4</c> you can use both ipv4 and ipv6.
+ It first tries <c>inet6</c> and if that does not works falls back to <c>inet</c>.
+ The option is here to provide a workaround for buggy ipv6 stacks to ensure that
+ ipv4 will always work.</d>
+ <v>IpAddress = ip_address() </v>
+ <d>If the host has several network interfaces, this option specifies which one to use.
+ See gen_tcp:connect/3,4 for more info. </d>
+ <v>Port = integer() </v>
+ <d>Specify which local port number to use.
+ See gen_tcp:connect/3,4 for more info. </d>
+ <v>VerboseMode = false | verbose | debug | trace </v>
+ <d>Default is <em>false</em>.
+ This option is used to switch on (or off)
+ different levels of erlang trace on the client.
+ It is a debug feature.</d>
+ <v>Profile = profile()</v>
+ </type>
+ <desc>
+ <p>Sets options to be used for subsequent
+ requests.</p>
+ <note>
+ <p>If possible the client will keep its connections
+ alive and use persistent connections
+ with or without pipeline depending on configuration
+ and current circumstances. The HTTP/1.1 specification does not
+ provide a guideline for how many requests that would be
+ ideal to be sent on a persistent connection,
+ this very much depends on the
+ application. Note that a very long queue of requests may cause a
+ user perceived delays as earlier request may take a long time
+ to complete. The HTTP/1.1 specification does suggest a
+ limit of 2 persistent connections per server, which is the
+ default value of the max_sessions option. </p>
+ </note>
+
+ <marker id="stream_next"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>stream_next(Pid) -> ok</name>
+ <fsummary> Triggers the next message to be streamed, e.i.
+ same behavior as active once for sockets.
+ </fsummary>
+ <type>
+ <v>Pid = pid() - as received in the stream_start message</v>
+ </type>
+ <desc>
+ <p>Triggers the next message to be streamed, e.i.
+ same behavior as active once for sockets.</p>
+
+ <marker id="verify_cookie"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>verify_cookie(SetCookieHeaders, Url) -> </name>
+ <name>verify_cookie(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name>
+ <fsummary>Saves the cookies defined in SetCookieHeaders in the client profile's cookie database.</fsummary>
+ <type>
+ <v>SetCookieHeaders = headers() - where field = "set-cookie"</v>
+ <v>Url = url()</v>
+ <v>Profile = profile()</v>
+ </type>
+ <desc>
+ <p>Saves the cookies defined in SetCookieHeaders
+ in the client profile's cookie database. You need to
+ call this function if you set the option cookies to verify.
+ If no profile is specified the default profile will be used.
+ </p>
+
+ <marker id="cookie_header"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>cookie_header(Url) -> </name>
+ <name>cookie_header(Url, Profile) -> header() | {error, Rason}</name>
+ <fsummary>Returns the cookie header that would be sent when
+ making a request to Url using the profile Profile.</fsummary>
+ <type>
+ <v>Url = url()</v>
+ <v>Profile = profile()</v>
+ </type>
+ <desc>
+ <p>Returns the cookie header that would be sent
+ when making a request to Url using the profile Profile.
+ If no profile is specified the default profile will be used.
+ </p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>,
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </p>
+ </section>
+
+</erlref>
+
diff --git a/lib/inets/doc/src/http_client.xml b/lib/inets/doc/src/http_client.xml
new file mode 100644
index 0000000000..510c30eb35
--- /dev/null
+++ b/lib/inets/doc/src/http_client.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>HTTP Client</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>http_client.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+
+ <p>The HTTP client default profile will be started when the inets
+ application is started and is then available to all processes on
+ that erlang node. Other profiles may also be started at
+ application startup, or profiles can be started and stopped
+ dynamically in runtime. Each client profile will spawn a new
+ process to handle each request unless there is a possibility to use
+ a persistent connection with or without pipelining.
+ The client will add a host header and an empty
+ te header if there are no such headers present in the request.</p>
+
+ <p>The clients supports ipv6 as long as the underlying mechanisms also do
+ so.</p>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <p> What to put in the erlang node application configuration file
+ in order to start a profile at application startup.</p>
+ <pre>
+ [{inets, [{services, [{httpc, PropertyList}]}]}]
+ </pre>
+ <p>For valid properties see <seealso
+ marker="http">http(3)</seealso></p>
+ </section>
+
+ <section>
+ <title>Using the HTTP Client API</title>
+ <code type="erl">
+ 1 > inets:start().
+ ok
+ </code>
+ <p> The following calls uses the default client profile.
+ Use the proxy "www-proxy.mycompany.com:8000",
+ but not for requests to localhost. This will apply to all subsequent
+ requests</p>
+ <code type="erl">
+ 2 > http:set_options([{proxy, {{"www-proxy.mycompany.com", 8000},
+ ["localhost"]}}]).
+ ok
+ </code>
+ <p>An ordinary synchronous request. </p>
+ <code type="erl">
+ 3 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} =
+ http:request(get, {"http://www.erlang.org", []}, [], []).
+ </code>
+ <p>With all default values, as above, a get request can also be written
+ like this.</p>
+ <code type="erl">
+ 4 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} =
+ http:request("http://www.erlang.org").
+ </code>
+ <p>An ordinary asynchronous request. The result will be sent
+ to the calling process on the form {http, {ReqestId, Result}}</p>
+ <code type="erl">
+ 5 > {ok, RequestId} =
+ http:request(get, {"http://www.erlang.org", []}, [], [{sync, false}]).
+ </code>
+ <p>In this case the calling process is the shell, so we receive the
+ result.</p>
+ <code type="erl">
+ 6 > receive {http, {RequestId, Result}} -> ok after 500 -> error end.
+ ok
+ </code>
+ <p>Send a request with a specified connection header. </p>
+ <code type="erl">
+ 7 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} =
+ http:request(get, {"http://www.erlang.org", [{"connection", "close"}]},
+ [], []).
+ </code>
+
+ <p>Start a HTTP client profile. </p>
+
+ <code><![CDATA[
+ 8 > {ok, Pid} = inets:start(httpc, [{profile, foo}]).
+ {ok, <0.45.0>}
+ ]]></code>
+
+ <p>The new profile has no proxy settings so the connection will
+ be refused</p>
+ <code type="erl">
+ 9 > http:request("http://www.erlang.org", foo).
+ {error,econnrefused}
+ </code>
+
+ <p>Stop a HTTP client profile. </p>
+ <code type="erl">
+ 10 > inets:stop(httpc, foo).
+ ok
+ </code>
+
+ <p>Alternatively:</p>
+ <code type="erl">
+ 10 > inets:stop(httpc, Pid).
+ ok
+ </code>
+
+
+ </section>
+</chapter>
+
+
+
+
diff --git a/lib/inets/doc/src/http_server.xml b/lib/inets/doc/src/http_server.xml
new file mode 100644
index 0000000000..56317d647c
--- /dev/null
+++ b/lib/inets/doc/src/http_server.xml
@@ -0,0 +1,1004 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>HTTP server </title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>http_server.xml</file>
+ </header>
+
+ <section>
+ <title>Introduction</title>
+
+ <p>The HTTP server, also referred to as httpd, handles HTTP requests
+ as described in RFC 2616 with a few exceptions such as gateway
+ and proxy functionality. The server supports ipv6 as long as the
+ underlying mechanisms also do so. </p>
+
+ <p>The server implements numerous features such as SSL (Secure Sockets
+ Layer), ESI (Erlang Scripting Interface), CGI (Common Gateway
+ Interface), User Authentication(using Mnesia, dets or plain text
+ database), Common Logfile Format (with or without disk_log(3)
+ support), URL Aliasing, Action Mappings, Directory Listings and SSI
+ (Server-Side Includes).</p>
+
+ <p>The configuration of the server is provided as an erlang
+ property list, and for backwards compatibility also a configuration
+ file using apache-style configuration directives is
+ supported.</p>
+
+ <p>As of inets version 5.0 the HTTP server is an easy to
+ start/stop and customize web server that provides the most basic
+ web server functionality. Depending on your needs there
+ are also other erlang based web servers that may be of interest
+ such as Yaws, http://yaws.hyber.org, that for instance has its own
+ markup support to generate html, and supports certain buzzword
+ technologies such as SOAP.</p>
+
+ <p>Allmost all server functionality has been implemented using an
+ especially crafted server API, it is described in the Erlang Web
+ Server API. This API can be used to advantage by all who wants
+ to enhance the server core functionality, for example custom
+ logging and authentication.</p>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <p> What to put in the erlang node application configuration file
+ in order to start a http server at application startup.</p>
+
+ <code type="erl">
+ [{inets, [{services, [{httpd, [{proplist_file,
+ "/var/tmp/server_root/conf/8888_props.conf"}]},
+ {httpd, [{proplist_file,
+ "/var/tmp/server_root/conf/8080_props.conf"}]}]}]}].
+ </code>
+
+ <p>The server is configured using an erlang property list.
+ For the available properties see
+ <seealso marker="inets:inets">httpd(3)</seealso>
+ For backwards compatibility also apache-like config files
+ are supported.
+ </p>
+
+ <p>All possible config properties are as follows </p>
+ <code type="none">
+ httpd_service() -> {httpd, httpd()}
+ httpd() -> [httpd_config()]
+ httpd_config() -> {file, file()} |
+ {proplist_file, file()}
+ {debug, debug()} |
+ {accept_timeout, integer()}
+ debug() -> disable | [debug_options()]
+ debug_options() -> {all_functions, modules()} |
+ {exported_functions, modules()} |
+ {disable, modules()}
+ modules() -> [atom()]
+ </code>
+ <p>{proplist_file, file()} File containing an erlang property
+ list, followed by a full stop, describing the HTTP server
+ configuration.</p>
+ <p>{file, file()} If you use an old apace-like configuration file.</p>
+ <p>{debug, debug()} - Can enable trace on all
+ functions or only exported functions on chosen modules.</p>
+ <p>{accept_timeout, integer()} sets the wanted timeout value for
+ the server to set up a request connection.</p>
+ </section>
+
+ <section>
+ <title>Using the HTTP Server API</title>
+ <code type="none">
+ 1 > inets:start().
+ ok
+ </code>
+ <p> Start a HTTP server with minimal
+ required configuration. Note that if you
+ specify port 0 an arbitrary available port will be
+ used and you can use the info function to find out
+ which port number that was picked.
+ </p>
+
+ <code type="none">
+ 2 > {ok, Pid} = inets:start(httpd, [{port, 0},
+ {server_name,"httpd_test"}, {server_root,"/tmp"},
+ {document_root,"/tmp/htdocs"}, {bind_address, "localhost"}]).
+ {ok, 0.79.0}
+ </code>
+
+ <code type="none">
+ 3 > httpd:info(Pid).
+ [{mime_types,[{"html","text/html"},{"htm","text/html"}]},
+ {server_name,"httpd_test"},
+ {bind_address, {127,0,0,1}},
+ {server_root,"/tmp"},
+ {port,59408},
+ {document_root,"/tmp/htdocs"}]
+ </code>
+
+ <p> Reload the configuration without restarting the server.
+ Note port and bind_address can not be changed. Clients
+ trying to access the server during the reload will
+ get a service temporary unavailable answer.
+ </p>
+ <code type="none">
+ 4 > httpd:reload_config([{port, 59408},
+ {server_name,"httpd_test"}, {server_root,"/tmp/www_test"},
+ {document_root,"/tmp/www_test/htdocs"},
+ {bind_address, "localhost"}], non_disturbing).
+ ok.
+ </code>
+
+ <code type="none">
+ 5 > httpd:info(Pid, [server_root, document_root]).
+ [{server_root,"/tmp/www_test"},{document_root,"/tmp/www_test/htdocs"}]
+ </code>
+
+ <code type="none">
+ 6 > ok = inets:stop(httpd, Pid).
+ </code>
+
+ <p> Alternative:</p>
+
+ <code type="none">
+ 6 > ok = inets:stop(httpd, {{127,0,0,1}, 59408}).
+ </code>
+
+ <p>Note that bind_address has to be
+ the ip address reported by the info function and can
+ not be the hostname that is allowed when inputting bind_address.</p>
+
+ </section>
+
+ <section>
+ <title>Htaccess - User Configurable Authentication.</title>
+ <p>If users of the web server needs to manage authentication of
+ web pages that are local to their user and do not have
+ server administrative privileges. They can use the
+ per-directory runtime configurable user-authentication scheme
+ that Inets calls htaccess. It works the following way: </p>
+ <list type="bulleted">
+ <item>Each directory in the path to the requested asset is
+ searched for an access-file (default .htaccess), that restricts
+ the web servers rights to respond to a request. If an access-file
+ is found the rules in that file is applied to the
+ request. </item>
+ <item>The rules in an access-file applies both to files in the same
+ directories and in subdirectories. If there exists more than one
+ access-file in the path to an asset, the rules in the
+ access-file nearest the requested asset will be applied.</item>
+ <item>To change the rules that restricts the use of
+ an asset. The user only needs to have write access
+ to the directory where the asset exists.</item>
+ <item>All the access-files in the path to a requested asset is read
+ once per request, this means that the load on the server will
+ increase when this scheme is used.</item>
+ <item>If a directory is
+ limited both by auth directives in the HTTP server configuration
+ file and by the htaccess files. The user must be allowed to get
+ access the file by both methods for the request to succeed.</item>
+ </list>
+
+ <section>
+ <title>Access Files Directives</title>
+ <p>In every directory under the <c>DocumentRoot</c> or under an
+ <c>Alias</c> a user can place an access-file. An access-file
+ is a plain text file that specify the restrictions that
+ shall be considered before the web server answer to a
+ request. If there are more than one access-file in the path
+ to the requested asset, the directives in the access-file in
+ the directory nearest the asset will be used.</p>
+ <list type="bulleted">
+ <item>
+ <p><em>DIRECTIVE: "allow"</em></p>
+ <p><em>Syntax:</em><c>Allow</c> from subnet subnet|from all <br></br>
+<em>Default:</em><c>from all </c> <br></br>
+</p>
+ <p>Same as the directive allow for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AllowOverRide"</em></p>
+ <p><em>Syntax:</em><c>AllowOverRide</c> all | none |
+ Directives <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+<c>AllowOverRide</c> Specify which parameters that not
+ access-files in subdirectories are allowed to alter the value
+ for. If the parameter is set to none no more
+ access-files will be parsed.
+ </p>
+ <p>If only one access-file exists setting this parameter to
+ none can lessen the burden on the server since the server
+ will stop looking for access-files.</p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthGroupfile"</em></p>
+ <p><em>Syntax:</em><c>AuthGroupFile</c> Filename <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p>AuthGroupFile indicates which file that contains the list
+ of groups. Filename must contain the absolute path to the
+ file. The format of the file is one group per row and
+ every row contains the name of the group and the members
+ of the group separated by a space, for example:</p>
+ <pre>
+\011 GroupName: Member1 Member2 .... MemberN
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthName"</em></p>
+ <p><em>Syntax:</em><c>AuthName</c> auth-domain <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p>Same as the directive AuthName for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthType"</em></p>
+ <p><em>Syntax:</em><c>AuthType</c> Basic <br></br>
+<em>Default:</em><c>Basic</c> <br></br>
+</p>
+ <p><c>AuthType</c> Specify which authentication scheme that shall
+ be used. Today only Basic Authenticating using UUEncoding of
+ the password and user ID is implemented. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "AuthUserFile"</em></p>
+ <p><em>Syntax:</em><c>AuthUserFile</c> Filename <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+</p>
+ <p><c>AuthUserFile</c> indicate which file that contains the list
+ of users. Filename must contain the absolute path to the
+ file. The users name and password are not encrypted so do not
+ place the file with users in a directory that is accessible
+ via the web server. The format of the file is one user per row
+ and every row contains User Name and Password separated by a
+ colon, for example:</p>
+ <pre>
+\011 UserName:Password
+\011 UserName:Password
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "deny"</em></p>
+ <p><em>Syntax:</em><c>deny</c> from subnet subnet|from all <br></br>
+<em>Context:</em> Limit</p>
+ <p>Same as the directive deny for the server config file. </p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "Limit"</em> <br></br>
+</p>
+ <p><em>Syntax:</em><c><![CDATA[<Limit]]></c> RequestMethods<c>></c> <br></br>
+<em>Default:</em> - None - <br></br>
+</p>
+ <p><c><![CDATA[<Limit>]]></c> and &lt;/Limit&gt; are used to enclose
+ a group of directives which applies only to requests using
+ the specified methods. If no request method is specified
+ all request methods are verified against the restrictions.</p>
+ <pre>
+\011 &lt;Limit POST GET HEAD&gt;
+\011 order allow deny
+\011 require group group1
+\011 allow from 123.145.244.5
+\011 &lt;/Limit&gt;
+ </pre>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "order"</em> <br></br>
+<em>Syntax:</em><c>order</c> allow deny | deny allow <br></br>
+<em>Default:</em> allow deny <br></br>
+</p>
+ <p><c>order</c>, defines if the deny or allow control shall
+ be preformed first.</p>
+ <p>If the order is set to allow deny, then first the users
+ network address is controlled to be in the allow subset. If
+ the users network address is not in the allowed subset he will
+ be denied to get the asset. If the network-address is in the
+ allowed subset then a second control will be preformed, that
+ the users network address is not in the subset of network
+ addresses that shall be denied as specified by the deny
+ parameter.</p>
+ <p>If the order is set to deny allow then only users from networks
+ specified to be in the allowed subset will succeed to request
+ assets in the limited area.</p>
+ </item>
+ <item>
+ <p><em>DIRECTIVE: "require"</em></p>
+ <p><em>Syntax:</em><c>require</c>
+ group group1 group2...|user user1 user2... <br></br>
+<em>Default:</em><c>- None -</c> <br></br>
+<em>Context:</em> Limit <br></br>
+</p>
+ <p>See the require directive in the documentation of mod_auth(3)
+ for more information.</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Dynamic Web Pages</title>
+ <p>The Inets HTTP server provides two ways of creating dynamic web
+ pages, each with its own advantages and disadvantages. </p>
+ <p>First there are CGI-scripts that can be written in any programming
+ language. CGI-scripts are standardized and supported by most
+ web servers. The drawback with CGI-scripts is that they are resource
+ intensive because of their design. CGI requires the server to fork a
+ new OS process for each executable it needs to start. </p>
+ <p>Second there are ESI-functions that provide a tight and efficient
+ interface to the execution of Erlang functions, this interface
+ on the other hand is Inets specific. </p>
+
+ <section>
+ <title>The Common Gateway Interface (CGI) Version 1.1, RFC 3875.</title>
+ <p>The mod_cgi module makes it possible to execute CGI scripts
+ in the server. A file that matches the definition of a
+ ScriptAlias config directive is treated as a CGI script. A CGI
+ script is executed by the server and it's output is returned to
+ the client. </p>
+ <p>The CGI Script response comprises a message-header and a
+ message-body, separated by a blank line. The message-header
+ contains one or more header fields. The body may be
+ empty. Example: </p>
+ <code type="none">
+"Content-Type:text/plain\
+Accept-Ranges:none\
+\
+some very
+\011plain text" </code>
+ <p>The server will interpret the cgi-headers and most of them
+ will be transformed into HTTP headers and sent back to the
+ client together with the body.</p>
+ <p>Support for CGI-1.1 is implemented in accordance with the RFC
+ 3875. </p>
+ </section>
+
+ <section>
+ <title>Erlang Server Interface (ESI)</title>
+ <p>The erlang server interface is implemented by the
+ module mod_esi.</p>
+
+ <section>
+ <title>ERL Scheme </title>
+ <p>The erl scheme is designed to mimic plain CGI, but without
+ the extra overhead. An URL which calls an Erlang erl function
+ has the following syntax (regular expression): </p>
+ <code type="none">
+\011 http://your.server.org/***/Module[:/]Function(?QueryString|/PathInfo)
+ </code>
+ <p>*** above depends on how the ErlScriptAlias config
+ directive has been used</p>
+ <p>The module (Module) referred to must be found in the code
+ path, and it must define a function (Function) with an arity
+ of two or three. It is preferable to implement a funtion
+ with arity three as it permits you to send chunks of the
+ webpage beeing generated to the client during the generation
+ phase instead of first generating the whole web page and
+ then sending it to the client. The option to implement a
+ function with arity two is only kept for
+ backwardcompatibilty reasons.
+ See <seealso marker="mod_esi">mod_esi(3)</seealso> for
+ implementation details of the esi callback function.</p>
+ </section>
+
+ <section>
+ <title>EVAL Scheme </title>
+ <p>The eval scheme is straight-forward and does not mimic the
+ behavior of plain CGI. An URL which calls an Erlang eval
+ function has the following syntax:</p>
+ <code type="none">
+http://your.server.org/***/Mod:Func(Arg1,...,ArgN)
+ </code>
+ <p>*** above depends on how the ErlScriptAlias config
+ directive has been used</p>
+ <p>The module (Mod) referred to must be found in the code
+ path, and data returned by the function (Func) is passed
+ back to the client. Data returned from the
+ function must furthermore take the form as specified in
+ the CGI specification. See <seealso marker="mod_esi">mod_esi(3)</seealso> for implementation details of the esi
+ callback function.</p>
+ <note>
+ <p>The eval scheme can seriously threaten the
+ integrity of the Erlang node housing a Web server, for
+ example: </p>
+ <code type="none">
+http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[])))
+ </code>
+ <p>which effectively will close down the Erlang node,
+ that is use the erl scheme instead, until this
+ security breach has been fixed.</p>
+ <p>Today there are no good way of solving this problem
+ and therefore Eval Scheme may be removed in future
+ release of Inets. </p>
+ </note>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Logging </title>
+ <p>There are three types of logs supported. Transfer logs,
+ security logs and error logs. The de-facto standard Common
+ Logfile Format is used for the transfer and security logging.
+ There are numerous statistics programs available to analyze Common
+ Logfile Format. The Common Logfile Format looks as follows:
+ </p>
+ <p><em>remotehost rfc931 authuser [date] "request" status bytes</em></p>
+ <taglist>
+ <tag><em>remotehost</em></tag>
+ <item>Remote hostname</item>
+ <tag><em>rfc931</em></tag>
+ <item>The client's remote username (RFC 931).</item>
+ <tag><em>authuser</em></tag>
+ <item>The username with which the user authenticated himself.</item>
+ <tag><em>[date]</em></tag>
+ <item>Date and time of the request (RFC 1123).</item>
+ <tag><em>"request"</em></tag>
+ <item>The request line exactly as it came from the client (RFC 1945).</item>
+ <tag><em>status</em></tag>
+ <item>The HTTP status code returned to the client (RFC 1945).</item>
+ <tag><em>bytes</em></tag>
+ <item>The content-length of the document transferred. </item>
+ </taglist>
+ <p>Internal server errors are recorde in the error log file. The
+ format of this file is a more ad hoc format than the logs using
+ Common Logfile Format, but conforms to the following syntax:
+ </p>
+ <p><em>[date]</em> access to <em>path</em> failed for
+ <em>remotehost</em>, reason: <em>reason</em></p>
+ </section>
+
+ <section>
+ <title>Server Side Includes</title>
+ <p>Server Side Includes enables the server to run code embedded
+ in HTML pages to generate the response to the client.</p>
+ <note>
+ <p>Having the server parse HTML pages is a double edged sword!
+ It can be costly for a heavily loaded server to perform
+ parsing of HTML pages while sending them. Furthermore, it can
+ be considered a security risk to have average users executing
+ commands in the name of the Erlang node user. Carefully
+ consider these items before activating server-side includes.</p>
+ </note>
+
+ <section>
+ <marker id="ssi_setup"></marker>
+ <title>SERVER-SIDE INCLUDES (SSI) SETUP</title>
+ <p>The server must be told which filename extensions to be used
+ for the parsed files. These files, while very similar to HTML,
+ are not HTML and are thus not treated the same. Internally, the
+ server uses the magic MIME type <c>text/x-server-parsed-html</c>
+ to identify parsed documents. It will then perform a format
+ conversion to change these files into HTML for the
+ client. Update the <c>mime.types</c> file, as described in the
+ Mime Type Settings, to tell the server which extension to use
+ for parsed files, for example:
+ </p>
+ <pre>
+\011text/x-server-parsed-html shtml shtm
+ </pre>
+ <p>This makes files ending with <c>.shtml</c> and <c>.shtm</c>
+ into parsed files. Alternatively, if the performance hit is not a
+ problem, <em>all</em> HTML pages can be marked as parsed:
+ </p>
+ <pre>
+\011text/x-server-parsed-html html htm
+ </pre>
+ </section>
+
+ <section>
+ <marker id="ssi_format"></marker>
+ <title>Server-Side Includes (SSI) Format</title>
+ <p>All server-side include directives to the server are formatted
+ as SGML comments within the HTML page. This is in case the
+ document should ever find itself in the client's hands
+ unparsed. Each directive has the following format:
+ </p>
+ <pre>
+\011&lt;!--#command tag1="value1" tag2="value2" --&gt;
+ </pre>
+ <p>Each command takes different arguments, most only accept one
+ tag at a time. Here is a breakdown of the commands and their
+ associated tags:
+ </p>
+ <p>The config directive controls various aspects of the
+ file parsing. There are two valid tags:
+ </p>
+ <taglist>
+ <tag><c>errmsg</c></tag>
+ <item>
+ <p>controls the message sent back to the client if an
+ error occurred while parsing the document. All errors are
+ logged in the server's error log.</p>
+ </item>
+ <tag><c>sizefmt</c></tag>
+ <item>
+ <p>determines the format used to display the size of
+ a file. Valid choices are <c>bytes</c> or
+ <c>abbrev</c>. <c>bytes</c> for a formatted byte count
+ or <c>abbrev</c> for an abbreviated version displaying
+ the number of kilobytes.</p>
+ </item>
+ </taglist>
+ <p>The include directory
+ will insert the text of a document into the parsed
+ document. This command accepts two tags:</p>
+ <taglist>
+ <tag><c>virtual</c></tag>
+ <item>
+ <p>gives a virtual path to a document on the
+ server. Only normal files and other parsed documents can
+ be accessed in this way.</p>
+ </item>
+ <tag><c>file</c></tag>
+ <item>
+ <p>gives a pathname relative to the current
+ directory. <c>../</c> cannot be used in this pathname, nor
+ can absolute paths. As above, you can send other parsed
+ documents, but you cannot send CGI scripts.</p>
+ </item>
+ </taglist>
+ <p>The echo directive prints the value of one of the include
+ variables (defined below). The only valid tag to this
+ command is <c>var</c>, whose value is the name of the
+ variable you wish to echo.</p>
+ <p>The fsize directive prints the size of the specified
+ file. Valid tags are the same as with the <c>include</c>
+ command. The resulting format of this command is subject
+ to the <c>sizefmt</c> parameter to the <c>config</c>
+ command.</p>
+ <p>The lastmod directive prints the last modification date of
+ the specified file. Valid tags are the same as with the
+ <c>include</c> command.</p>
+ <p>The exec directive executes a given shell command or CGI
+ script. Valid tags are:</p>
+ <taglist>
+ <tag><c>cmd</c></tag>
+ <item>
+ <p>executes the given string using <c>/bin/sh</c>. All
+ of the variables defined below are defined, and can be
+ used in the command.</p>
+ </item>
+ <tag><c>cgi</c></tag>
+ <item>
+ <p>executes the given virtual path to a CGI script and
+ includes its output. The server does not perform error
+ checking on the script output.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <marker id="ssi_environment_variables"></marker>
+ <title>Server-Side Includes (SSI) Environment Variables</title>
+ <p>A number of variables are made available to parsed
+ documents. In addition to the CGI variable set, the following
+ variables are made available:
+ </p>
+ <taglist>
+ <tag><c>DOCUMENT_NAME</c></tag>
+ <item>
+ <p>The current filename.</p>
+ </item>
+ <tag><c>DOCUMENT_URI</c></tag>
+ <item>
+ <p>The virtual path to this document (such as
+ <c>/docs/tutorials/foo.shtml</c>).</p>
+ </item>
+ <tag><c>QUERY_STRING_UNESCAPED</c></tag>
+ <item>
+ <p>The unescaped version of any search query the client
+ sent, with all shell-special characters escaped with
+ <c>\\</c>.</p>
+ </item>
+ <tag><c>DATE_LOCAL</c></tag>
+ <item>
+ <p>The current date, local time zone.</p>
+ </item>
+ <tag><c>DATE_GMT</c></tag>
+ <item>
+ <p>Same as DATE_LOCAL but in Greenwich mean time.</p>
+ </item>
+ <tag><c>LAST_MODIFIED</c></tag>
+ <item>
+ <p>The last modification date of the current document.</p>
+ </item>
+ </taglist>
+ </section>
+ </section>
+
+ <section>
+ <title>The Erlang Web Server API</title>
+ <p>The process of handling a HTTP request involves several steps
+ such as:</p>
+ <list type="bulleted">
+ <item>Seting up connections, sending and receiving data.</item>
+ <item>URI to filename translation</item>
+ <item>Authenication/access checks.</item>
+ <item>Retriving/generating the response.</item>
+ <item>Logging</item>
+ </list>
+ <p>To provide customization and extensibility of the HTTP servers
+ request handling most of these steps are handled by one or more
+ modules that may be replaced or removed at runtime, and of course
+ new ones can be added. For each request all modules will be
+ traversed in the order specified by the modules directive in the
+ server configuration file. Some parts mainly the communication
+ related steps are considered server core functionality and are
+ not implemented using the Erlang Web Server API. A description of
+ functionality implemented by the Erlang Webserver API is described
+ in the section Inets Webserver Modules.</p>
+ <p>A module can use data generated by previous modules in the
+ Erlang Webserver API module sequence or generate data to be used
+ by consecutive Erlang Web Server API modules. This is made
+ possible due to an internal list of key-value tuples, also referred to
+ as interaction data. </p>
+ <note>
+ <p>Interaction data enforces module dependencies and
+ should be avoided if possible. This means the order
+ of modules in the Modules property is significant.</p>
+ </note>
+
+ <section>
+ <title>API Description</title>
+ <p>Each module implements server functionality
+ using the Erlang Web Server API should implement the following
+ call back functions:</p>
+ <list type="bulleted">
+ <item>do/1 (mandatory) - the function called when
+ a request should be handled.</item>
+ <item>load/2</item>
+ <item>store/2</item>
+ <item>remove/1</item>
+ </list>
+ <p>The latter functions are needed only when new config
+ directives are to be introduced. For details see
+ <seealso marker="httpd">httpd(3)</seealso></p>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets Web Server Modules</title> <p>The convention is that
+ all modules implementing some webserver functionality has the
+ name mod_*. When configuring the web server an appropriate
+ selection of these modules should be present in the Module
+ directive. Please note that there are some interaction dependencies
+ to take into account so the order of the modules can not be
+ totally random.</p>
+
+ <section>
+ <title>mod_action - Filetype/Method-Based Script Execution.</title>
+ <p>Runs CGI scripts whenever a file of a
+ certain type or HTTP method (See RFC 1945) is requested.
+ </p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data, if possible:
+ </p>
+ <taglist>
+ <tag><c>{new_request_uri, RequestURI}</c></tag>
+ <item>An alternative <c>RequestURI</c> has been generated.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_alias - URL Aliasing</title>
+ <p>This module makes it possible to map different parts of the
+ host file system into the document tree e.i. creates aliases and
+ redirections.</p>
+ <p>Exports the following Erlang Web Server API interaction data, if possible:
+ </p>
+ <taglist>
+ <tag><c>{real_name, PathData}</c></tag>
+ <item>PathData is the argument used for API function mod_alias:path/3.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_auth - User Authentication </title>
+ <p>This module provides for basic user authentication using
+ textual files, dets databases as well as mnesia databases.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{remote_user, User}</c></tag>
+ <item>The user name with which the user has authenticated himself.</item>
+ </taglist>
+
+
+ <section>
+ <title>Mnesia as Authentication Database</title>
+
+ <p> If Mnesia is used as storage method, Mnesia must be
+ started prio to the HTTP server. The first time Mnesia is
+ started the schema and the tables must be created before
+ Mnesia is started. A naive example of a module with two
+ functions that creates and start mnesia is provided
+ here. The function shall be used the first
+ time. first_start/0 creates the schema and the tables. The
+ second function start/0 shall be used in consecutive
+ startups. start/0 Starts Mnesia and wait for the tables to
+ be initiated. This function must only be used when the
+ schema and the tables already is created. </p>
+
+ <code>
+ -module(mnesia_test).
+ -export([start/0,load_data/0]).
+ -include("mod_auth.hrl").
+
+ first_start()->
+ mnesia:create_schema([node()]),
+ mnesia:start(),
+ mnesia:create_table(httpd_user,
+ [{type,bag},{disc_copies,[node()]},
+ {attributes,record_info(fields,httpd_user)}]),
+ mnesia:create_table(httpd_group,
+ [{type,bag},{disc_copies,[node()]},
+ {attributes,record_info(fields,httpd_group)}]),
+ mnesia:wait_for_tables([httpd_user,httpd_group],60000).
+
+ start()->
+ mnesia:start(),
+ mnesia:wait_for_tables([httpd_user,httpd_group],60000).
+ </code>
+
+ <p>To create the Mnesia tables we use two records defined in
+ mod_auth.hrl so the file must be included. The first
+ function first_start/0 creates a schema that specify on
+ which nodes the database shall reside. Then it starts Mnesia
+ and creates the tables. The first argument is the name of
+ the tables, the second argument is a list of options how the
+ table will be created, see Mnesia documentation for more
+ information. Since the current implementation of the
+ mod_auth_mnesia saves one row for each user the type must be
+ bag. When the schema and the tables is created the second
+ function start/0 shall be used to start Mensia. It starts
+ Mnesia and wait for the tables to be loaded. Mnesia use the
+ directory specified as mnesia_dir at startup if specified,
+ otherwise Mnesia use the current directory. For security
+ reasons, make sure that the Mnesia tables are stored outside
+ the document tree of the HTTP server. If it is placed in the
+ directory which it protects, clients will be able to
+ download the tables. Only the dets and mnesia storage
+ methods allow writing of dynamic user data to disk. plain is
+ a read only method.</p>
+ </section>
+
+ </section>
+
+ <section>
+ <title>mod_cgi - CGI Scripts</title>
+ <p>This module handles invoking of CGI scripts</p>
+ </section>
+
+ <section>
+ <title>mod_dir - Directories</title>
+ <p>This module generates an HTML directory listing
+ (Apache-style) if a client sends a request for a directory
+ instead of a file. This module needs to be removed from the
+ Modules config directive if directory listings is unwanted.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c>.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_disk_log - Logging Using disk_log.</title>
+ <p>Standard logging using the "Common Logfile Format" and
+ disk_log(3).</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_esi - Erlang Server Interface</title>
+ <p>This module implements
+ the Erlang Server Interface (ESI) that provides a tight and
+ efficient interface to the execution of Erlang functions. </p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c></item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_get - Regular GET Requests</title>
+ <p>This module is responsible for handling GET requests to regular
+ files. GET requests for parts of files is handled by mod_range.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_head - Regular HEAD Requests</title>
+ <p>This module is responsible for handling HEAD requests to regular
+ files. HEAD requests for dynamic content is handled by each module
+ responsible for dynamic content.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_htaccess - User Configurable Access</title>
+ <p>This module provides per-directory user configurable access
+ control.</p>
+ <p>Uses the following Erlang Web Server API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Web Server API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{remote_user_name, User}</c></tag>
+ <item>The user name with which the user has authenticated himself.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_include - SSI</title>
+ <p>This module makes it possible to expand "macros" embedded in
+ HTML pages before they are delivered to the client, that is
+ Server-Side Includes (SSI).
+ </p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ <item>remote_user - from mod_auth</item>
+ </list>
+ <p>Exports the following Erlang Webserver API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{mime_type, MimeType}</c></tag>
+ <item>The file suffix of the incoming URL mapped into a
+ <c>MimeType</c> as defined in the Mime Type Settings
+ section.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_log - Logging Using Text Files.</title>
+ <p>Standard logging using the "Common Logfile Format" and text
+ files.</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>remote_user - from mod_auth</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_range - Requests with Range Headers</title>
+ <p>This module response to requests for one or many ranges of a
+ file. This is especially useful when downloading large files,
+ since a broken download may be resumed.</p>
+ <p>Note that request for multiple parts of a document will report a
+ size of zero to the log file.</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ </section>
+
+ <section>
+ <title>mod_response_control - Requests with If* Headers</title>
+ <p>This module controls that the conditions in the requests is
+ fulfilled. For example a request may specify that the answer
+ only is of interest if the content is unchanged since last
+ retrieval. Or if the content is changed the range-request shall
+ be converted to a request for the whole file instead.</p> <p>If
+ a client sends more then one of the header fields that restricts
+ the servers right to respond, the standard does not specify how
+ this shall be handled. httpd will control each field in the
+ following order and if one of the fields not match the current
+ state the request will be rejected with a proper response.
+ <br></br>
+
+ 1.If-modified <br></br>
+
+ 2.If-Unmodified <br></br>
+
+ 3.If-Match <br></br>
+
+ 4.If-Nomatch <br></br>
+</p>
+ <p>Uses the following Erlang Webserver API interaction data:
+ </p>
+ <list type="bulleted">
+ <item>real_name - from mod_alias</item>
+ </list>
+ <p>Exports the following Erlang Webserver API interaction data:
+ </p>
+ <taglist>
+ <tag><c>{if_range, send_file}</c></tag>
+ <item>The conditions for the range request was not fulfilled.
+ The response must not be treated as a range request, instead it
+ must be treated as a ordinary get request. </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>mod_security - Security Filter</title>
+ <p>This module serves as a filter for authenticated requests
+ handled in mod_auth. It provides possibility to restrict users
+ from access for a specified amount of time if they fail to
+ authenticate several times. It logs failed authentication as
+ well as blocking of users, and it also calls a configurable
+ call-back module when the events occur. </p>
+ <p>There is also an
+ API to manually block, unblock and list blocked users or users,
+ who have been authenticated within a configurable amount of
+ time.</p>
+ </section>
+
+ <section>
+ <title>mod_trace - TRACE Request</title>
+ <p>mod_trace is responsible for handling of TRACE requests.
+ Trace is a new request method in HTTP/1.1. The intended use of
+ trace requests is for testing. The body of the trace response is
+ the request message that the responding Web server or proxy
+ received.</p>
+ </section>
+ </section>
+</chapter>
+
+
diff --git a/lib/inets/doc/src/httpd.xml b/lib/inets/doc/src/httpd.xml
new file mode 100644
index 0000000000..60afcc6cfe
--- /dev/null
+++ b/lib/inets/doc/src/httpd.xml
@@ -0,0 +1,1089 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>httpd</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>httpd.sgml</file>
+ </header>
+ <module>httpd</module>
+ <modulesummary>An implementation of an HTTP
+ 1.1 compliant Web server, as defined in RFC 2616.
+ </modulesummary>
+ <description>
+ <p>Documents the HTTP server start options, some administrative
+ functions and also specifies the Erlang Web server callback
+ API</p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in
+ this module:</p>
+ <p><c>boolean() = true | false </c></p>
+ <p><c>string() = list of ASCII characters</c></p>
+ <p><c>path() = string() - representing a file or directory path.</c></p>
+ <p><c> ip_address() = {N1,N2,N3,N4} % IPv4
+ | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p>
+ <p><c>hostname() = string() - representing a host ex "foo.bar.com"</c></p>
+ <p><c>property() = atom()</c></p>
+
+ </section>
+
+ <section>
+ <title>ERLANG HTTP SERVER SERVICE START/STOP </title>
+ <p>A web server can be configured to start when starting the inets
+ application or started dynamically in runtime by calling the
+ Inets application API <c>inets:start(httpd, ServiceConfig)</c>, or
+ <c>inets:start(httpd, ServiceConfig, How)</c>,
+ see <seealso marker="inets">inets(3)</seealso> Below follows a
+ description of the available configuration options, also called
+ properties.</p>
+
+ <marker id="file_prop"></marker>
+ <p><em>File properties</em></p>
+
+ <p>When the web server is started
+ at application start time the properties should be fetched from a
+ configuration file that could consist of a regular erlang property
+ list, e.i. <c>[{Option, Value}] </c> where <c> Option = property()
+ </c> and <c>Value = term()</c>, followed by a full stop, or for
+ backwards compatibility an Apache like configuration file. If the
+ web server is started dynamically at runtime you may still specify
+ a file but you could also just specify the complete property
+ list.</p>
+
+ <taglist>
+ <tag>{proplist_file, path()}</tag>
+ <item>
+ If this property is defined inets will expect to find
+ all other properties defined in this file. Note that the
+ file must include all properties listed under mandatory
+ properties. </item>
+ <tag>{file, path()}</tag>
+
+ <item> If this property is defined
+ inets will expect to find all other properties defined in this
+ file, that uses Apache like syntax. Note that the file must
+ include all properties listed under mandatory properties. The
+ Apache like syntax is the property, written as one word where
+ each new word begins with a capital, followed by a white-space
+ followed by the value followed by a new line. Ex:
+
+ <code>
+ {server_root, "/urs/local/www"} -> ServerRoot /usr/local/www
+ </code>
+
+ <p>With a few exceptions, that are documented
+ for each property that behaves differently,
+ and the special case {directory, {path(), PropertyList}} and
+ {security_directory, {Dir, PropertyList}} that are represented
+ as:</p>
+ <pre>
+ <![CDATA[
+ <Directory Dir>
+ <Properties handled as described above>
+ </Directory>
+ ]]>
+ </pre>
+ </item>
+ </taglist>
+ <note>
+ <p>The properties proplist_file and file are mutually exclusive.</p>
+ </note>
+
+ <marker id="mand_prop"></marker>
+ <p><em>Mandatory properties</em></p>
+ <taglist>
+ <tag>{port, integer()} </tag>
+ <item>
+ The port that the HTTP server shall listen on.
+ If zero is specified as port, an arbitrary available port
+ will be picked and you can use the httpd:info/2 function to find
+ out which port was picked. </item>
+ <tag>{server_name, string()} </tag>
+ <item>
+ The name of your server, normally a fully qualified domain
+ name.
+ </item>
+ <tag>{server_root, path()} </tag>
+ <item>
+ Defines the servers home directory where log files etc can
+ be stored. Relative paths specified in other properties refer
+ to this directory.</item>
+ <tag>{document_root, path()}</tag>
+ <item>
+ Defines the top directory for the documents that
+ are available on the HTTP server.</item>
+ </taglist>
+
+ <marker id="comm_prop"></marker>
+ <p><em>Communication properties</em> </p>
+ <taglist>
+ <tag>{bind_address, ip_address() | hostname() | any} </tag>
+ <item>
+ Defaults to <c>any</c>. Note that <c>any</c> is denoted <em>*</em>
+ in the apache like configuration file.
+ </item>
+
+ <tag>{socket_type, ip_comm | ssl}</tag>
+ <item>
+ <p>Defaults to <c>ip_comm</c>. </p>
+ </item>
+
+ <tag>{ipfamily, inet | inet6 | inet6fb4}</tag>
+ <item>
+ <p>Defaults to <c>inet6fb4. </c> </p>
+ <p>Note that this option is only used when the option
+ <c>socket_type</c> has the value <c>ip_comm</c>. </p>
+ </item>
+
+ </taglist>
+
+ <p><em>Erlang Web server API modules</em> </p>
+ <taglist>
+ <tag>{modules, [atom()]} </tag>
+ <item>
+ Defines which modules the HTTP server will use to handle
+ requests. Defaults to: <c>[mod_alias, mod_auth, mod_esi,
+ mod_actions, mod_cgi, mod_dir, mod_get, mod_head, mod_log,
+ mod_disk_log] </c>
+ Note that some mod-modules are dependent on
+ others, so the order can not be entirely arbitrary. See the
+ <seealso marker="http_server"> Inets Web server Modules in the
+ Users guide</seealso> for more information.
+ </item>
+ </taglist>
+
+ <marker id="limit_prop"></marker>
+ <p><em>Limit properties</em> </p>
+ <taglist>
+ <tag>{disable_chunked_transfer_encoding_send, boolean()}</tag>
+ <item>
+ This property allows you to disable chunked
+ transfer-encoding when sending a response to a HTTP/1.1
+ client, by default this is false.</item>
+
+ <tag>{keep_alive, boolean()}</tag>
+ <item>
+ Instructs the server whether or not to use persistent
+ connections when the client claims to be HTTP/1.1
+ compliant, default is true.</item>
+
+ <tag>{keep_alive_timeout, integer()}</tag>
+ <item>
+ The number of seconds the server will wait for a
+ subsequent request from the client before closing the
+ connection. Default is 150.</item>
+
+ <tag>{max_body_size, integer()}</tag>
+ <item>
+ Limits the size of the message body of HTTP request.
+ By the default there is no limit.</item>
+
+ <tag>{max_clients, integer()}</tag>
+ <item>
+ Limits the number of simultaneous requests that can be
+ supported. Defaults to 150. </item>
+
+ <tag>{max_header_size, integer()}</tag>
+ <item>
+ Limits the size of the message header of HTTP request.
+ Defaults to 10240.
+ </item>
+
+ <tag>{max_uri, integer()}</tag>
+ <item>
+ Limits the size of the HTTP request URI. By
+ default there is no limit.</item>
+
+ <tag>{max_keep_alive_requests, integer()}</tag>
+ <item> The number of request that a client can do on one
+ connection. When the server has responded to the number of
+ requests defined by max_keep_alive_requests the server close the
+ connection. The server will close it even if there are queued
+ request. Defaults to no limit.</item>
+ </taglist>
+
+ <marker id="admin_prop"></marker>
+ <p><em>Administrative properties</em></p>
+ <taglist>
+ <tag>{mime_types, [{MimeType, Extension}] | path()}</tag>
+ <item>
+ <p>Where MimeType = string() and Extension = string().
+ Files delivered to the client are MIME typed according to RFC
+ 1590. File suffixes are mapped to MIME types before file delivery.
+ The mapping between file suffixes and MIME types can be specified
+ as an Apache like file as well as directly in the property list. Such
+ a file may look like:</p>
+ <pre>
+ \011 # MIME type\011\011\011Extension
+ \011 text/html\011\011\011html htm
+ \011 text/plain\011\011\011asc txt
+ </pre>
+
+ <p>Defaults to [{"html","text/html"},{"htm","text/html"}]</p>
+ </item>
+
+ <tag>{mime_type, string()}</tag>
+
+ <item>
+ When the server is asked to provide a document type which
+ cannot be determined by the MIME Type Settings, the server will
+ use this default type. </item>
+
+ <tag>{server_admin, string()}</tag>
+ <item>
+ ServerAdmin defines the email-address of the server
+ administrator, to be included in any error messages returned by
+ the server.</item>
+
+ <tag>{log_format, common | combined}</tag>
+ <item>
+ <p>Defines if access logs should be written according to the common
+ log format or to the extended common log format.
+ The <c>common</c> format is one line that looks like this:
+ <c>remotehost rfc931 authuser [date] "request" status bytes</c></p>
+
+ <pre>remotehost
+ Remote
+rfc931
+ The client's remote username (RFC 931).
+authuser
+ The username with which the user authenticated himself.
+[date]
+ Date and time of the request (RFC 1123).
+"request"
+ The request line exactly as it came from the client(RFC 1945).
+status
+ The HTTP status code returned to the client (RFC 1945).
+bytes
+ The content-length of the document transferred.
+ </pre>
+
+ <p>The <c>combined</c> format is on line that look like this:
+ <c>remotehost rfc931 authuser [date] "request" status bytes "referer" "user_agent" </c></p>
+
+ <pre>"referer"
+ The url the client was on before
+ requesting your url. (If it could not be determined a minus
+ sign will be placed in this field)
+"user_agent"
+ The software the client claims to be using. (If it
+ could not be determined a minus sign will be placed in
+ this field)
+ </pre>
+
+ <p>This affects the access logs written by mod_log and mod_disk_log.
+ </p>
+
+ </item>
+
+ <tag>{error_log_format, pretty | compact}</tag>
+ <item>
+ <p>Defaults to pretty. If the error log is meant to be read
+ directly by a human <c>pretty</c> will be the best
+ option. <c>pretty</c> has the format corresponding to:
+ </p>
+
+ <code>io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).
+ </code>
+
+ <p><c>compact</c> has the format corresponding to:</p>
+
+ <code>io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).
+ </code>
+
+ <p>This affects the error logs written by mod_log and mod_disk_log.
+ </p>
+ </item>
+
+ </taglist>
+
+ <marker id="ssl_prop"></marker>
+ <p><em>ssl properties</em></p>
+ <taglist>
+ <tag>{ssl_ca_certificate_file, path()}</tag>
+ <item>
+ Used as cacertfile option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_certificate_file, path()}</tag>
+ <item>
+ Used as certfile option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_ciphers, list()}</tag>
+ <item>
+ Used as ciphers option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_verify_client, integer()}</tag>
+ <item>
+ Used as verify option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_verify_depth, integer()}</tag>
+ <item>
+ Used as depth option in ssl:listen/2 see
+ <seealso marker="ssl:ssl">ssl(3)</seealso> </item>
+
+ <tag>{ssl_password_callback_function, atom()}</tag>
+ <item>
+ Used together with ssl_password_callback_module
+ to retrieve a value to use as password option to ssl:listen/2
+ see <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </item>
+
+ <tag>{ssl_password_callback_arguments, list()}</tag>
+ <item>
+ Used together with ssl_password_callback_function to supply a
+ list of arguments to the callback function. If not specified
+ the callback function will be assumed to have arity 0. </item>
+
+ <tag>{ssl_password_callback_module, atom()}</tag>
+ <item>
+ Used together with ssl_password_callback_function
+ to retrieve a value to use as password option to ssl:listen/2
+ see <seealso marker="ssl:ssl">ssl(3)</seealso></item>
+
+ </taglist>
+
+ <marker id="alias_prop"></marker>
+ <p><em>URL aliasing properties - requires mod_alias</em></p>
+ <taglist>
+ <tag>{alias, {Alias, RealName}}</tag>
+
+ <item> Where Alias = string() and RealName = string().
+ The Alias property allows documents to be stored in the local file
+ system instead of the document_root location. URLs with a path that
+ begins with url-path is mapped to local files that begins with
+ directory-filename, for example:
+
+ <code>{alias, {"/image", "/ftp/pub/image"}</code>
+
+ and an access to http://your.server.org/image/foo.gif would refer to
+ the file /ftp/pub/image/foo.gif.</item>
+
+ <tag>{directory_index, [string()]}</tag>
+
+ <item>
+ DirectoryIndex specifies a list of resources to look for
+ if a client requests a directory using a / at the end of the
+ directory name. file depicts the name of a file in the
+ directory. Several files may be given, in which case the server
+ will return the first it finds, for example:
+
+ <code>{directory_index, ["index.hml", "welcome.html"]}</code>
+
+ and access to http://your.server.org/docs/ would return
+ http://your.server.org/docs/index.html or
+ http://your.server.org/docs/welcome.html if index.html do not
+ exist.
+ </item>
+ </taglist>
+
+ <marker id="cgi_prop"></marker>
+ <p><em>CGI properties - requires mod_cgi</em></p>
+ <taglist>
+ <tag>{script_alias, {Alias, RealName}}</tag>
+ <item> Where Alias = string() and RealName = string().
+ Has the same behavior as the Alias property, except that
+ it also marks the target directory as containing CGI
+ scripts. URLs with a path beginning with url-path are mapped to
+ scripts beginning with directory-filename, for example:
+
+ <code> {script_alias, {"/cgi-bin/", "/web/cgi-bin/"}</code>
+
+ and an access to http://your.server.org/cgi-bin/foo would cause
+ the server to run the script /web/cgi-bin/foo.
+ </item>
+
+ <tag>{script_nocache, boolean()}</tag>
+
+ <item>
+ If ScriptNoCache is set to true the HTTP server will by
+ default add the header fields necessary to prevent proxies from
+ caching the page. Generally this is something you want. Defaults
+ to false.</item>
+
+ <tag>{script_timeout, integer()}</tag>
+
+ <item>
+ The time in seconds the web server will wait between each
+ chunk of data from the script. If the CGI-script not delivers
+ any data before the timeout the connection to the client will be
+ closed. Defaults to 15. </item>
+
+ <tag>{action, {MimeType, CgiScript}} - requires mod_action</tag>
+
+ <item>Where MimeType = string() and CgiScript = string().
+ Action adds an action, which will activate a cgi-script
+ whenever a file of a certain mime-type is requested. It
+ propagates the URL and file path of the requested document using
+ the standard CGI PATH_INFO and PATH_TRANSLATED environment
+ variables.
+ <code> {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}
+ </code>
+ </item>
+
+ <tag>{script, {Method, CgiScript}} - requires mod_action</tag>
+
+ <item>Where Method = string() and CgiScript = string().
+ Script adds an action, which will activate a cgi-script
+ whenever a file is requested using a certain HTTP method. The
+ method is either GET or POST as defined in RFC 1945. It
+ propagates the URL and file path of the requested document using
+ the standard CGI PATH_INFO and PATH_TRANSLATED environment
+ variables.
+
+ <code> {script, {"PUT", "/cgi-bin/put"}
+ </code>
+
+ </item>
+ </taglist>
+
+ <marker id="esi_prop"></marker>
+ <p><em>ESI properties - requires mod_esi</em></p>
+ <taglist>
+ <tag>{erl_script_alias, {URLPath, [AllowedModule]}}</tag>
+
+ <item>Where URLPath = string() and AllowedModule = atom().
+ erl_script_alias marks all URLs matching url-path as erl
+ scheme scripts. A matching URL is mapped into a specific module
+ and function. For example:
+
+ <code>{erl_script_alias, {"/cgi-bin/example" [httpd_example]}
+ </code>
+
+ and a request to
+ http://your.server.org/cgi-bin/example/httpd_example:yahoo
+ would refer to httpd_example:yahoo/2 and
+ http://your.server.org/cgi-bin/example/other:yahoo would
+ not be allowed to execute.
+ </item>
+
+ <tag>{erl_script_nocache, boolean()}</tag>
+
+ <item>
+ If erl_script_nocache is set to true the server will add
+ http header fields that prevents proxies from caching the
+ page. This is generally a good idea for dynamic content, since
+ the content often vary between each request. Defaults to false.
+ </item>
+
+ <tag>{erl_script_timeout, integer()}</tag>
+
+ <item>
+ If erl_script_timeout sets the time in seconds the server will
+ wait between each chunk of data to be delivered through
+ mod_esi:deliver/2. Defaults to 15. This is only relevant
+ for scripts that uses the erl scheme.
+ </item>
+
+ <tag>{eval_script_alias, {URLPath, [AllowedModule]}}</tag>
+
+ <item>Where URLPath = string() and AllowedModule = atom().
+ Same as erl_script_alias but for scripts
+ using the eval scheme. Note that this is only supported
+ for backwards compatibility. The eval scheme is deprecated.</item>
+ </taglist>
+
+ <marker id="log_prop"></marker>
+ <p><em>Log properties - requires mod_log</em></p>
+ <taglist>
+ <tag>{error_log, path()}</tag>
+
+ <item>
+ Defines the filename of the error log file to be used to log
+ server errors. If the filename does not begin with a slash (/)
+ it is assumed to be relative to the server_root</item>
+
+ <tag>{security_log, path()}</tag>
+
+ <item>
+ Defines the filename of the access log file to be used to
+ log security events. If the filename does not begin with a slash
+ (/) it is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{transfer_log, path()}</tag>
+
+ <item>
+ Defines the filename of the access log file to be used to
+ log incoming requests. If the filename does not begin with a
+ slash (/) it is assumed to be relative to the server_root.
+ </item>
+ </taglist>
+
+ <marker id="dlog_prop"></marker>
+ <p><em>Disk Log properties - requires mod_disk_log</em></p>
+ <taglist>
+ <tag>{disk_log_format, internal | external}</tag>
+
+ <item>
+ Defines the file-format of the log files see disk_log for
+ more information. If the internal file-format is used, the
+ logfile will be repaired after a crash. When a log file is
+ repaired data might get lost. When the external file-format is
+ used httpd will not start if the log file is broken. Defaults to
+ external.
+ </item>
+
+ <tag>{error_disk_log, internal | external}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) error log file
+ to be used to log server errors. If the filename does not begin
+ with a slash (/) it is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{error_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the (disk_log(3)) error log
+ file. The disk_log(3) error log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused. </item>
+
+ <tag>{security_disk_log, path()}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) access log file
+ which logs incoming security events i.e authenticated
+ requests. If the filename does not begin with a slash (/) it
+ is assumed to be relative to the server_root.
+ </item>
+
+ <tag>{security_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the disk_log(3) access log
+ file. The disk_log(3) access log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused.</item>
+
+ <tag>{transfer_disk_log, path()}</tag>
+
+ <item>
+ Defines the filename of the (disk_log(3)) access log file
+ which logs incoming requests. If the filename does not begin
+ with a slash (/) it is assumed to be relative to the
+ server_root.
+ </item>
+
+ <tag>{transfer_disk_log_size, {MaxBytes, MaxFiles}}</tag>
+
+ <item>Where MaxBytes = integer() and MaxFiles = integer().
+ Defines the properties of the disk_log(3) access log
+ file. The disk_log(3) access log file is of type wrap log and
+ max-bytes will be written to each file and max-files will be
+ used before the first file is truncated and reused.</item>
+ </taglist>
+
+ <marker id="auth_prop"></marker>
+ <p><em>Authentication properties - requires mod_auth</em></p>
+
+ <p><em>{directory, {path(), [{property(), term()}]}}</em></p>
+
+ <marker id="dir_prop"></marker>
+ <p>Here follows the valid properties for directories </p>
+
+ <taglist>
+ <tag>{allow_from, all | [RegxpHostString]}</tag>
+
+ <item>
+ Defines a set of hosts which should be granted access to a
+ given directory.
+
+ For example:
+
+ <code>{allow_from, ["123.34.56.11", "150.100.23"] </code>
+
+ The host 123.34.56.11 and all machines on the 150.100.23
+ subnet are allowed access.</item>
+
+ <tag>{deny_from, all | [RegxpHostString]}</tag>
+
+ <item>
+ Defines a set of hosts
+ which should be denied access to a given directory.
+ For example:
+
+ <code>{deny_from, ["123.34.56.11", "150.100.23"] </code>
+
+ The host 123.34.56.11 and all machines on the 150.100.23
+ subnet are not allowed access.</item>
+
+ <tag>{auth_type, plain | dets | mnesia}</tag>
+
+ <item>
+ Sets the type of authentication database that is used for the
+ directory.The key difference between the different methods is
+ that dynamic data can be saved when Mnesia and Dets is used.
+ This property is called AuthDbType in the Apache like
+ configuration files.
+ </item>
+
+ <tag>{auth_user_file, path()}</tag>
+
+ <item>
+ Sets the name of a file which contains the list of users and
+ passwords for user authentication. filename can be either
+ absolute or relative to the <c>server_root</c>. If using the
+ plain storage method, this file is a plain text file, where
+ each line contains a user name followed by a colon, followed
+ by the non-encrypted password. If user names are duplicated,
+ the behavior is undefined. For example:
+
+ <code> ragnar:s7Xxv7
+ edward:wwjau8 </code>
+
+ If using the dets storage method, the user database is
+ maintained by dets and should not be edited by hand. Use the
+ API functions in mod_auth module to create / edit the user
+ database. This directive is ignored if using the mnesia
+ storage method. For security reasons, make sure that the
+ <c>auth_user_file</c> is stored outside the document tree of the Web
+ server. If it is placed in the directory which it protects,
+ clients will be able to download it.
+ </item>
+
+ <tag>{auth_group_file, path()}</tag>
+
+ <item> Sets the name of a file which contains the list of user
+ groups for user authentication. Filename can be either
+ absolute or relative to the <c>server_root</c>. If you use the plain
+ storage method, the group file is a plain text file, where
+ each line contains a group name followed by a colon, followed
+ by the member user names separated by spaces. For example:
+
+ <code>group1: bob joe ante</code>
+
+ If using the dets storage method, the group database is
+ maintained by dets and should not be edited by hand. Use the
+ API for mod_auth module to create / edit the group database.
+ This directive is ignored if using the mnesia storage method.
+ For security reasons, make sure that the <c>auth_group_file</c> is
+ stored outside the document tree of the Web server. If it is
+ placed in the directory which it protects, clients will be
+ able to download it.</item>
+
+ <tag>{auth_name, string()}</tag>
+
+ <item>
+ Sets the name of the authorization realm (auth-domain) for
+ a directory. This string informs the client about which user
+ name and password to use. </item>
+
+ <tag>{auth_access_password, string()}</tag>
+
+ <item> If set to other than "NoPassword" the password is required
+ for all API calls. If the password is set to "DummyPassword" the
+ password must be changed before any other API calls. To secure
+ the authenticating data the password must be changed after the
+ web server is started since it otherwise is written in clear
+ text in the configuration file.</item>
+
+ <tag>{require_user, [string()]}</tag>
+ <item>
+ Defines users which should be granted access to a given
+ directory using a secret password.
+ </item>
+
+ <tag>{require_group, [string()]}</tag>
+ <item>
+ Defines users which should be granted access to a given
+ directory using a secret password.
+ </item>
+
+ </taglist>
+
+ <marker id="htaccess_prop"></marker>
+ <p><em>Htaccess authentication properties - requires mod_htaccess</em></p>
+ <taglist>
+ <tag>{access_files, [path()]}</tag>
+
+ <item> Specify which filenames that are used for
+ access-files. When a request comes every directory in the path
+ to the requested asset will be searched after files with the
+ names specified by this parameter. If such a file is found the
+ file will be parsed and the restrictions specified in it will
+ be applied to the request.
+ </item>
+ </taglist>
+
+ <marker id="sec_prop"></marker>
+ <p><em>Security properties - requires mod_security </em></p>
+
+ <p><em>{security_directory, {path(), [{property(), term()}]}</em></p>
+
+ <marker id="sdir_prop"></marker>
+ <p> Here follows the valid properties for security directories</p>
+ <taglist>
+ <tag>{security_data_file, path()}</tag>
+
+ <item>
+ Name of the security data file. The filename can either
+ absolute or relative to the server_root. This file is used to
+ store persistent data for the mod_security module. </item>
+
+ <tag>{security_max_retries, integer()}</tag>
+
+ <item> Specifies the maximum number of tries to authenticate a
+ user has before the user is blocked out. If a user
+ successfully authenticates when the user has been blocked, the
+ user will receive a 403 (Forbidden) response from the
+ server. If the user makes a failed attempt while blocked the
+ server will return 401 (Unauthorized), for security
+ reasons. Defaults to 3 may also be set to infinity.</item>
+
+ <tag>{security_block_time, integer()}</tag>
+
+ <item> Specifies the number of minutes a user is blocked. After
+ this amount of time, he automatically regains access.
+ Defaults to 60</item>
+
+ <tag>{security_fail_expire_time, integer()}</tag>
+
+ <item>
+ Specifies the number of minutes a failed user authentication
+ is remembered. If a user authenticates after this amount of
+ time, his previous failed authentications are
+ forgotten. Defaults to 30</item>
+
+ <tag>{security_auth_timeout, integer()}</tag>
+
+ <item>
+ Specifies the number of seconds a successful user
+ authentication is remembered. After this time has passed, the
+ authentication will no longer be reported. Defaults to 30.
+ </item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>info(Pid) -></name>
+ <name>info(Pid, Properties) -> [{Option, Value}]</name>
+ <fsummary>Fetches information about the HTTP server</fsummary>
+ <type>
+ <v>Properties = [property()]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Fetches information about the HTTP server. When called
+ with only the pid all properties are fetched, when called
+ with a list of specific properties they are fetched.
+ Available properties are the same as the servers start options.
+ </p>
+
+ <note><p>Pid is the pid returned from inets:start/[2,3].
+ Can also be retrieved form inets:services/0, inets:services_info/0
+ see <seealso marker="inets">inets(3)</seealso>
+ </p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>info(Address, Port) -> </name>
+ <name>info(Address, Port, Properties) -> [{Option, Value}] </name>
+ <fsummary>Fetches information about the HTTP server</fsummary>
+ <type>
+ <v>Address = ip_address()</v>
+ <v>Port = integer()</v>
+ <v>Properties = [property()]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Fetches information about the HTTP server. When called with
+ only the Address and Port all properties are fetched, when
+ called with a list of specific properties they are fetched.
+ Available properties are the same as the servers start
+ options.
+ </p>
+
+ <note><p> Address has to be the ip-address and can not be
+ the hostname.
+ </p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>reload_config(Config, Mode) -> ok | {error, Reason}</name>
+ <fsummary>Reloads the HTTP server configuration without
+ restarting the server.</fsummary>
+ <type>
+ <v>Config = path() | [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ <v>Mode = non_disturbing | disturbing</v>
+ </type>
+ <desc>
+ <p>Reloads the HTTP server configuration without restarting the
+ server. Incoming requests will be answered with a temporary
+ down message during the time the it takes to reload.</p>
+
+ <note><p>Available properties are the same as the servers
+ start options, although the properties bind_address and
+ port can not be changed.</p></note>
+
+ <p>If mode is disturbing, the server is blocked forcefully and
+ all ongoing requests are terminated and the reload will
+ start immediately. If mode is non-disturbing, no new
+ connections are accepted, but the ongoing requests are
+ allowed to complete before the reload is done.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ERLANG WEB SERVER API DATA TYPES </title>
+ <code type="none">
+ ModData = #mod{}
+
+ -record(mod, {
+\011\011data = [],
+\011\011socket_type = ip_comm,
+\011\011socket,
+\011\011config_db,
+\011\011method,
+\011\011absolute_uri,
+\011\011request_uri,
+\011\011http_version,
+\011\011request_line,
+\011\011parsed_header = [],
+\011\011entity_body,
+\011\011connection
+\011 }).
+ </code>
+ <p>The fields of the <c>mod</c> record has the following meaning:
+ </p>
+ <taglist>
+ <tag><c>data</c></tag>
+ <item>Type <c>[{InteractionKey,InteractionValue}]</c> is used to
+ propagate data between modules. Depicted
+ <c>interaction_data()</c> in function type declarations.
+ </item>
+ <tag><c>socket_type</c></tag>
+ <item><c>socket_type()</c>,
+ Indicates whether it is an ip socket or a ssl socket.
+ </item>
+ <tag><c>socket</c></tag>
+ <item>The actual socket in <c>ip_comm</c> or <c>ssl</c> format
+ depending on the <c>socket_type</c>.
+ </item>
+ <tag><c>config_db</c></tag>
+ <item>The config file directives stored as key-value tuples in
+ an ETS-table. Depicted <c>config_db()</c> in function type
+ declarations.
+ </item>
+ <tag><c>method</c></tag>
+ <item>Type <c>"GET" | "POST" | "HEAD" | "TRACE"</c>, that is the
+ HTTP method.
+ </item>
+ <tag><c>absolute_uri</c></tag>
+ <item>If the request is a HTTP/1.1
+ request the URI might be in the absolute URI format. In that
+ case httpd will save the absolute URI in this field. An Example
+ of an absolute URI could
+ be<c>"http://ServerName:Part/cgi-bin/find.pl?person=jocke"</c></item>
+ <tag><c>request_uri</c></tag>
+ <item>The <c>Request-URI</c> as defined
+ in RFC 1945, for example <c>"/cgi-bin/find.pl?person=jocke"</c></item>
+ <tag><c>http_version</c></tag>
+ <item>The <c>HTTP</c> version of the
+ request, that is "HTTP/0.9", "HTTP/1.0", or "HTTP/1.1".
+ </item>
+ <tag><c>request_line</c></tag>
+ <item>The <c>Request-Line</c> as
+ defined in RFC 1945, for example <c>"GET /cgi-bin/find.pl?person=jocke HTTP/1.0"</c>.
+ </item>
+ <tag><c>parsed_header</c></tag>
+ <item>Type <c>[{HeaderKey,HeaderValue}]</c>,
+ <c>parsed_header</c> contains all HTTP header fields from the
+ HTTP-request stored in a list as key-value tuples. See RFC 2616
+ for a listing of all header fields. For example the date field
+ would be stored as: <c>{"date","Wed, 15 Oct 1997 14:35:17 GMT"}.
+ RFC 2616 defines that HTTP is a case insensitive protocol and
+ the header fields may be in lower case or upper case. Httpd will
+ ensure that all header field names are in lower case. </c>.
+ </item>
+ <tag><c>entity_body</c></tag>
+ <item>The <c>Entity-Body</c> as defined
+ in RFC 2616, for example data sent from a CGI-script using the
+ POST method.
+ </item>
+ <tag><c>connection</c></tag>
+ <item><c>true | false</c> If set to true the connection to the
+ client is a persistent connection and will not be closed when
+ the request is served.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>ERLANG WEB SERVER API CALLBACK FUNCTIONS</title>
+ </section>
+ <funcs>
+ <func>
+ <name>Module:do(ModData)-> {proceed, OldData} | {proceed, NewData} | {break, NewData} | done</name>
+ <fsummary>Called for each request to the Web server.</fsummary>
+ <type>
+ <v>OldData = list()</v>
+ <v>NewData = [{response,{StatusCode,Body}}] | [{response,{response,Head,Body}}] | [{response,{already_sent,Statuscode,Size}] </v>
+ <v>StausCode = integer()</v>
+ <v>Body = io_list() | nobody | {Fun, Arg}</v>
+ <v>Head = [HeaderOption]</v>
+ <v>HeaderOption = {Option, Value} | {code, StatusCode}</v>
+ <v>Option = accept_ranges | allow | cache_control | content_MD5 | content_encoding | content_language | content_length | content_location | content_range | content_type | date | etag | expires | last_modified | location | pragma | retry_after | server | trailer | transfer_encoding</v>
+ <v>Value = string()</v>
+ <v>Fun = fun( Arg ) -> sent| close | Body </v>
+ <v>Arg = [term()]</v>
+ </type>
+ <desc>
+ <p>When a valid request reaches httpd it calls <c>do/1</c> in
+ each module defined by the Modules configuration
+ option. The function may generate data for other modules
+ or a response that can be sent back to the client.</p>
+ <p>The field <c>data</c> in ModData is a list. This list will be
+ the list returned from the last call to
+ <c>do/1</c>.</p>
+ <p><c>Body</c> is the body of the http-response that will be
+ sent back to the client an appropriate header will be
+ appended to the message. <c>StatusCode</c> will be the
+ status code of the response see RFC2616 for the appropriate
+ values.</p>
+ <p><c>Head</c> is a key value list of HTTP header fields. The
+ server will construct a HTTP header from this data. See RFC
+ 2616 for the appropriate value for each header field. If the
+ client is a HTTP/1.0 client then the server will filter the
+ list so that only HTTP/1.0 header fields will be sent back
+ to the client.</p>
+ <p>If <c>Body</c> is returned and equal to <c>{Fun,Arg}</c>,
+ the Web server will try <c>apply/2</c> on <c>Fun</c> with
+ <c>Arg</c> as argument and expect that the fun either
+ returns a list <c>(Body)</c> that is a HTTP-repsonse or the
+ atom sent if the HTTP-response is sent back to the
+ client. If close is returned from the fun something has gone
+ wrong and the server will signal this to the client by
+ closing the connection.</p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:load(Line, AccIn)-> eof | ok | {ok, AccOut} | {ok, AccOut, {Option, Value}} | {ok, AccOut, [{Option, Value}]} | {error, Reason} </name>
+ <fsummary>Load is used to convert a line in a Apache like config
+ file to a <c>{Option, Value}</c> tuple.</fsummary>
+ <type>
+ <v>Line = string()</v>
+ <v>AccIn = [{Option, Value}]</v>
+ <v>AccOut = [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term() </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Load is used to convert a line in a Apache like
+ configuration file to a <c>{Option, Value}</c> tuple. Some
+ more complex configuration options such as <c>directory</c>
+ and <c>security_directory</c> will create an
+ accumulator.This function does only need clauses for the
+ options implemented by this particular callback module.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:store({Option, Value}, Config)-> {ok, {Option, NewValue}} | {error, Reason} </name>
+ <fsummary></fsummary>
+ <type>
+ <v>Line = string()</v>
+ <v>Option = property()</v>
+ <v>Config = [{Option, Value}]</v>
+ <v>Value = term() </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>This function is used to check the validity of the
+ configuration options before saving them in the internal
+ database. This function may also have a side effect
+ e.i. setup necessary extra resources implied by the
+ configuration option. It can also
+ resolve possible dependencies among
+ configuration options by changing the value of the option.
+ This function does only need clauses for the options
+ implemented by this particular callback module.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>Module:remove(ConfigDB) -> ok | {error, Reason} </name>
+ <fsummary>Callback function that is called when the Web server is closed.</fsummary>
+ <type>
+ <v>ConfigDB = ets_table()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>When httpd is shutdown it will try to execute
+ <c>remove/1</c> in each Erlang web server callback module. The
+ programmer may use this function to clean up resources
+ that may have been created in the store function.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ERLANG WEB SERVER API HELP FUNCTIONS</title>
+ </section>
+ <funcs>
+ <func>
+ <name>parse_query(QueryString) -> [{Key,Value}]</name>
+ <fsummary>Parse incoming data to <c>erl </c>and <c>eval </c>scripts.</fsummary>
+ <type>
+ <v>QueryString = string()</v>
+ <v>Key = string()</v>
+ <v>Value = string()</v>
+ </type>
+ <desc>
+ <marker id="parse_query"></marker>
+ <p><c>parse_query/1</c> parses incoming data to <c>erl</c> and
+ <c>eval</c> scripts (See <seealso marker="mod_esi">mod_esi(3)</seealso>) as defined in the standard
+ URL format, that is '+' becomes 'space' and decoding of
+ hexadecimal characters (<c>%xx</c>).</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>,
+ <seealso marker="ssl:ssl">ssl(3)</seealso>
+ </p>
+ </section>
+
+</erlref>
+
diff --git a/lib/inets/doc/src/httpd_conf.xml b/lib/inets/doc/src/httpd_conf.xml
new file mode 100644
index 0000000000..a1ad76a8ae
--- /dev/null
+++ b/lib/inets/doc/src/httpd_conf.xml
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>httpd_conf</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>httpd_conf.sgml</file>
+ </header>
+ <module>httpd_conf</module>
+ <modulesummary>Configuration utility functions to be used by the Erlang
+ Web server API programmer.</modulesummary>
+ <description>
+ <p>This module provides the Erlang Webserver API programmer with
+ utility functions for adding run-time configuration directives.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>check_enum(EnumString,ValidEnumStrings) -> Result</name>
+ <fsummary>Check if string is a valid enumeration.</fsummary>
+ <type>
+ <v>EnumString = string()</v>
+ <v>ValidEnumStrings = [string()]</v>
+ <v>Result = {ok,atom()} | {error,not_valid}</v>
+ </type>
+ <desc>
+ <marker id="check_enum"></marker>
+ <p><c>check_enum/2</c> checks if <c>EnumString</c> is a valid
+ enumeration of <c>ValidEnumStrings</c> in which case it is
+ returned as an atom.</p>
+ </desc>
+ </func>
+ <func>
+ <name>clean(String) -> Stripped</name>
+ <fsummary>Remove leading and/or trailing white spaces.</fsummary>
+ <type>
+ <v>String = Stripped = string()</v>
+ </type>
+ <desc>
+ <marker id="clean"></marker>
+ <p><c>clean/1</c> removes leading and/or trailing white spaces
+ from <c>String</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>custom_clean(String,Before,After) -> Stripped</name>
+ <fsummary>Remove leading and/or trailing white spaces and custom characters.</fsummary>
+ <type>
+ <v>Before = After = regexp()</v>
+ <v>String = Stripped = string()</v>
+ </type>
+ <desc>
+ <marker id="custom_clean"></marker>
+ <p><c>custom_clean/3</c> removes leading and/or trailing white
+ spaces and custom characters from <c>String</c>. <c>Before</c>
+ and <c>After</c> are regular expressions, as defined in
+ <c>regexp(3)</c>, describing the custom characters.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_directory(FilePath) -> Result</name>
+ <fsummary>Check if a file path is a directory.</fsummary>
+ <type>
+ <v>FilePath = string()</v>
+ <v>Result = {ok,Directory} | {error,Reason}</v>
+ <v>Directory = string()</v>
+ <v>Reason = string() | enoent | eaccess | enotdir | FileInfo</v>
+ <v>FileInfo = File info record</v>
+ </type>
+ <desc>
+ <marker id="is_directory"></marker>
+ <p><c>is_directory/1</c> checks if <c>FilePath</c> is a
+ directory in which case it is returned. Please read
+ <c>file(3)</c> for a description of <c>enoent</c>,
+ <c>eaccess</c> and <c>enotdir</c>. The definition of
+ the file info record can be found by including <c>file.hrl</c>
+ from the kernel application, see file(3).</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_file(FilePath) -> Result</name>
+ <fsummary>Check if a file path is a regular file.</fsummary>
+ <type>
+ <v>FilePath = string()</v>
+ <v>Result = {ok,File} | {error,Reason}</v>
+ <v>File = string()</v>
+ <v>Reason = string() | enoent | eaccess | enotdir | FileInfo</v>
+ <v>FileInfo = File info record</v>
+ </type>
+ <desc>
+ <marker id="is_file"></marker>
+ <p><c>is_file/1</c> checks if <c>FilePath</c> is a regular
+ file in which case it is returned. Read <c>file(3)</c> for a
+ description of <c>enoent</c>, <c>eaccess</c> and
+ <c>enotdir</c>. The definition of the file info record can be
+ found by including <c>file.hrl</c> from the kernel application,
+ see file(3).</p>
+ </desc>
+ </func>
+ <func>
+ <name>make_integer(String) -> Result</name>
+ <fsummary>Return an integer representation of a string.</fsummary>
+ <type>
+ <v>String = string()</v>
+ <v>Result = {ok,integer()} | {error,nomatch}</v>
+ </type>
+ <desc>
+ <marker id="make_integer"></marker>
+ <p><c>make_integer/1</c> returns an integer representation of
+ <c>String</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="see_also"></marker>
+ <title>SEE ALSO</title>
+ <p><seealso marker="httpd">httpd(3)</seealso></p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/httpd_socket.xml b/lib/inets/doc/src/httpd_socket.xml
new file mode 100644
index 0000000000..fba1a58d3a
--- /dev/null
+++ b/lib/inets/doc/src/httpd_socket.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>httpd_socket</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>httpd_socket.sgml</file>
+ </header>
+ <module>httpd_socket</module>
+ <modulesummary>Communication utility functions to be used by the Erlang
+ Web server API programmer.</modulesummary>
+ <description>
+ <p>This module provides the Erlang Web server API module programmer
+ with utility functions for generic sockets communication. The
+ appropriate communication mechanism is transparently used, that
+ is <c>ip_comm</c> or <c>ssl</c>.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>deliver(SocketType, Socket, Data) -> Result</name>
+ <fsummary>Send binary data over socket.</fsummary>
+ <type>
+ <v>SocketType = socket_type()</v>
+ <v>Socket = socket()</v>
+ <v>Data = io_list() | binary()</v>
+ <v>Result = socket_closed | void()</v>
+ </type>
+ <desc>
+ <marker id="deliver"></marker>
+ <p><c>deliver/3</c> sends the <c>Binary</c> over the
+ <c>Socket</c> using the specified <c>SocketType</c>. Socket
+ and SocketType should be the socket and the socket_type form
+ the mod record as defined in httpd.hrl</p>
+ </desc>
+ </func>
+ <func>
+ <name>peername(SocketType,Socket) -> {Port,IPAddress}</name>
+ <fsummary>Return the port and IP-address of the remote socket.</fsummary>
+ <type>
+ <v>SocketType = socket_type()</v>
+ <v>Socket = socket()</v>
+ <v>Port = integer()</v>
+ <v>IPAddress = string()</v>
+ </type>
+ <desc>
+ <marker id="peername"></marker>
+ <p><c>peername/3</c> returns the <c>Port</c> and
+ <c>IPAddress</c> of the remote <c>Socket</c>. </p>
+ </desc>
+ </func>
+ <func>
+ <name>resolve() -> HostName</name>
+ <fsummary>Return the official name of the current host.</fsummary>
+ <type>
+ <v>HostName = string()</v>
+ </type>
+ <desc>
+ <marker id="resolve"></marker>
+ <p><c>resolve/0</c> returns the official <c>HostName</c> of
+ the current host. </p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="see_also"></marker>
+ <title>SEE ALSO</title>
+ <p><seealso marker="httpd">httpd(3)</seealso></p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/httpd_util.xml b/lib/inets/doc/src/httpd_util.xml
new file mode 100644
index 0000000000..1566ee29d1
--- /dev/null
+++ b/lib/inets/doc/src/httpd_util.xml
@@ -0,0 +1,459 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>httpd_util</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>httpd_util.sgml</file>
+ </header>
+ <module>httpd_util</module>
+ <modulesummary>Miscellaneous utility functions to be used when implementing Erlang Web server API modules.</modulesummary>
+ <description>
+ <p>This module provides the Erlang Web Server API module
+ programmer with miscellaneous utility functions.</p>
+
+ <marker id="convert_request_date"></marker>
+ </description>
+
+ <funcs>
+ <func>
+ <name>convert_request_date(DateString) -> ErlDate|bad_date</name>
+ <fsummary>Convert The the date to the Erlang date format.</fsummary>
+ <type>
+ <v>DateString = string()</v>
+ <v>ErlDate = {{Year,Month,Date},{Hour,Min,Sec}}</v>
+ <v>Year = Month = Date = Hour = Min = Sec = integer()</v>
+ </type>
+ <desc>
+ <p><c>convert_request_date/1</c> converts <c>DateString</c> to
+ the Erlang date format. DateString must be in one of the three
+ date formats that is defined in the RFC 2616.</p>
+
+ <marker id="create_etag"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>create_etag(FileInfo) -> Etag</name>
+ <fsummary>Calculates the Etag for a file.</fsummary>
+ <type>
+ <v>FileInfo = file_info()</v>
+ <v>Etag = string()</v>
+ </type>
+ <desc>
+ <p><c>create_etag/1</c> calculates the Etag for a file, from it's
+ size and time for last modification. fileinfo is a record defined
+ in <c>kernel/include/file.hrl</c></p>
+
+ <marker id="decode_hex"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>decode_hex(HexValue) -> DecValue</name>
+ <fsummary>Convert a hex value into its decimal equivalent.</fsummary>
+ <type>
+ <v>HexValue = DecValue = string()</v>
+ </type>
+ <desc>
+ <p>Converts the hexadecimal value <c>HexValue</c> into it's
+ decimal equivalent (<c>DecValue</c>).</p>
+
+ <marker id="day"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>day(NthDayOfWeek) -> DayOfWeek</name>
+ <fsummary>Convert the day of the week (integer [1-7]) to an abbreviated string.</fsummary>
+ <type>
+ <v>NthDayOfWeek = 1-7</v>
+ <v>DayOfWeek = string()</v>
+ </type>
+ <desc>
+ <marker id="day"></marker>
+ <p><c>day/1</c> converts the day of the week
+ (<c>NthDayOfWeek</c>) as an integer (1-7) to an abbreviated
+ string, that is: </p>
+ <p>1 = "Mon", 2 = "Tue", ..., 7 = "Sat".</p>
+
+ <marker id="flatlength"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>flatlength(NestedList) -> Size</name>
+ <fsummary>Compute the size of a possibly nested list.</fsummary>
+ <type>
+ <v>NestedList = list()</v>
+ <v>Size = integer()</v>
+ </type>
+ <desc>
+ <marker id="flatlength"></marker>
+ <p><c>flatlength/1</c> computes the size of the possibly nested
+ list <c>NestedList</c>. Which may contain binaries.</p>
+
+ <marker id="hexlist_to_integer"></marker>
+ </desc>
+ </func>
+
+<!--
+ <func>
+ <name>header(StatusCode,PersistentConn)</name>
+ <name>header(StatusCode,Date)</name>
+ <name>header(StatusCode,MimeType,Date)</name>
+ <name>header(StatusCode,MimeType,PersistentConn,Date) -> HTTPHeader</name>
+ <fsummary>Generate a HTTP 1.1 header.</fsummary>
+ <type>
+ <v>StatusCode = integer()</v>
+ <v>Date = rfc1123_date()</v>
+ <v>MimeType = string()</v>
+ <v>PersistentConn = true | false</v>
+ </type>
+ <desc>
+ <marker id="header"></marker>
+ <p><c>header</c> returns a HTTP 1.1 header string. The
+ <c>StatusCode</c> is one of the status codes defined in RFC
+ 2616 and the <c>Date</c> string is RFC 1123
+ compliant. (See <seealso marker="#rfc1123_date">rfc1123_date/0</seealso>).
+ </p>
+ <p>Note that the two version of <c>header/n</c> that does not
+ has a <c>PersistentConn</c> argument is there only for
+ backward compatibility, and must not be used in new Erlang
+ Webserver API modules. that will support persistent
+ connections.</p>
+
+ <marker id="hexlist_to_integer"></marker>
+ </desc>
+ </func>
+-->
+
+ <func>
+ <name>hexlist_to_integer(HexString) -> Number</name>
+ <fsummary>Convert a hexadecimal string to an integer.</fsummary>
+ <type>
+ <v>Number = integer()</v>
+ <v>HexString = string()</v>
+ </type>
+ <desc>
+ <p><c>hexlist_to_integer</c> Convert the Hexadecimal value of
+ HexString to an integer.</p>
+
+ <marker id="integer_to_hexlist"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>integer_to_hexlist(Number) -> HexString</name>
+ <fsummary>Convert an integer to a hexadecimal string.</fsummary>
+ <type>
+ <v>Number = integer()</v>
+ <v>HexString = string()</v>
+ </type>
+ <desc>
+ <marker id="integer_to_hexlist"></marker>
+ <p><c>integer_to_hexlist/1</c> Returns a string that represents
+ the Number in a Hexadecimal form.</p>
+
+ <marker id="lookup"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>lookup(ETSTable,Key) -> Result</name>
+ <name>lookup(ETSTable,Key,Undefined) -> Result</name>
+ <fsummary>Extract the first value associated with a key in an ETS table.</fsummary>
+ <type>
+ <v>ETSTable = ets_table()</v>
+ <v>Key = term()</v>
+ <v>Result = term() | undefined | Undefined</v>
+ <v>Undefined = term()</v>
+ </type>
+ <desc>
+ <p><c>lookup</c> extracts <c>{Key,Value}</c> tuples from
+ <c>ETSTable</c> and returns the <c>Value</c> associated
+ with <c>Key</c>. If <c>ETSTable</c> is of type <c>bag</c>
+ only the first <c>Value</c> associated with <c>Key</c> is
+ returned. <c>lookup/2</c> returns <c>undefined</c> and
+ <c>lookup/3</c> returns <c>Undefined</c> if no <c>Value</c>
+ is found.</p>
+
+ <marker id="lookup_mime"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>lookup_mime(ConfigDB,Suffix)</name>
+ <name>lookup_mime(ConfigDB,Suffix,Undefined) -> MimeType</name>
+ <fsummary>Return the mime type associated with a specific file suffix. </fsummary>
+ <type>
+ <v>ConfigDB = ets_table()</v>
+ <v>Suffix = string()</v>
+ <v>MimeType = string() | undefined | Undefined</v>
+ <v>Undefined = term()</v>
+ </type>
+ <desc>
+ <marker id="lookup_mime"></marker>
+ <p><c>lookup_mime</c> returns the mime type associated with a
+ specific file suffix as specified in the <c>mime.types</c>
+ file (located in the <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\\\\conf\\\\mime.types">config directory</path>).</p>
+
+ <marker id="lookup_mime_default"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>lookup_mime_default(ConfigDB,Suffix)</name>
+ <name>lookup_mime_default(ConfigDB,Suffix,Undefined) -> MimeType</name>
+ <fsummary>Return the mime type associated with a specific file suffix or the value of the DefaultType.</fsummary>
+ <type>
+ <v>ConfigDB = ets_table()</v>
+ <v>Suffix = string()</v>
+ <v>MimeType = string() | undefined | Undefined</v>
+ <v>Undefined = term()</v>
+ </type>
+ <desc>
+ <marker id="lookup_mime_default"></marker>
+ <p><c>lookup_mime_default</c> returns the mime type associated
+ with a specific file suffix as specified in the
+ <c>mime.types</c> file (located in the
+ <path unix="$SERVER_ROOT/conf/mime.types" windows="%SERVER_ROOT%\\\\conf\\\\mime.types">config directory</path>).
+ If no appropriate association can be found
+ the value of DefaultType is
+ returned.</p>
+
+ <marker id="message"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>message(StatusCode,PhraseArgs,ConfigDB) -> Message</name>
+ <fsummary>Return an informative HTTP 1.1 status string in HTML.</fsummary>
+ <type>
+ <v>StatusCode = 301 | 400 | 403 | 404 | 500 | 501 | 504</v>
+ <v>PhraseArgs = term()</v>
+ <v>ConfigDB = ets_table</v>
+ <v>Message = string()</v>
+ </type>
+ <desc>
+ <marker id="message"></marker>
+ <p><c>message/3</c> returns an informative HTTP 1.1 status
+ string in HTML. Each <c>StatusCode</c> requires a specific
+ <c>PhraseArgs</c>:
+ </p>
+ <taglist>
+ <tag><c>301</c></tag>
+ <item><c>string()</c>: A URL pointing at the new document
+ position.</item>
+ <tag><c>400 | 401 | 500</c></tag>
+ <item><c>none</c> (No <c>PhraseArgs</c>)</item>
+ <tag><c>403 | 404</c></tag>
+ <item><c>string()</c>: A <c>Request-URI</c> as described in
+ RFC 2616.</item>
+ <tag><c>501</c></tag>
+ <item><c>{Method,RequestURI,HTTPVersion}</c>: The HTTP
+ <c>Method</c>, <c>Request-URI</c> and <c>HTTP-Version</c>
+ as defined in RFC 2616.</item>
+ <tag><c>504</c></tag>
+ <item><c>string()</c>: A string describing why the service
+ was unavailable.</item>
+ </taglist>
+
+ <marker id="month"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>month(NthMonth) -> Month</name>
+ <fsummary>Convert the month as an integer (1-12) to an abbreviated string.</fsummary>
+ <type>
+ <v>NthMonth = 1-12</v>
+ <v>Month = string()</v>
+ </type>
+ <desc>
+ <marker id="month"></marker>
+ <p><c>month/1</c> converts the month <c>NthMonth</c> as an
+ integer (1-12) to an abbreviated string, that is: </p>
+ <p>1 = "Jan", 2 = "Feb", ..., 12 = "Dec".</p>
+
+ <marker id="multi_lookup"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>multi_lookup(ETSTable,Key) -> Result</name>
+ <fsummary>Extract the values associated with a key in a ETS table.</fsummary>
+ <type>
+ <v>ETSTable = ets_table()</v>
+ <v>Key = term()</v>
+ <v>Result = [term()]</v>
+ </type>
+ <desc>
+ <p><c>multi_lookup</c> extracts all <c>{Key,Value}</c> tuples
+ from an <c>ETSTable</c> and returns <em>all</em><c>Values</c> associated with the <c>Key</c> in a list.</p>
+
+ <marker id="reason phrase"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>reason_phrase(StatusCode) -> Description</name>
+ <fsummary>Return the description of an HTTP 1.1 status code.</fsummary>
+ <type>
+ <v>StatusCode = 100| 200 | 201 | 202 | 204 | 205 | 206 | 300 | 301 | 302 | 303 | 304 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 410 411 | 412 | 413 | 414 415 | 416 | 417 | 500 | 501 | 502 | 503 | 504 | 505</v>
+ <v>Description = string()</v>
+ </type>
+ <desc>
+ <p><c>reason_phrase</c> returns the <c>Description</c> of an
+ HTTP 1.1 <c>StatusCode</c>, for example 200 is "OK" and 201
+ is "Created". Read RFC 2616 for further information.</p>
+
+ <marker id="rfc1123_date"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>rfc1123_date() -> RFC1123Date</name>
+ <name>rfc1123_date({{YYYY,MM,DD},{Hour,Min,Sec}}}) -> RFC1123Date</name>
+ <fsummary>Return the current date in RFC 1123 format.</fsummary>
+ <type>
+ <v>YYYY = MM = DD = Hour = Min =Sec = integer()</v>
+ <v>RFC1123Date = string()</v>
+ </type>
+ <desc>
+ <marker id="rfc1123_date"></marker>
+ <p><c>rfc1123_date/0</c> returns the current date in RFC 1123
+ format. <c>rfc_date/1</c> converts the date in the Erlang format
+ to the RFC 1123 date format.</p>
+
+ <marker id="split"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>split(String,RegExp,N) -> SplitRes</name>
+ <fsummary>Split a string in N chunks using a regular expression.</fsummary>
+ <type>
+ <v>String = RegExp = string()</v>
+ <v>SplitRes = {ok, FieldList} | {error, errordesc()}</v>
+ <v>Fieldlist = [string()]</v>
+ <v>N = integer</v>
+ </type>
+ <desc>
+ <marker id="split"></marker>
+ <p><c>split/3</c> splits the <c>String</c> in <c>N</c> chunks
+ using the <c>RegExp</c>. <c>split/3</c> is is equivalent to
+ <c>regexp:split/2</c> with one exception, that is <c>N</c>
+ defines the number of maximum number of fields in the
+ <c>FieldList</c>.</p>
+
+ <marker id="split_script_path"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>split_script_path(RequestLine) -> Splitted</name>
+ <fsummary>Split a <c>RequestLine</c>in a file reference to an executable and a<c>QueryString</c>or a <c>PathInfo</c>string.</fsummary>
+ <type>
+ <v>RequestLine = string()</v>
+ <v>Splitted = not_a_script | {Path, PathInfo, QueryString}</v>
+ <v>Path = QueryString = PathInfo = string()</v>
+ </type>
+ <desc>
+ <marker id="split_script_path"></marker>
+ <p><c>split_script_path/1</c> is equivalent to
+ <c>split_path/1</c> with one exception. If the longest
+ possible path is not a regular, accessible and executable
+ file <c>not_a_script</c> is returned.</p>
+
+ <marker id="split_path"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>split_path(RequestLine) -> {Path,QueryStringOrPathInfo}</name>
+ <fsummary>Split a <c>RequestLine</c>in a file reference and a <c>QueryString</c>or a<c>PathInfo</c>string.</fsummary>
+ <type>
+ <v>RequestLine = Path = QueryStringOrPathInfo = string()</v>
+ </type>
+ <desc>
+ <marker id="split_path"></marker>
+ <p><c>split_path/1</c> splits the <c>RequestLine</c> in a file
+ reference (<c>Path</c>) and a <c>QueryString</c> or a
+ <c>PathInfo</c> string as specified in RFC 2616. A
+ <c>QueryString</c> is isolated from the <c>Path</c> with a
+ question mark (<c>?</c>) and <c>PathInfo</c> with a slash
+ (/). In the case of a <c>QueryString</c>, everything before
+ the <c>?</c> is a <c>Path</c> and everything after a
+ <c>QueryString</c>. In the case of a <c>PathInfo</c> the
+ <c>RequestLine</c> is scanned from left-to-right on the hunt
+ for longest possible <c>Path</c> being a file or a
+ directory. Everything after the longest possible
+ <c>Path</c>, isolated with a <c>/</c>, is regarded as
+ <c>PathInfo</c>. The resulting <c>Path</c> is decoded using
+ <c>decode_hex/1</c> before delivery.</p>
+
+ <marker id="strip"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>strip(String) -> Stripped</name>
+ <fsummary>Returns String where the leading and trailing space and tabs has been removed.</fsummary>
+ <type>
+ <v>String = Stripped = string()</v>
+ </type>
+ <desc>
+ <marker id="strip"></marker>
+ <p><c>strip/1</c> removes any leading or trailing linear white
+ space from the string. Linear white space should be read as
+ horizontal tab or space.</p>
+
+ <marker id="suffix"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>suffix(FileName) -> Suffix</name>
+ <fsummary>Extract the file suffix from a given filename.</fsummary>
+ <type>
+ <v>FileName = Suffix = string()</v>
+ </type>
+ <desc>
+ <marker id="suffix"></marker>
+ <p><c>suffix/1</c> is equivalent to
+ <c>filename:extension/1</c> with one exception, that is
+ <c>Suffix</c> is returned without a leading dot (<c>.</c>). </p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="see_also"></marker>
+ <title>SEE ALSO</title>
+ <p><seealso marker="httpd">httpd(3)</seealso></p>
+ </section>
+
+</erlref>
diff --git a/lib/inets/doc/src/inets.gif b/lib/inets/doc/src/inets.gif
new file mode 100644
index 0000000000..64968ae68a
--- /dev/null
+++ b/lib/inets/doc/src/inets.gif
Binary files differ
diff --git a/lib/inets/doc/src/inets.xml b/lib/inets/doc/src/inets.xml
new file mode 100644
index 0000000000..e5fe32f32f
--- /dev/null
+++ b/lib/inets/doc/src/inets.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2007</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>inets</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>inets</module>
+ <modulesummary>The inets services API</modulesummary>
+ <description>
+ <p>This module provides the most basic API to the
+ clients and servers, that are part of the Inets application,
+ such as start and stop. </p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in
+ this module: </p>
+ <p><c> service() = ftpc | tfptd | httpc | httpd</c></p>
+ <p><c> property() = atom() </c></p>
+ </section>
+ <funcs>
+ <func>
+ <name>services() -> [{Service, Pid}]</name>
+ <fsummary>Returns a list of currently running services. </fsummary>
+ <type>
+ <v>Service = service()</v>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Returns a list of currently running services.</p>
+ <note>
+ <p>Services started as <c>stand_alone</c> will not
+ be listed.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>services_info() -> [{Service, Pid, Info}]</name>
+ <fsummary>Returns a list of currently running services where
+ each service is described by a [{Option, Value}]
+ list. </fsummary>
+ <type>
+ <v>Service = service()</v>
+ <v>Pid = pid()</v>
+ <v>Info = [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Returns a list of currently running services where each
+ service is described by a [{Option, Value}] list. The
+ information given in the list is specific for each service
+ and it is probable that each service will have its own info
+ function that gives you even more details about the
+ service.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>service_names() -> [Service] </name>
+ <fsummary>Returns a list of available service names.</fsummary>
+ <type>
+ <v>Service = service()</v>
+ </type>
+ <desc>
+ <p>Returns a list of available service names.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start() -> </name>
+ <name>start(Type) -> ok | {error, Reason}</name>
+ <fsummary>Starts the Inets application. </fsummary>
+ <type>
+ <v>Type = permanent | transient | temporary</v>
+ </type>
+ <desc>
+ <p>Starts the Inets application. Default type
+ is temporary. See also
+ <seealso marker="kernel:application">application(3)</seealso></p>
+ </desc>
+ </func>
+ <func>
+ <name>stop() -> ok </name>
+ <fsummary>Stops the inets application.</fsummary>
+ <desc>
+ <p>Stops the inets application. See also
+ <seealso marker="kernel:application">application(3)</seealso></p>
+ </desc>
+ </func>
+ <func>
+ <name>start(Service, ServiceConfig) -> {ok, Pid} | {error, Reason}</name>
+ <name>start(Service, ServiceConfig, How) -> {ok, Pid} |
+ {error, Reason}</name>
+ <fsummary>Dynamically starts an inets
+ service after the inets application has been
+ started. </fsummary>
+ <type>
+ <v>Service = service()</v>
+ <v>ServiceConfig = [{Option, Value}]</v>
+ <v>Option = property()</v>
+ <v>Value = term()</v>
+ <v>How = inets | stand_alone - default is inets</v>
+ </type>
+ <desc>
+ <p>Dynamically starts an inets service after the inets
+ application has been started.\011</p>
+ <note>
+ <p>Dynamically started services will not be handled by
+ application takeover and failover behavior when inets is
+ run as a distributed application. Nor will they be
+ automatically restarted when the inets application is
+ restarted, but as long as the inets application is up and
+ running they will be supervised and may be soft code
+ upgraded. Services started as <c>stand_alone</c>,
+ e.i. the service is not started as part of the inets
+ application, will lose all OTP application benefits such
+ as soft upgrade. The "stand_alone-service" will be linked to
+ the process that started it. In most cases some of the
+ supervision functionality will still be in place and in
+ some sense the calling process has now become the top
+ supervisor.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>stop(Service, Reference) -> ok | {error, Reason} </name>
+ <fsummary>Stops a started service of the inets application or takes
+ down a "stand_alone-service" gracefully.</fsummary>
+ <type>
+ <v>Service = service() | stand_alone</v>
+ <v>Reference = pid() | term() - service specified reference</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Stops a started service of the inets application or takes
+ down a "stand_alone-service" gracefully. When the
+ <c>stand_alone</c> option is used in start,
+ only the pid is a valid argument to stop.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="ftp">ftp(3)</seealso>,
+ <seealso marker="http">http(3)</seealso>,
+ <seealso marker="httpd">httpd(3)</seealso>,
+ <seealso marker="tftp">tftp(3)</seealso></p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/inets_services.xml b/lib/inets/doc/src/inets_services.xml
new file mode 100644
index 0000000000..c274d67f19
--- /dev/null
+++ b/lib/inets/doc/src/inets_services.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Introduction</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2004-09-28</date>
+ <rev>A</rev>
+ <file>inets_services.xml</file>
+ </header>
+
+ <section>
+ <title>Purpose</title>
+ <p>Inets is a container for Internet clients and
+ servers. Currently, an <term id="HTTP"></term>client and server, a
+ TFPT client and server, and a FTP client has been incorporated
+ into Inets. The HTTP server and client is HTTP 1.1 compliant as
+ defined in <term id="RFC"></term>2616.</p>
+ </section>
+
+ <section>
+ <title>Prerequisites</title>
+ <p>It is assumed that the reader is familiar with the Erlang
+ programming language, concepts of OTP and has a basic
+ understanding of the HTTP, TFTP and FTP protocols.</p>
+ </section>
+
+ <section>
+ <title>The Service Concept</title>
+ <p>Each client and server in inets is viewed as service. Services
+ may be configured to be started at application startup or
+ started dynamically in runtime. If you want to run inets as an
+ distributed application that should handle application failover
+ and takeover, services should be configured to be started at
+ application startup. When starting the inets application
+ the inets top supervisor will start a number of subsupervisors
+ and worker processes for handling the different services
+ provided. When starting services dynamically new children will
+ be added to the supervision tree, unless the service is started
+ with the stand alone option, in which case the service is linked
+ to the calling process and all OTP application features such as
+ soft upgrade are lost.</p>
+ <p>Services that should be configured for startup at application
+ startup time should be put into the erlang node configuration file
+ on the form: </p>
+ <pre>
+ [{inets, [{services, ListofConfiguredServices}]}].
+ </pre>
+ <p>For details of exactly what to put in the list of configured
+ services see the documentation for the services that should be
+ configured.</p>
+ </section>
+</chapter>
+
+
diff --git a/lib/inets/doc/src/make.dep b/lib/inets/doc/src/make.dep
new file mode 100644
index 0000000000..d96c6dc5b8
--- /dev/null
+++ b/lib/inets/doc/src/make.dep
@@ -0,0 +1,27 @@
+# ----------------------------------------------------
+# >>>> Do not edit this file <<<<
+# This file was automaticly generated by
+# /home/otp/bin/docdepend
+# ----------------------------------------------------
+
+
+# ----------------------------------------------------
+# TeX files that the DVI file depend on
+# ----------------------------------------------------
+
+book.dvi: book.tex ftp.tex ftp_client.tex http.tex http_client.tex \
+ http_server.tex httpd.tex httpd_conf.tex httpd_socket.tex \
+ httpd_util.tex inets.tex inets_services.tex \
+ mod_alias.tex mod_auth.tex mod_esi.tex mod_security.tex \
+ part.tex ref_man.tex tftp.tex
+
+# ----------------------------------------------------
+# Source inlined when transforming from source to LaTeX
+# ----------------------------------------------------
+
+book.tex: ref_man.xml
+
+ftp.tex: ../../../../system/doc/definitions/term.defs
+
+inets_services.tex: ../../../../system/doc/definitions/term.defs
+
diff --git a/lib/inets/doc/src/marting_tankar.sdw b/lib/inets/doc/src/marting_tankar.sdw
new file mode 100644
index 0000000000..90e1d2130d
--- /dev/null
+++ b/lib/inets/doc/src/marting_tankar.sdw
Binary files differ
diff --git a/lib/inets/doc/src/min_head.gif b/lib/inets/doc/src/min_head.gif
new file mode 100644
index 0000000000..67948a6378
--- /dev/null
+++ b/lib/inets/doc/src/min_head.gif
Binary files differ
diff --git a/lib/inets/doc/src/mod_alias.xml b/lib/inets/doc/src/mod_alias.xml
new file mode 100644
index 0000000000..c783b99b23
--- /dev/null
+++ b/lib/inets/doc/src/mod_alias.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>mod_alias</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>mod_alias.sgml</file>
+ </header>
+ <module>mod_alias</module>
+ <modulesummary>URL aliasing.</modulesummary>
+ <description>
+ <p>Erlang Webserver Server internal API for handling of things
+ such as interaction data exported by the mod_alias module.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>default_index(ConfigDB, Path) -> NewPath</name>
+ <fsummary>Return a new path with the default resource or file appended.</fsummary>
+ <type>
+ <v>ConfigDB = config_db()</v>
+ <v>Path = NewPath = string()</v>
+ </type>
+ <desc>
+ <marker id="default_index"></marker>
+ <p>If <c>Path</c> is a directory, <c>default_index/2</c>, it starts
+ searching for resources or files that are specified in the config
+ directive DirectoryIndex.
+ If an appropriate resource or file is found, it is appended to
+ the end of <c>Path</c> and then returned. <c>Path</c> is
+ returned unaltered, if no appropriate
+ file is found, or if <c>Path</c> is not a directory.
+ <c>config_db()</c> is the server config file in ETS table format
+ as described in
+ <seealso marker="http_server">Inets Users Guide.</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>path(PathData, ConfigDB, RequestURI) -> Path</name>
+ <fsummary>Return the actual file path to a URL.</fsummary>
+ <type>
+ <v>PathData = interaction_data()</v>
+ <v>ConfigDB = config_db()</v>
+ <v>RequestURI = Path = string()</v>
+ </type>
+ <desc>
+ <marker id="path"></marker>
+ <p><c>path/3</c> returns the actual file <c>Path</c> in the
+ <c>RequestURI</c> (See RFC 1945). If the interaction data
+ <c>{real_name,{Path,AfterPath}}</c> has been exported by
+ mod_alias;
+ <c>Path</c> is returned. If no interaction data has been
+ exported, ServerRoot is used to
+ generate a file <c>Path</c>. <c>config_db()</c> and
+ <c>interaction_data()</c> are as defined in <seealso marker="http_server">Inets Users Guide</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>real_name(ConfigDB, RequestURI, Aliases) -> Ret</name>
+ <fsummary>Expand a request uri using Alias config directives.</fsummary>
+ <type>
+ <v>ConfigDB = config_db()</v>
+ <v>RequestURI = string()</v>
+ <v>Aliases = [{FakeName,RealName}]</v>
+ <v>Ret = {ShortPath,Path,AfterPath}</v>
+ <v>ShortPath = Path = AfterPath = string()</v>
+ </type>
+ <desc>
+ <marker id="real_name"></marker>
+ <p><c>real_name/3</c> traverses <c>Aliases</c>, typically
+ extracted from <c>ConfigDB</c>, and matches each
+ <c>FakeName</c> with <c>RequestURI</c>. If a match is found
+ <c>FakeName</c> is replaced with <c>RealName</c> in the
+ match. The resulting path is split into two parts, that
+ is <c>ShortPath</c> and <c>AfterPath</c> as defined in <seealso marker="httpd_util#split_path">httpd_util:split_path/1</seealso>.
+ <c>Path</c> is generated from <c>ShortPath</c>, that is
+ the result from <seealso marker="#default_index">default_index/2</seealso> with
+ <c>ShortPath</c> as an argument.
+ <c>config_db()</c> is the server config file in ETS table
+ format as described in <seealso marker="http_server">Inets User Guide.</seealso>. </p>
+ </desc>
+ </func>
+ <func>
+ <name>real_script_name(ConfigDB,RequestURI,ScriptAliases) -> Ret</name>
+ <fsummary>Expand a request uri using ScriptAlias config directives.</fsummary>
+ <type>
+ <v>ConfigDB = config_db()</v>
+ <v>RequestURI = string()</v>
+ <v>ScriptAliases = [{FakeName,RealName}]</v>
+ <v>Ret = {ShortPath,AfterPath} | not_a_script</v>
+ <v>ShortPath = AfterPath = string()</v>
+ </type>
+ <desc>
+ <marker id="real_script_name"></marker>
+ <p><c>real_name/3</c> traverses <c>ScriptAliases</c>,
+ typically extracted from <c>ConfigDB</c>, and matches each
+ <c>FakeName</c> with <c>RequestURI</c>. If a match is found
+ <c>FakeName</c> is replaced with <c>RealName</c> in the
+ match. If the resulting match is not an executable script
+ <c>not_a_script</c> is returned. If it is a script the
+ resulting script path is in two parts, that is
+ <c>ShortPath</c> and <c>AfterPath</c> as defined in <seealso marker="httpd_util#split_script_path">httpd_util:split_script_path/1</seealso>.
+ <c>config_db()</c> is the server config file in ETS table
+ format as described in <seealso marker="http_server">Inets Users Guide.</seealso>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/mod_auth.xml b/lib/inets/doc/src/mod_auth.xml
new file mode 100644
index 0000000000..f3628c8297
--- /dev/null
+++ b/lib/inets/doc/src/mod_auth.xml
@@ -0,0 +1,287 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>mod_auth</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.3</rev>
+ <file>mod_auth.sgml</file>
+ </header>
+ <module>mod_auth</module>
+ <modulesummary>User authentication using text files, dets or mnesia database.</modulesummary>
+ <description>
+ <p>This module provides for basic user authentication using
+ textual files, dets databases as well as mnesia databases. </p>
+ </description>
+ <funcs>
+ <func>
+ <name>add_user(UserName, Options) -> true| {error, Reason}</name>
+ <name>add_user(UserName, Password, UserData, Port, Dir) -> true | {error, Reason}</name>
+ <name>add_user(UserName, Password, UserData, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Add a user to the user database.</fsummary>
+ <type>
+ <v>UserName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {password,Password} | {userData,UserData} | {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Password = string()</v>
+ <v>UserData = term()</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>AuthPassword =string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="user_api"></marker>
+ <marker id="add_user"></marker>
+ <p><c>add_user/2, add_user/5</c> and <c>add_user/6</c> adds a user to the user
+ database. If the operation is successful, this function returns
+ <c>true</c>. If an error occurs, <c>{error,Reason}</c> is returned. When <c>add_user/2</c>
+ is called the Password, UserData Port and Dir options is mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_user(UserName,Options) -> true | {error, Reason}</name>
+ <name>delete_user(UserName, Port, Dir) -> true | {error, Reason}</name>
+ <name>delete_user(UserName, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Delete a user from the user database.</fsummary>
+ <type>
+ <v>UserName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="delete_user"></marker>
+ <p><c>delete_user/2, delete_user/3</c> and <c>delete_user/4</c>
+ deletes a user
+ from the user database. If the operation is succesfull, this
+ function returns <c>true</c>. If an error occurs,
+ <c>{error,Reason}</c> is returned. When <c>delete_user/2</c> is
+ called the Port and Dir options are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_user(UserName,Options) -> {ok, #httpd_user} |{error, Reason}</name>
+ <name>get_user(UserName, Port, Dir) -> {ok, #httpd_user} | {error, Reason}</name>
+ <name>get_user(UserName, Address, Port, Dir) -> {ok, #httpd_user} | {error, Reason}</name>
+ <fsummary>Returns a user from the user database.</fsummary>
+ <type>
+ <v>UserName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="get_user"></marker>
+ <p><c>get_user/2, get_user/3</c> and <c>get_user/4</c> returns a
+ <c>httpd_user</c> record containing the userdata for a
+ specific user. If the user cannot be found, <c>{error, Reason}</c>
+ is returned. When <c>get_user/2</c> is called the Port and Dir
+ options are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_users(Options) -> {ok, Users} | {error, Reason} &lt;name>list_users(Port, Dir) -> {ok, Users} | {error, Reason}</name>
+ <name>list_users(Address, Port, Dir) -> {ok, Users} | {error, Reason}</name>
+ <fsummary>List users in the user database.</fsummary>
+ <type>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Users = list()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = atom()</v>
+ </type>
+ <desc>
+ <marker id="list_users"></marker>
+ <p><c>list_users/1, list_users/2</c> and <c>list_users/3</c> returns a list
+ of users in the user database for a specific <c>Port/Dir</c>.
+ When <c>list_users/1</c> is called the Port and Dir
+ options are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>add_group_member(GroupName, UserName, Options) -> true | {error, Reason}</name>
+ <name>add_group_member(GroupName, UserName, Port, Dir) -> true | {error, Reason}</name>
+ <name>add_group_member(GroupName, UserName, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Add a user to a group.</fsummary>
+ <type>
+ <v>GroupName = string()</v>
+ <v>UserName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="add_group_member"></marker>
+ <p><c>add_group_member/3, add_group_member/4</c> and <c>add_group_member/5</c>
+ adds a user to a group. If the group does not exist, it
+ is created and the user is added to the group. Upon successful
+ operation, this function returns <c>true</c>. When <c>add_group_members/3</c>
+ is called the Port and Dir options are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_group_member(GroupName, UserName, Options) -> true | {error, Reason}</name>
+ <name>delete_group_member(GroupName, UserName, Port, Dir) -> true | {error, Reason}</name>
+ <name>delete_group_member(GroupName, UserName, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Remove a user from a group.</fsummary>
+ <type>
+ <v>GroupName = string()</v>
+ <v>UserName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="delete_group_member"></marker>
+ <p><c>delete_group_member/3, delete_group_member/4</c> and <c>delete_group_member/5</c> deletes a user from a group.
+ If the group or the user does not exist,
+ this function returns an error, otherwise it returns <c>true</c>.
+ When <c>delete_group_member/3</c> is called the Port and Dir options
+ are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_group_members(GroupName, Options) -> {ok, Users} | {error, Reason}</name>
+ <name>list_group_members(GroupName, Port, Dir) -> {ok, Users} | {error, Reason}</name>
+ <name>list_group_members(GroupName, Address, Port, Dir) -> {ok, Users} | {error, Reason}</name>
+ <fsummary>List the members of a group.</fsummary>
+ <type>
+ <v>GroupName = string()</v>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Users = list()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="list_group_members"></marker>
+ <p><c>list_group_members/2, list_group_members/3</c> and <c>list_group_members/4</c>
+ lists the members of a specified group. If the group does not
+ exist or there is an error, <c>{error, Reason}</c> is returned.
+ When <c>list_group_members/2</c> is called the Port and Dir options
+ are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_groups(Options) -> {ok, Groups} | {error, Reason}</name>
+ <name>list_groups(Port, Dir) -> {ok, Groups} | {error, Reason}</name>
+ <name>list_groups(Address, Port, Dir) -> {ok, Groups} | {error, Reason}</name>
+ <fsummary>List all the groups.</fsummary>
+ <type>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Groups = list()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="list_groups"></marker>
+ <p><c>list_groups/1, list_groups/2</c> and <c>list_groups/3</c> lists all
+ the groups available. If there is an error, <c>{error, Reason}</c>
+ is returned. When <c>list_groups/1</c> is called the Port and Dir options
+ are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>delete_group(GroupName, Options) -> true | {error,Reason} &lt;name>delete_group(GroupName, Port, Dir) -> true | {error, Reason}</name>
+ <name>delete_group(GroupName, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Deletes a group</fsummary>
+ <type>
+ <v>Options = [Option]</v>
+ <v>Option = {port,Port} | {addr,Address} | {dir,Directory} | {authPassword,AuthPassword}</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>GroupName = string()</v>
+ <v>AuthPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="delete_group"></marker>
+ <p><c>delete_group/2, delete_group/3</c> and <c>delete_group/4</c> deletes the
+ group specified and returns <c>true</c>. If there is an error,
+ <c>{error, Reason}</c> is returned. When <c>delete_group/2</c> is called the
+ Port and Dir options are mandatory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>update_password(Port, Dir, OldPassword, NewPassword, NewPassword) -> ok | {error, Reason}</name>
+ <name>update_password(Address,Port, Dir, OldPassword, NewPassword, NewPassword) -> ok | {error, Reason}</name>
+ <fsummary>Change the AuthAcessPassword</fsummary>
+ <type>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>GroupName = string()</v>
+ <v>OldPassword = string()</v>
+ <v>NewPassword = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="update_password"></marker>
+ <p><c>update_password/5</c> and <c>update_password/6</c> Updates the AuthAccessPassword
+ for the specified directory. If NewPassword is equal to "NoPassword" no password is requires to
+ change authorisation data. If NewPassword is equal to "DummyPassword" no changes can be done
+ without changing the password first.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="see_also"></marker>
+ <title>SEE ALSO</title>
+ <p><seealso marker="httpd">httpd(3)</seealso>,
+ <seealso marker="mod_alias">mod_alias(3)</seealso>,</p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/mod_esi.xml b/lib/inets/doc/src/mod_esi.xml
new file mode 100644
index 0000000000..d4541a1d15
--- /dev/null
+++ b/lib/inets/doc/src/mod_esi.xml
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>mod_esi</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-10-14</date>
+ <rev>2.2</rev>
+ <file>mod_esi.sgml</file>
+ </header>
+ <module>mod_esi</module>
+ <modulesummary>Erlang Server Interface </modulesummary>
+ <description>
+ <p>This module defines the API - Erlang Server Interface (ESI).
+ Which is a more efficient way of writing erlang scripts
+ for your Inets web server than writing them as common CGI scripts.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>deliver(SessionID, Data) -> ok | {error, Reason}</name>
+ <fsummary>Sends Data back to client.</fsummary>
+ <type>
+ <v>SessionID = term()</v>
+ <v>Data = string() | io_list()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="deliver"></marker>
+ <p>This function is <em>only</em> intended to be used from
+ functions called by the Erl Scheme interface to deliver
+ parts of the content to the user.</p>
+ <p>Sends data from a Erl Scheme script back to the client.</p>
+
+ <note><p>Note
+ that if any HTTP-header fields should be added by the
+ script they must be in the first call to deliver/2 and the
+ data in the call must be a string. Do not
+ assume anything about the data type of SessionID, the
+ SessionID must be the value given as input to the esi
+ call back function that you implemented.</p></note>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>ESI Callback Functions</title>
+ </section>
+ <funcs>
+ <func>
+ <name>Module:Function(SessionID, Env, Input)-> _ </name>
+ <fsummary>Creates a dynamic web page and returns it chunk by chunk to the server process by calling mod_esi:deliver/2.</fsummary>
+ <type>
+ <v>SessionID = term()</v>
+ <v>Env = [EnvironmentDirectives] ++ ParsedHeader</v>
+ <v>EnvironmentDirectives = {Key,Value}</v>
+ <v>Key = query_string | content_length | server_software | gateway_interface | server_protocol | server_port | request_method | remote_addr | script_name. &lt;v>Input = string()</v>
+ </type>
+ <desc>
+ <p>The <c>Module</c> must be found in the code path and export
+ <c>Function</c> with an arity of two. An erlScriptAlias must
+ also be set up in the configuration file for the Web server.</p>
+ <p>If the HTTP request is a post request and a body is sent
+ then content_length will be the length of the posted
+ data. If get is used query_string will be the data after
+ <em>?</em> in the url.</p>
+ <p>ParsedHeader is the HTTP request as a key value tuple
+ list. The keys in parsed header will be the in lower case.</p>
+ <p>SessionID is a identifier
+ the server use when <c>deliver/2</c> is called, do not
+ assume any-thing about the datatype.</p>
+ <p>Use this callback function to dynamically generate dynamic web
+ content. when a part of the page is generated send the
+ data back to the client through <c>deliver/2</c>. Note
+ that the first chunk of data sent to the client must at
+ least contain all HTTP header fields that the response
+ will generate. If the first chunk not contains
+ <em>End of HTTP header</em> that is <c>"\\r\ \\r\ "</c>
+ the server will
+ assume that no HTTP header fields will be generated.</p>
+ </desc>
+ </func>
+ <func>
+ <name>Module:Function(Env, Input)-> Response </name>
+ <fsummary>Creates a dynamic web page and return it as a list. This functions is deprecated and only kept for backwards compatibility.</fsummary>
+ <type>
+ <v>Env = [EnvironmentDirectives] ++ ParsedHeader</v>
+ <v>EnvironmentDirectives = {Key,Value}</v>
+ <v>Key = query_string | content_length | server_software | gateway_interface | server_protocol | server_port | request_method | remote_addr | script_name. &lt;v>Input = string()</v>
+ <v>Response = string()</v>
+ </type>
+ <desc>
+ <p>This callback format consumes quite much memory since the
+ whole response must be generated before it is sent to the
+ user. This functions is deprecated and only keept for backwards
+ compatibility.
+ For new development Module:Function/3 should be used.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/mod_security.xml b/lib/inets/doc/src/mod_security.xml
new file mode 100644
index 0000000000..5f9f88071e
--- /dev/null
+++ b/lib/inets/doc/src/mod_security.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1998</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>mod_security</title>
+ <prepared>Mattias Nilsson</prepared>
+ <docno></docno>
+ <date>1997-11-18</date>
+ <rev>1.0</rev>
+ <file>mod_security.sgml</file>
+ </header>
+ <module>mod_security</module>
+ <modulesummary>Security Audit and Trailing Functionality</modulesummary>
+ <description>
+ <p>Security Audit and Trailing Functionality</p>
+ </description>
+ <funcs>
+ <func>
+ <name>list_auth_users(Port) -> Users | []</name>
+ <name>list_auth_users(Address, Port) -> Users | []</name>
+ <name>list_auth_users(Port, Dir) -> Users | []</name>
+ <name>list_auth_users(Address, Port, Dir) -> Users | []</name>
+ <fsummary>List users that have authenticated within the SecurityAuthTimeout time for a given address (if specified), port number and directory (if specified).</fsummary>
+ <type>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Users = list() = [string()]</v>
+ </type>
+ <desc>
+ <marker id="list_auth_users"></marker>
+ <p><c>list_auth_users/1</c>, <c>list_auth_users/2</c> and
+ <c>list_auth_users/3</c> returns a list of users that are
+ currently authenticated. Authentications are stored for
+ SecurityAuthTimeout seconds, and are then discarded.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_blocked_users(Port) -> Users | []</name>
+ <name>list_blocked_users(Address, Port) -> Users | []</name>
+ <name>list_blocked_users(Port, Dir) -> Users | []</name>
+ <name>list_blocked_users(Address, Port, Dir) -> Users | []</name>
+ <fsummary>List users that are currently blocked from access to a specified port number, for a given address (if specified).</fsummary>
+ <type>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Users = list() = [string()]</v>
+ </type>
+ <desc>
+ <marker id="list_blocked_users"></marker>
+ <p><c>list_blocked_users/1</c>, <c>list_blocked_users/2</c> and
+ <c>list_blocked_users/3</c> returns a list of users that are
+ currently blocked from access.</p>
+ </desc>
+ </func>
+ <func>
+ <name>block_user(User, Port, Dir, Seconds) -> true | {error, Reason}</name>
+ <name>block_user(User, Address, Port, Dir, Seconds) -> true | {error, Reason}</name>
+ <fsummary>Block user from access to a directory for a certain amount of time.</fsummary>
+ <type>
+ <v>User = string()</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Seconds = integer() | infinity</v>
+ <v>Reason = no_such_directory</v>
+ </type>
+ <desc>
+ <marker id="block_user"></marker>
+ <p><c>block_user/4</c> and <c>block_user/5</c> blocks the user
+ <c>User</c> from the directory <c>Dir</c> for a specified
+ amount of time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>unblock_user(User, Port) -> true | {error, Reason}</name>
+ <name>unblock_user(User, Address, Port) -> true | {error, Reason}</name>
+ <name>unblock_user(User, Port, Dir) -> true | {error, Reason}</name>
+ <name>unblock_user(User, Address, Port, Dir) -> true | {error, Reason}</name>
+ <fsummary>Remove a blocked user from the block list</fsummary>
+ <type>
+ <v>User = string()</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() | undefined</v>
+ <v>Dir = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <marker id="unblock_user"></marker>
+ <p><c>unblock_user/2</c>, <c>unblock_user/3</c> and
+ <c>unblock_user/4</c> removes the user <c>User</c> from
+ the list of blocked users for the Port (and Dir) specified.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="callback_module"></marker>
+ <title>The SecurityCallbackModule</title>
+ <p>The SecurityCallbackModule is a user written module that can receive events from
+ the mod_security Erlang Webserver API module. This module only exports one function,
+ <seealso marker="#callback_module_event">event/4</seealso>, which is described below.
+ </p>
+ </section>
+ <funcs>
+ <func>
+ <name>event(What, Port, Dir, Data) -> ignored</name>
+ <name>event(What, Address, Port, Dir, Data) -> ignored</name>
+ <fsummary>This function is called whenever an event occurs in mod_security</fsummary>
+ <type>
+ <v>What = atom()</v>
+ <v>Port = integer()</v>
+ <v>Address = {A,B,C,D} | string() &lt;v>Dir = string()</v>
+ <v>What = [Info]</v>
+ <v>Info = {Name, Value}</v>
+ </type>
+ <desc>
+ <marker id="callback_module_event"></marker>
+ <p><c>event/4</c> or <c>event/4</c> is called whenever an event
+ occurs in the mod_security Erlang Webserver API module (<c>event/4</c> is
+ called if Address is undefined and <c>event/5</c> otherwise).
+ The <c>What</c> argument specifies the type of event that has
+ occurred, and should be one of the following reasons;
+ <c>auth_fail</c> (a failed user authentication),
+ <c>user_block</c> (a user is being blocked from access) or
+ <c>user_unblock</c> (a user is being removed from the block list).</p>
+ <note>
+ <p>Note that the <c>user_unblock</c> event is not triggered when
+ a user is removed from the block list explicitly using the
+ <c>unblock_user</c> function.</p>
+ </note>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/inets/doc/src/note.gif b/lib/inets/doc/src/note.gif
new file mode 100644
index 0000000000..6fffe30419
--- /dev/null
+++ b/lib/inets/doc/src/note.gif
Binary files differ
diff --git a/lib/inets/doc/src/notes.gif b/lib/inets/doc/src/notes.gif
new file mode 100644
index 0000000000..e000cca26a
--- /dev/null
+++ b/lib/inets/doc/src/notes.gif
Binary files differ
diff --git a/lib/inets/doc/src/notes.xml b/lib/inets/doc/src/notes.xml
new file mode 100644
index 0000000000..489e88cbe5
--- /dev/null
+++ b/lib/inets/doc/src/notes.xml
@@ -0,0 +1,929 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2002</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets Release Notes</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2002-02-28</date>
+ <rev>A</rev>
+ <file>notes.xml</file>
+ </header>
+
+ <section><title>Inets 5.2</title>
+
+ <section><title>Improvements and New Features</title>
+<!--
+ <p>-</p>
+-->
+ <list>
+ <item>
+ <p>[ftpc] - Start of the FTP client has been changed in
+ the following way: </p>
+ <list type="bulleted">
+ <item>
+ <p>It is now also possible to start a standalone FTP client
+ process using the re-introduced
+ <seealso marker="ftp#open">ftp:open</seealso>
+ function. </p>
+ <p>This is an alternative to starting the client using the
+ <seealso marker="ftp#service_start">inets service framework</seealso>. </p>
+ <p>The old <c>ftp:open/1</c>, undocumented, function,
+ caused the client to be hooken into the inets service
+ supervision framework. This is <em>no</em> longer the
+ case. </p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ </item>
+ <item>
+ <p>Previously, the FTP client attempted to use IPv6,
+ unless otherwise instructed (the <c>ip_v6_disabled</c>
+ flag), and only used IPv4 if this did not work.
+ This has now been <em>changed</em>. </p>
+ <p>A new option,
+ <seealso marker="ftp#ipfamily">ipfamily</seealso>,
+ has been introduced, with the default value
+ <c>inet</c> (IPv4). </p>
+ <p>See <seealso marker="ftp#open">ftp:open</seealso>
+ for more info.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ </item>
+ </list>
+ <p>Own Id: OTP-8258</p>
+ <!-- <p>Aux Id: seq11407</p> -->
+ </item>
+
+ <item>
+ <p>The documentation is now built with open source tools
+ (<em>xsltproc</em> and <em>fop</em>) that exists on most
+ platforms. One visible change is that the frames are removed.</p>
+ <p>Own Id: OTP-8249</p>
+ </item>
+
+ </list>
+ </section>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>[httpc] - Streaming to file did not work.</p>
+ <p>Own Id: OTP-8204</p>
+ </item>
+
+ <item>
+ <p>[ftpc] - The
+ <seealso marker="ftp#ls2">ls/2</seealso> function (LIST command)
+ and the
+ <seealso marker="ftp#nlist2">nlist/2</seealso> function
+ (NLST command)
+ with wildcards did
+ not work properly. </p>
+ <p>These functions is documented as working on directories, but
+ this is actually not according the standard. The LIST and NLST
+ commands are specified to operate on a directory or other
+ group of files, or a file.</p>
+ <p>Previously, an attempt was made to check if the listing
+ returned by the server was actually an error message. This
+ was done by changing remote directory (cd) into the
+ (assumed) "directory". This may work if Pathname was actually
+ a directory, but as this is not always the case, this test
+ does not work. Instead, we now return the actual server
+ result and leave the interpretation to the caller. </p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-8247</p>
+ <p>Aux Id: seq11407</p>
+ </item>
+
+ <item>
+ <p>[httpc] - Fixes various bugs in timeout and keep-alive queue
+ handling. </p>
+ <list type="bulleted">
+ <item>
+ <p>When a queued request times, out the error mssage is sent
+ the owner of the active request. </p>
+ </item>
+
+ <item>
+ <p>Requests in the keep-alive queue is forgotten when
+ handler terminates. </p>
+ </item>
+
+ <item>
+ <p>Timeout out requests are retried. </p>
+ </item>
+ </list>
+ <p>Jean-S�bastien P�dron</p>
+ <p>Own Id: OTP-8248</p>
+ </item>
+
+ <item>
+ <p>[httpd] - Unnecessarily strict matching when handling closing sockets. </p>
+ <p>Own Id: OTP-8280</p>
+ </item>
+
+ </list>
+ </section>
+
+ </section> <!-- 5.2 -->
+
+
+ <section><title>Inets 5.1.3</title>
+
+ <section><title>Improvements and New Features</title>
+ <p>-</p>
+<!--
+ <list>
+ <item>
+ <p>[httpc] Added support for web services using only basic auth,
+ with a token as the user part and no password part.</p>
+ <p>Own Id: OTP-7998</p>
+ </item>
+
+ </list>
+-->
+ </section>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>[httpc] - Raise condition.
+ When http:request is called and httpc_manager selects a session
+ where there's already a pending request, then the connection
+ handler for that session effectively resets its parser, readying
+ it for the response to the second request. But if there are still
+ some inbound packets for the response to the first request, things
+ get confused.</p>
+ <p>Own Id: OTP-8154</p>
+ </item>
+
+ </list>
+ </section>
+
+ </section> <!-- 5.1.3 -->
+
+
+ <section><title>Inets 5.1.2</title>
+<!--
+ <p>-</p>
+-->
+
+ <section><title>Improvements and New Features</title>
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>[httpc] - Added http option <c>connect_timeout</c> for http
+ client request.
+ The <c>connect_timeout</c> option is used for the initial
+ request, when the client connects to the server. Default
+ value is that of the <c>timeout</c> option. </p>
+ <p>See the
+ <seealso marker="http#request2">request/4,5</seealso>
+ function for more info. </p>
+ <p>Own Id: OTP-7298</p>
+ <!-- <p>Aux Id: seq11086</p> -->
+ </item>
+
+ </list>
+ </section>
+
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>[httpd] - Failed to create listen socket with invalid
+ option combo. The http-server failed to create its listen
+ socket when the bind-address was an IPv4-address (a tuple of
+ size 4) and the ipfamily option was inet6fb4. </p>
+ <p>Own Id: OTP-8118</p>
+ <p>Aux Id: seq11321</p>
+ </item>
+
+ <item>
+ <p>[httpd] - Removed documentation for non-existing function
+ (httpd_util:header/2,3,4). </p>
+ <p>Own Id: OTP-8101</p>
+ <!-- <p>Aux Id: seq11321</p> -->
+ </item>
+
+ </list>
+ </section>
+
+ </section> <!-- 5.1.2 -->
+
+
+ <section><title>Inets 5.1.1</title>
+<!--
+ <p>-</p>
+-->
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>[httpd] - When starting inets (the web-server) and supplying
+ a descriptor on the command line
+ (example: erl -httpd_8888 &lt;descriptor&gt;)
+ it is now possible to specify which ip-family to use:
+ <c>inet | inet6 | inet6fb4</c>. </p>
+ <p>Example: erl -httpd_8888 10|inet6</p>
+ <p>When starting the web-server either using a file with
+ property list (the proplist_file) or a an property list,
+ using the ipfamily option:
+ <c>{ipfamily, inet | inet6 | inet6fb4}</c>. </p>
+ <p>Finally, when starting the web-server using the classical
+ apache-style config file, the <c>BindAddress</c> directive
+ has been augmented to allow the specification of the
+ IpFamily: <c>BindAddress blirk.ericsson.se|inet</c></p>
+ <p>Default is <c>inet6fb4</c> which emulates the
+ behaviour of the previous version. </p>
+ <p>See the
+ <seealso marker="httpd#comm_prop">Communication properties</seealso>
+ section for more info. </p>
+ <p>Own Id: OTP-8069</p>
+ <p>Aux Id: seq11086</p>
+ </item>
+
+ </list>
+ </section>
+
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>[httpc] - Reception of unexpected data causes handler crash. </p>
+ <p>Own Id: OTP-8052</p>
+ </item>
+
+ </list>
+ </section>
+
+ </section> <!-- 5.1.1 -->
+
+
+ <section><title>Inets 5.1</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>[httpc] Added support for web services using only basic auth,
+ with a token as the user part and no password part.</p>
+ <p>Own Id: OTP-7998</p>
+ </item>
+
+ <item>
+ <p>[httpc] - Bind HTTP client to IP-addr. It is now possible
+ to specify an alternate ip-address and port to be used when
+ the client connects to the server. </p>
+ <p>As a side-effect of this, the option <c>ipv6</c> has been
+ removed and replaced by the <c>ipfamily</c> option. </p>
+ <p>See <seealso marker="http#set_options">http:set_options/1,2</seealso>
+ for more info. </p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-8004</p>
+ </item>
+
+ </list>
+ </section>
+
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+<!--
+ <p>-</p>
+-->
+
+ <list>
+ <item>
+ <p>Updated guard tests (i.e. is_list(L) instead of
+ list(L) and possibly andalso/orelse instead of ","/";"). </p>
+ <p>Own Id: OTP-7994</p>
+ </item>
+
+ <item>
+ <p>[httpc] - Remove use of the deprecated regexp module. </p>
+ <p>Own Id: OTP-8001</p>
+ </item>
+
+ <item>
+ <p>[httpc] - The option <c>max_keep_alive_length</c> was
+ not handled properly. </p>
+ <p>Own Id: OTP-8005</p>
+ </item>
+
+
+ </list>
+ </section>
+
+ </section> <!-- 5.1 -->
+
+
+ <section><title>Inets 5.0.14</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [tftp] The callback watchdog has been removed, as it
+ turned out to be counter productive when the disk was
+ overloaded. Earlier a connection was aborted when a
+ callback (which performs the file access in the TFTP
+ server) took too long time.</p>
+ <p>
+ [tftp] The error message "Too many connections" has been
+ reclassified to be a warning.</p>
+ <p>
+ Own Id: OTP-7888</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>[httpc] - Incorrect http version option check. </p>
+ <p>Mats Cronqvist</p>
+ <p>Own Id: OTP-7882</p>
+ </item>
+
+ <item>
+ <p>[httpc] - Unnecessary error report when client
+ terminating as a result of the server closed the
+ socket unexpectedly. </p>
+ <p>Own Id: OTP-7883</p>
+ </item>
+
+ <item>
+ <p>[httpc] - Failed transforming a relative URI to
+ an absolute URI. </p>
+ <p>Own Id: OTP-7950</p>
+ </item>
+
+ <item>
+ <p>[httpd] - The HTTP server did not handle the config
+ option ssl_ca_certificate_file. </p>
+ <p>Own Id: OTP-7976</p>
+ </item>
+
+ </list>
+ </section>
+
+ </section> <!-- 5.0.14 -->
+
+
+ <section><title>Inets 5.0.13</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Ssl did not work correctly with the use of new style
+ configuration due to sn old internal format that was not
+ changed correctly in all places.</p>
+ <p>
+ Own Id: OTP-7723 Aux Id: seq11143 </p>
+ </item>
+ <item>
+ <p>
+ [httpc] - Now streams 200 and 206 results and not only
+ 200 results.</p>
+ <p>
+ Own Id: OTP-7857</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpc] - The inets http client will now use persistent
+ connections without pipelining as default and if a
+ pipeline timeout is set it will pipeline the requests on
+ the persistent connections.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7463</p>
+ </item>
+ <item>
+ <p>
+ [httpd] - added option ssl_password_callback_arguments.</p>
+ <p>
+ Own Id: OTP-7724 Aux Id: seq11151 </p>
+ </item>
+ <item>
+ <p>
+ Changed the socket use so that it will become more robust
+ to non-functional ipv6 and fallback on ipv4. This changes
+ may for very special os-configurations cause a problem
+ when used with erts-versions pre R13.</p>
+ <p>
+ Own Id: OTP-7726</p>
+ </item>
+ <item>
+ <p>
+ Removed deprecated function httpd_util:key1search/[2,3]</p>
+ <p>
+ Own Id: OTP-7815</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.12</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpd] - Updated inets so that it not uses the deprecated
+ function ssl:accept/[2,3].</p>
+ <p>
+ Own Id: OTP-7636 Aux Id: seq11086 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+
+ <section><title>Inets 5.0.11</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Transient bug related to hot code swap of the TFTP server is
+ now fixed. It could happen that the first TFTP server that was
+ started after a code upgrade to Inets-5.0.6 crashed with a
+ function clause error in tftp_engine:service_init/2.</p>
+ <p> Own Id: OTP-7574 Aux Id: seq11069 </p>
+ </item>
+ <item>
+ <p>
+ [httpd] - Validation of ssl_password_callback_module was
+ incorrect.</p>
+ <p>
+ Own Id: OTP-7597 Aux Id: seq11074 </p>
+ </item>
+ <item>
+ <p>
+ [httpd] - Misspelling in old apachelike configuration
+ directive TransferDiskLogSize has been corrected.</p>
+ <p> Own Id: OTP-7598 Aux Id: seq11059 </p>
+ </item>
+ <item>
+ <p>
+ Minor problems found by dialyzer has been fixed.</p>
+ <p>
+ Own Id: OTP-7605</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+<section><title>Inets 5.0.10</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Enhanched an info report.</p>
+ <p>
+ Own Id: OTP-7450</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Changed errro message from
+ {wrong_type,{document_root,"/tmp/htdocs"}} to
+ {invalid_option,{non_existing,
+ document_root,"/tmp/htdocs"}}.</p>
+ <p>
+ Own Id: OTP-7454</p>
+ </item>
+ <item>
+ <p>
+ Relative paths in directory authentication did not work
+ as intended, this has now been fixed.</p>
+ <p>
+ Own Id: OTP-7490</p>
+ </item>
+ <item>
+ <p>
+ The query-string passed to the callback function was not
+ compliant with the documentation, it is now.</p>
+ <p>
+ Own Id: OTP-7512</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+ <section><title>Inets 5.0.9</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Parameters to error_logger:error_report/1 has been
+ corrected.</p>
+ <p>
+ Own Id: OTP-7257 Aux Id: OTP-7294, OTP-7258 </p>
+ </item>
+ <item>
+ <p>
+ [httpd] - If a Module/Function request matching an
+ erl_script_alias registration does not exist as a function in
+ the module registered a 404 error will now be issued instead of a
+ 500 error.</p>
+ <p>
+ Own Id: OTP-7323</p>
+ </item>
+ <item>
+ <p>
+ [httpd] -The option auth_type for mod_auth is no longer
+ mandatory, for backward-compatibility reasons.</p>
+ <p>
+ Own Id: OTP-7341</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.8</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ [httpd] - Spelling error caused client connection header
+ to be ignored.</p>
+ <p>
+ Own Id: OTP-7315 Aux Id: seq10951 </p>
+ </item>
+ <item>
+ <p>
+ [httpd] - Call to the function
+ mod_get:get_modification_date/1 was made too early
+ resulting in that httpd did not send the 404 file missing
+ response.</p>
+ <p>
+ Own Id: OTP-7321</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.7</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpc, httpd] - Now follows the recommendation regarding
+ line terminators in section 19.3 in RFC 2616 e.i: "The
+ line terminator for message-header fields is the sequence
+ CRLF. However, we recommend that applications, when
+ parsing such headers, recognize a single LF as a line
+ terminator and ignore the leading CR".</p>
+ <p>
+ Own Id: OTP-7304 Aux Id: seq10944 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.6</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [tftp] If a callback (which performs the file access in
+ the TFTP server) takes too long time (more than the
+ double TFTP timeout), the server will abort the
+ connection and send an error reply to the client. This
+ implies that the server will release resources attached
+ to the connection faster than before. The server simply
+ assumes that the client has given up.</p>
+ <p>
+ [tftp] If the TFTP server receives yet another request
+ from the same client (same host and port) while it
+ already has an active connection to the client, it will
+ simply ignore the new request if the request is equal
+ with the first one (same filename and options). This
+ implies that the (new) client will be served by the
+ already ongoing connection on the server side. By not
+ setting up yet another connection, in parallel with the
+ ongoing one, the server will consumer lesser resources.</p>
+ <p>
+ [tftp] netascii mode is now supported when the
+ client/server has native ascii support (Windows). The new
+ optional parameter native_ascii in the tftp_binary and
+ tftp_file callback modules can be used to override the
+ default behavior.</p>
+ <p>
+ [tftp] Yet another callback module has been added in
+ order to allow customized handling of error, warning and
+ info messages. See the new configuration parameter,
+ logger.</p>
+ <p>
+ [tftp] Yet another configuration parameter, max_retries,
+ has been added in order to control the number of times a
+ packet can be resent. The default is 5.</p>
+ <p>
+ [tftp] tftp:info/1 and tftp:change_config/2 can now be
+ applied to all daemons or all servers in one command
+ without bothering about their process identifiers.</p>
+ <p>
+ External TR HI89527.</p>
+ <p>
+ Own Id: OTP-7266</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Inets 5.0.5</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [tftp] Blocks with too low block numbers are silently
+ discarded. For example if a server receives block #5 when
+ it expects block #7 it will discard the block without
+ interrupting the file transfer. Too high block numbers
+ does still imply an error. External TR HI96072.</p>
+ <p>
+ Own Id: OTP-7220</p>
+ </item>
+ <item>
+ <p>
+ [tftp] The problem with occasional case_clause errors in
+ tftp_engine:common_read/7 has been fixed. External TR
+ HI97362.</p>
+ <p>
+ Own Id: OTP-7221</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+ <section><title>Inets 5.0.4</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Changed calls to file open to concur with the API and not
+ use deprecated syntax.</p>
+ <p>
+ Own Id: OTP-7172</p>
+ </item>
+ <item>
+ <p>
+ [tftp] Server lost the first packet when the client timed
+ out</p>
+ <p>
+ Own Id: OTP-7173</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.3</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Updated copyright headers and fixed backwards
+ compatibility for an undocumented feature, for now. This
+ feature will later be removed and a new and documented
+ option will take its place.</p>
+ <p>
+ Own Id: OTP-7144</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.2</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpd] - Error logs now has a pretty and a compact
+ format and access logs can be written on the common log
+ format or the extended common log format.</p>
+ <p>
+ Own Id: OTP-6661 Aux Id: Seq 7764 </p>
+ </item>
+ <item>
+ <p>
+ [httpc] - Added acceptance of missing reason phrase to
+ the relaxed mode.</p>
+ <p>
+ Own Id: OTP-7024</p>
+ </item>
+ <item>
+ <p>
+ [httpc] - A new option has been added to enable the
+ client to act as lower version clients, by default the
+ client is an HTTP/1.1 client.</p>
+ <p>
+ Own Id: OTP-7043</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ [httpd] - Deprecated function httpd:start/1 did not
+ accept all inputs that it had done previously. This
+ should now work again.</p>
+ <p>
+ Own Id: OTP-7040</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpd] - Changed validity check on bind_address so that
+ it uses inet:getaddr instead of inet:gethostbyaddr as the
+ former puts a too hard restriction on the bind_address.</p>
+ <p>
+ Own Id: OTP-7041 Aux Id: seq10829 </p>
+ </item>
+ <item>
+ <p>
+ [httpc] - Internal process now does try-catch and
+ terminates normally in case of HTTP parse errors.
+ Semantical the client works just as before returning an
+ error message to the client, even if the error massage
+ has been enhanced, but there is no supervisor report in
+ the shell of a internal process crashing. (Which was the
+ expected behavior and not a fault.)</p>
+ <p>
+ Own Id: OTP-7042</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Inets 5.0</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [httpd, httpc] - Deprecated base64 decode/encode
+ functions have been removed. Inets uses base64 in STDLIB
+ instead.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-6485</p>
+ </item>
+ <item>
+ <p>
+ [httpd] - It is now possible to restrict the length of
+ acceptable URI:s in the HTTP server.</p>
+ <p>
+ Own Id: OTP-6572</p>
+ </item>
+ <item>
+ <p>
+ [httpc] - Profiles are now supported i.e. the options
+ available in set_options/1 can be set locally for a
+ certain profile and do not have to affect all
+ HTTP-requests issued in the Erlang node. Calls to the
+ HTTP client API functions not using the profile argument
+ will use the default profile.</p>
+ <p>
+ Own Id: OTP-6690</p>
+ </item>
+ <item>
+ <p>
+ A new uniform Inets interface provides a flexible way to
+ start/stop Inets services and get information about
+ running services. See inets(3). This also means that
+ inflexibilities in the HTTP server has been removed and
+ more default values has been added.</p>
+ <p>
+ Own Id: OTP-6705</p>
+ </item>
+ <item>
+ <p>
+ [tftp] Logged errors have been changed to be logged
+ warnings.</p>
+ <p>
+ Own Id: OTP-6916 Aux Id: seq10737 </p>
+ </item>
+ <item>
+ <p>
+ [httpc] - The client will now return the proper value
+ when receiving a HTTP 204 code instead of hanging.</p>
+ <p>
+ Own Id: OTP-6982</p>
+ </item>
+ <item>
+ <p>
+ The Inets application now has to be explicitly started
+ and stopped i.e. it will not automatically be started as
+ a temporary application as it did before. Although a
+ practical feature when testing things in the shell it is
+ not desirable that people take advantage of this and not
+ start the Inets application in a correct way in their
+ products. Added functions to the Inets API that call
+ application:start/stop.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-6993</p>
+ </item>
+ </list>
+ </section>
+
+ <!-- p>For information about older versions see
+ <url href="part_notes_history_frame.html">release notes history</url>.</p -->
+ </section>
+</chapter>
+
+
diff --git a/lib/inets/doc/src/notes_history.xml b/lib/inets/doc/src/notes_history.xml
new file mode 100644
index 0000000000..53375c9aa7
--- /dev/null
+++ b/lib/inets/doc/src/notes_history.xml
@@ -0,0 +1,1826 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets Release Notes History</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>04-09-30</date>
+ <rev>A</rev>
+ <file>notes_history.sgml</file>
+ </header>
+
+ <section>
+ <title>Inets 4.7.17</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[HTTP client] - Could fail in retry_pipeline/2 due to an
+ incorrect assumption of an internal returnvalue.</p>
+ <p>Own Id: OTP-6791</p>
+ </item>
+ <item>
+ <p>[HTTP client] - The check of the value of the transfer
+ encoding has been updated so that it is case insensitive.</p>
+ <p>Own Id: OTP-6807</p>
+ </item>
+ <item>
+ <p>[HTTP client] - When receiving a 304 "Not Modified"
+ reply, the httpc_handler will no longer expect to receive
+ a HTTP body.</p>
+ <p>Own Id: OTP-6821</p>
+ </item>
+ <item>
+ <p>[HTTP client] - Parsing of the HTTP response failed when
+ there was no headers fields in the response.</p>
+ <p>Own Id: OTP-6830</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[HTTP server] - Started clean up of code so that it uses
+ stdlib functions instead of reinventing them.</p>
+ <p>Own Id: OTP-6808</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Inets 4.7.16</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Minor Makefile changes.</p>
+ <p>Own Id: OTP-6689</p>
+ </item>
+ <item>
+ <p>http_base_64:encode/decode and
+ httpd_util:to_upper/to_lower are now deprecated, as these
+ functions has been moved to stdlib, using them will now
+ cause an compiler warning and the documentation of them
+ has been removed.</p>
+ <p>Own Id: OTP-6716</p>
+ </item>
+ <item>
+ <p>When making an asynchronous HTTP request and the
+ underlying gen_tcp:connect failed with timeout (not a
+ very common case) the return of the asynchronous HTTP
+ request was delayed for "timeout" seconds. This happened
+ due to the fact that when spawning a gen_server process
+ the spawn will wait for the init function to complete.
+ This is now avoided using proc_lib and
+ gen_server:enter_loop/3, hence the asynchronous HTTP
+ request return will not be delayed. Also the request
+ timeout value is now propagated to gen_tcp rather that
+ relying on the system default.</p>
+ <p>Own Id: OTP-6735</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.15</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[tftp] The TFTP client/server implements now a more
+ relaxed interpretation of the RFC 1350 regarding
+ re-receive of acknowledgments. If multiple copies of the
+ same acknowledgments is received the spurious ones are
+ silently ignored. This fix was intended for inets-4.7.14
+ but accidentaly it was not included in that release.</p>
+ <p>Own Id: OTP-6706 Aux Id: OTP-6691 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Minor Makefile changes.</p>
+ <p>Own Id: OTP-6689</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.14</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[tftp] The TFTP client/server implements now a more
+ relaxed interpretation of the RFC 1350 regarding
+ re-receive of acknowledgments. If multiple copies of the
+ same acknowledgments is received the spurious ones are
+ silently ignored.</p>
+ <p>Own Id: OTP-6691</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.13</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[tftp] The TFTP client/server implements now a more
+ relaxed interpretation of the RFC 1350 regarding
+ re-receive of data packets. If multiple copies of the
+ same data packet is received the spurious ones are
+ silently ignored.</p>
+ <p>Own Id: OTP-6642</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.12</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] - When calling httpd:restart there was a file
+ descriptor and ets table leek due to the fact that the
+ semantics of the function restart is not restart but
+ reload.</p>
+ <p>Own Id: OTP-6573 Aux Id: seq10607 </p>
+ </item>
+ <item>
+ <p>[tftp] Crash in tftp_engine:terminate/3 caused big crash
+ report. The file was however transferred as normal, but
+ the ugly printout is now gone.</p>
+ <p>Own Id: OTP-6596 Aux Id: seq10618 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.11</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http] - Chunked encoding updated to handle the empty
+ chunk.</p>
+ <p>Own Id: OTP-6511</p>
+ </item>
+ <item>
+ <p>[http] - Removed minor bugs and dead code found by
+ dialyzer.</p>
+ <p>Own Id: OTP-6522</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.10</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] - The server no longer produces error messages
+ when the client resets the the connection. This is not an
+ error as far as the server is concerned.</p>
+ <p>Own Id: OTP-6484 Aux Id: seq10568 </p>
+ </item>
+ <item>
+ <p>[tftp] The server is now silent by default. Error
+ messages can however be displayed by setting the debug
+ level to 'error' (new) or higher.</p>
+ <p>Own Id: OTP-6498</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.9</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Bug in in handling of request timers has been corrected.</p>
+ <p>Own Id: OTP-6476</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[tftp] - Daemon was only able to process one request when
+ fd option was given.</p>
+ <p>Own Id: OTP-6480</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.8</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, httpc] - Updated the internal ensure_started
+ functions to handle that inets was started as an included
+ application.</p>
+ <p>Own Id: OTP-6409 Aux Id: seq10546 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] - Guard added to API function
+ httpd_util:integer_to_hexlist/1.</p>
+ <p>Own Id: OTP-6397</p>
+ </item>
+ <item>
+ <p>[tftp] - Introduced ability to use prebound ports (see
+ the option {port, Port} for more info). Added peer info
+ (host and port) as new optional argument to prepare and
+ open functions in tftp callback modules.</p>
+ <p>Own Id: OTP-6413</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.7</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] - The http server could throw away pipelined
+ requests leaving the client hanging.</p>
+ <p>Own Id: OTP-6310</p>
+ </item>
+ <item>
+ <p>[ftp] - Code for handling fallback to ipv4 was not
+ exhaustive.</p>
+ <p>Own Id: OTP-6312</p>
+ </item>
+ <item>
+ <p>[httpd] - Incorrect handling of ipv6 address would crash
+ the loading of the BindAddress parameter, which had the
+ consequence that you could not start more than one HTTP
+ server on an erlang node.</p>
+ <p>Own Id: OTP-6323</p>
+ </item>
+ <item>
+ <p>[httpc] - Some 30X codes, as for instance 302, should not
+ always be automatically redirected but in inets-4.7.6 some
+ restrictions where made too hard, never allowing an
+ automatic redirection. (Automatic redirect should be
+ allowed for get and head.)</p>
+ <p>Own Id: OTP-6332</p>
+ </item>
+ <item>
+ <p>[ftp] - The mode flag that could be used to force ftp
+ active mode was ignored. Only the deprecated function
+ force_active/1 works for prior releases to this one.</p>
+ <p>Own Id: OTP-6342</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpc] - Added debug feature to turn on/off some basic
+ erlang tracing on client processes.</p>
+ <p>Own Id: OTP-6326</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.6</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpc] - The parsing of uri's was rewritten so that it
+ should handle all types of uri's including ipv6 uri's.</p>
+ <p>Own Id: OTP-5677</p>
+ </item>
+ <item>
+ <p>[httpc, httpd] - Extensions and trailers where not
+ properly handled by the chunk decoding implementation.</p>
+ <p>Own Id: OTP-6005 Aux Id: OTP-6264 </p>
+ </item>
+ <item>
+ <p>[httpc] - A request resulting in an empty body is now
+ returned without any delays.</p>
+ <p>Own Id: OTP-6243</p>
+ </item>
+ <item>
+ <p>[httpc] - When http:request/4 was used with a configured
+ proxy, and the webserver returns 3XX code, http:request/4
+ entered an endless loop. Two problems was solved in this
+ area, the absolute uri is now updated when a redirect is
+ issued, so that the problem in this case will not arise,
+ and the redirection endless loop detection was fixed so
+ that will actually detect potential endless loops.</p>
+ <p>Own Id: OTP-6244</p>
+ </item>
+ <item>
+ <p>[httpc, httpd] - In some cases if a body contained the
+ sequence "\\r\
+ 0" and was chunked encoded this sequence
+ was incorrectly interpreted as the last chunk.</p>
+ <p>Own Id: OTP-6264 Aux Id: OTP-6005 </p>
+ </item>
+ <item>
+ <p>[httpc, httpd] - http_request.erl didn't handle https
+ URIs, which meant that redirects from ESI did not work.</p>
+ <p>Own Id: OTP-6274</p>
+ </item>
+ <item>
+ <p>[httpc, httpd] - The base 64 decoder was missing a guard
+ so that invalid input lead to an emulator crash instead
+ of a function clause as expected. Also the http server
+ has been improved to handle the function clause error
+ returning a bad credentials reply to the client.</p>
+ <p>Own Id: OTP-6279</p>
+ </item>
+ <item>
+ <p>[httpc] - Changed internal default value as it sometimes
+ would be interpreted incorrectly causing the client to
+ return an incomplete body.</p>
+ <p>Own Id: OTP-6283</p>
+ </item>
+ <item>
+ <p>[httpc] - Handling of 30X codes was changed so that it
+ works according to the documentation. For instance 301
+ and 302 codes will not be automatically redirected.</p>
+ <p>Own Id: OTP-6297</p>
+ </item>
+ <item>
+ <p>[httpc] - A bug in the pipeline-handling code could cause
+ a response to be sent to the client with an incorrect
+ request id.</p>
+ <p>Own Id: OTP-6303</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpc] - Added feature to send header values as they
+ where typed by the user of the client. Note that the http
+ standard requires them to be case insensitive. This
+ feature should only be used if there is no other way to
+ communicate with the server or for testing purpose.</p>
+ <p>Own Id: OTP-5527</p>
+ </item>
+ <item>
+ <p>[httpc] - When using asynchronous HTTP-request it is now
+ possible to receive "200-responses" as streams instead of
+ having to wait until the whole response has been
+ delivered. It also possible to stream "200-response
+ bodys" to a file both for synchronous and asynchronous
+ requests.</p>
+ <p>Own Id: OTP-6263</p>
+ </item>
+ <item>
+ <p>[httpc] - Added option to generate Proxy-Authorization
+ header from provided proxy username and password.</p>
+ <p>Own Id: OTP-6280</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.5</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[FTP] Change documentation so that it agrees with the
+ default behaviour of the code regarding the use of
+ transfer type, which is right according to rfc959.</p>
+ <p>Own Id: OTP-6018</p>
+ </item>
+ <item>
+ <p>[ftp] The application handles the case if the owning
+ process terminates with the reason 'shutdown'.</p>
+ <p>Own Id: OTP-6035</p>
+ </item>
+ <item>
+ <p>[ftp] Handle file errors from the FTP server.</p>
+ <p>Own Id: OTP-6036</p>
+ </item>
+ <item>
+ <p>[httpd] Header parsing of reply from cgi script incorrect.</p>
+ <p>Own Id: OTP-6145</p>
+ </item>
+ <item>
+ <p>[ftp] The timeout given in the ftp:open call was not
+ properly used, which could leave the caller hanging
+ forever.</p>
+ <p>Own Id: OTP-6184</p>
+ <p>Aux Id: seq10388</p>
+ </item>
+ <item>
+ <p>[httpd] HTTPD request handler does not handle unexpected info
+ properly, which causes an unnecessarily obscure error
+ message.</p>
+ <p>Own Id: OTP-6189</p>
+ <p>Aux Id: seq10395</p>
+ </item>
+ <item>
+ <p>[http] Misc fixes in the URI parsing module.</p>
+ <p>Igor Goryachev</p>
+ <p>Own Id: OTP-6191</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added application interface module: <c>inets</c>.</p>
+ <p>Own Id: OTP-6135</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.4</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed code generating compiler warnings</p>
+ <p>Own Id: OTP-6069</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[tftp] Added documentation (manual page) for
+ <seealso marker="tftp">TFTP</seealso>.</p>
+ <p>Own Id: OTP-6082</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.3</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] started dbg even though no debugging was
+ desired.</p>
+ <p>Own Id: OTP-5984 Aux Id: seq10290 </p>
+ </item>
+ <item>
+ <p>[http,server] request handler process died ugly due to a
+ parse error when validating a bad request.</p>
+ <p>Own Id: OTP-6003 Aux Id: seq10260 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] Server falsely sets ipv6 enabled when it
+ gets an ipv4-mapped ipv6 address.</p>
+ <p>Own Id: OTP-5941 Aux Id: seq10221 </p>
+ </item>
+ <item>
+ <p>[http,server] In case http version is unknown of client
+ use HTTP1.0 to send status.</p>
+ <p>Own Id: OTP-5943 Aux Id: seq10198 </p>
+ </item>
+ <item>
+ <p>[http,server] The process handling a request now ignores
+ garbage messages.</p>
+ <p>Own Id: OTP-5961 Aux Id: seq10198 </p>
+ </item>
+ <item>
+ <p>[http,server] Changed some actions taken if config data
+ in httpd services was faulty.</p>
+ <p>Own Id: OTP-5962 Aux Id: seq10198 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>inets 4.7.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] It was possible to read arbitrary files on
+ server by prepending ././ and ../../ in front of the file
+ name.</p>
+ <p>Own Id: OTP-5938</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.7</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] Handling of undefined file times (e.g.
+ modification time: the mtime field on the file_info
+ record).</p>
+ <p>Own Id: OTP-5865 Aux Id: OTP-5844 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server]It is now possible to set the wanted timeout
+ for the server to setup a request connection. A new
+ syntax for inets.config is provided in the users guide
+ documentation. This syntax also allows to set tracing of
+ the server for debug purposes.</p>
+ <p>Own Id: OTP-5913 Aux Id: seq10198 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.6.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] Had earlier forgot to convert a value in
+ entity_body to a binary.</p>
+ <p>Own Id: OTP-5796</p>
+ </item>
+ <item>
+ <p>[http,server] Now application checks whether the
+ necessary directives under directive Directory exist.</p>
+ <p>Own Id: OTP-5821</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.6.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http, client] If an Ipv4-mapped ipv6 address is used the
+ client now falls back on ipv4.</p>
+ <p>Own Id: OTP-5773 Aux Id: OTP-5765, OTP-5764 </p>
+ </item>
+ <item>
+ <p>[http,server] Content-length may got a too low value,
+ causing loss of data in clients.</p>
+ <p>Own Id: OTP-5775 Aux Id: seq10110 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[http, client] The verbose mode prints what was sent and
+ received during a request. Added a <c>verbose</c> option
+ that can be used by <c>http:set_options/1</c></p>
+ <p>Own Id: OTP-5766</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.6</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] - Improvement of error handling if
+ something goes wrong while handling the option list in
+ ftp:open/[1,2,3].</p>
+ <p>Own Id: OTP-5711</p>
+ </item>
+ <item>
+ <p>[ftp, client] - Error when parsing a multiple FTP
+ response line. The last line in a multiple response must
+ be the response code followed by a space. A server may
+ have intermediate lines that start with the response code
+ even if this is not recommended. The parsing missed to
+ make sure that that space was present in what it
+ considered to be the last line.</p>
+ <p>Own Id: OTP-5712</p>
+ </item>
+ <item>
+ <p>[http, client] - The HTTP client will now retry a
+ pipelined request that was unsuccessful due to the fact
+ that the server unexpectedly closed the pipeline
+ connection.</p>
+ <p>Own Id: OTP-5728</p>
+ </item>
+ <item>
+ <p>[http, server, esi] - Under some circumstances mod_esi
+ would send a corrupted content-length header.</p>
+ <p>Own Id: OTP-5735</p>
+ </item>
+ <item>
+ <p>[http, server, get] - Removed debug printout which
+ caused a confusing "Socket closed"-printout at high
+ load.</p>
+ <p>Own Id: OTP-5762 Aux Id: seq10101 </p>
+ </item>
+ <item>
+ <p>FTP: a data connection setup to the ftp server that
+ failed caused a crash of the client. Now it is handled
+ smoothly.</p>
+ <p>Own Id: OTP-5738</p>
+ </item>
+ <item>
+ <p>[ftp] If host name is a ipv4 tuple ftp erroneous tries to
+ connect as a ipv6 address with the ipv4 address.</p>
+ <p>Own Id: OTP-5764</p>
+ </item>
+ <item>
+ <p>[ftp] Handles connect to ipv6/ipv4 address differently
+ according to a change in <c>inet:getaddr</c>.</p>
+ <p>Own Id: OTP-5765</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[http, server] - The HTTP request handling was remoduled
+ to have a more straight forward error-handling. And the
+ internal debug strategy was changed to use tracing
+ instead of debug macros, which means we do not have to
+ write special debug code.</p>
+ <p>Own Id: OTP-5729</p>
+ </item>
+ <item>
+ <p>ftp:ls towards different ftp servers resulted in
+ different return results. E.g. the solaris 9 default
+ server caused <c>{ok,[]}</c> while older servers caused
+ <c>{error,epath}</c> as the result. For backwards
+ compatibility the behaviour has been changed to the old
+ result.</p>
+ <p>Own Id: OTP-5731</p>
+ </item>
+ <item>
+ <p>[http, server] - The documentation for the HTTP server
+ has been partly rewritten and very restructured too
+ provide a better overall picture. Lots of information
+ provided by "semi manual pages" has been moved to the
+ Users Guide.</p>
+ <p>Own Id: OTP-5752</p>
+ </item>
+ <item>
+ <p>FTP: verbose mode now also prints what the client sends
+ on the control channel.</p>
+ <p>Own Id: OTP-5753</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.5.4</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] - Timing related issues could sometimes
+ cause the ftp response to be delayed.</p>
+ <p>Own Id: OTP-5705 Aux Id: seq10055 </p>
+ </item>
+ <item>
+ <p>[http, server, esi] - The dispatching of the post body to
+ the esi callback function was broken.</p>
+ <p>Own Id: OTP-5706</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.5.3</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] - The FTP error code 550 was handled in an
+ unexpected way. Some earlier versions of inets had a
+ workaround for this in ftp:recv_bin/2 that was eliminated
+ during restructuring of the ftp module while implementing
+ ipv6 capabilities. The problem is now fixed.</p>
+ <p>Own Id: OTP-5682 Aux Id: seq10048 </p>
+ </item>
+ <item>
+ <p>[http, client] Post request with a body in binary format
+ failed as length was used instead of size.</p>
+ <p>Own Id: OTP-5686</p>
+ </item>
+ <item>
+ <p>[ftp, client] - For some FTP commands the FTP server will
+ send more than one reply on the FTP control channel. In
+ the case of a fast FTP server the client would sometimes
+ wrongly disregard the second answer as trailing garbage
+ attached to the first reply.</p>
+ <p>Own Id: OTP-5690 Aux Id: seq10055 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] - A new option {progress, {CBmodule,
+ CBFunction, InitProgressTerm} has been added to allow
+ users to create things such as progress bars in there
+ GUI's. The option affects ftp:send/[3,4] and
+ ftp:recv/[3,4].</p>
+ <p>Own Id: OTP-5680</p>
+ </item>
+ <item>
+ <p>[http, client] - Added new API function http:request/1</p>
+ <p>Own Id: OTP-5691</p>
+ </item>
+ <item>
+ <p>[httpd, server] - mod_cgi is implemented according to
+ CGI-1.1 RFC 3875, an early implementation was based on
+ some draft that is not totally compliant to the RFC.
+ Documentation was updated. Also some code was
+ restructured to facilitate testing and maintenance of the
+ server.</p>
+ <p>Own Id: OTP-5694</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.5.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] Calling ftp:recv/2 twice on the same
+ connection failed due to that the last message on the
+ ctrl channel was not appropriately taken care of. This
+ could potentially cause a problem for any operation
+ performed on the same connection where there had
+ previously been an ftp:recv/2 call. Also, in some cases,
+ when the process tries to close the data connection, it
+ does not take into account that the data connection may
+ actually not have been established.</p>
+ <p>Own Id: OTP-5662 Aux Id: seq10004, seq9988 </p>
+ </item>
+ <item>
+ <p>[ftp, client] Enhanced error handling, mainly so the ftp
+ client behaves gracefully when the user does strange
+ things such as violate the user API.</p>
+ <p>Own Id: OTP-5665</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[ftp, client] Added open option: mode.Deprecates
+ function force_active/1.</p>
+ <p>Own Id: OTP-5663</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.5.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http, server] The server did not handle the config
+ directive BindAddress value "*" properly.
+ When creating the option list for the listen call,
+ everything beside the atom undefined (if BindAddress
+ was never given) and an 4-tuple (e.g. BindAddress
+ value is 192.168.0.30) was incorrectly assumed to be
+ an ipv6 address.
+ For undefined (no BindAddress), Inets attempts to
+ figure out if it is running on a ipv6-machine, and if
+ so, add the inet6 option when calling listen. The
+ same approach should be used when BindAddress is
+ assigned the value "*".</p>
+ <p>Own Id: OTP-5642</p>
+ </item>
+ <item>
+ <p>Some data doesn't pass through http_base_64:decode/1 correctly.
+ The decoding routine fails whenever a 4-character group of the
+ encoding ends with "9" or "99". If it ends with 99, two bytes
+ will be lost in the decode routine. If it ends with a single 9,
+ one byte will be lost in the decode.</p>
+ <p>Own Id: OTP-5635 Aux Id: seq9971</p>
+ </item>
+ <item>
+ <p>[http, server,esi] Web server does not handle status-code
+ returned by an esi function. I.e. the esi-function
+ can no longer control the status code.</p>
+ <p>Own Id: OTP-5648 Aux Id: seq9982</p>
+ </item>
+ <item>
+ <p>[http, server,esi] Corrected header format. First character
+ was lower case, and there where no space after the ":"
+ character, example: content-length:0. Now, first character
+ was upper case, and a space after the ":" character,
+ example: Content-Length: 0 (To preserve
+ backward compatibility with the de-facto standard as the
+ new way does not break the HTTP standard!)</p>
+ <p>Own Id: OTP-5649 Aux Id: seq9982</p>
+ </item>
+ <item>
+ <p>[http, server, cgi] Parsing of the status header field could
+ cause a crash.</p>
+ <p>Own Id: OTP-5650 Aux Id: seq9982</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.5</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The internal design of using blocking gen_tcp:recv with a
+ timeout and retries resulted in code that was hard to get
+ a good overview of, and ultimate led to situations where
+ the client got the wrong answer or no answer at all. The
+ errors where many times very timing dependent and mainly
+ effected the chunk-related functions, so if you where
+ lucky you probably would not have noticed. The internal
+ design was changed to use gen_tcp active once semantics.
+ The API is not effected except for the function
+ ftp:quote/2 which now returns a list of strings (ftp
+ result lines) where the line endings "\\r\
+ " has been
+ removed. This was the original intention for the return
+ value of ftp:quote/2 but it was non trivial to make a
+ good such solution with the old design and a compromise
+ was made.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5623</p>
+ </item>
+ <item>
+ <p>The new implementation of pipelining in inets-4.1 alas
+ was slightly broken and unfortunately not caught by the
+ test suite that apparently needs some additions. The
+ result was that requests that ought to have been
+ pipelined where not, this has now been fixed.</p>
+ <p>Own Id: OTP-5624</p>
+ </item>
+ <item>
+ <p>When using the latest esi interface with the callback
+ interface of arity 3, HTTP Content-Type headers where
+ ignored, this due to a subtle difference between this
+ interface and the old one in how they viewed HTTP
+ delimiters.</p>
+ <p>Own Id: OTP-5627</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The HTTP server now supports ipv6 in the case that the
+ underlying mechanisms also do so. (ssl does not yet
+ support ipv6.)</p>
+ <p>Own Id: OTP-5141</p>
+ </item>
+ <item>
+ <p>The FTP client now supports ipv6 in the case that the
+ underlying mechanisms also do so.</p>
+ <p>Own Id: OTP-5142</p>
+ </item>
+ <item>
+ <p>An option was added to disable the ipv6 support in the
+ HTTP client. This to provide a workaround possibility for
+ buggy ipv6-stacks.</p>
+ <p>Own Id: OTP-5625 Aux Id: seq9872</p>
+ </item>
+ <item>
+ <p>When generating dynamic HTTP response bodies the the
+ default content-type is now set to "text/html" instead of
+ "text/plain" which is more intuitive.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5626</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.4.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Wrapper function http_transport:accept/3 did
+ error-handling that it should not do because only the
+ caller of the wrapper can determine what action to take.
+ So timeouts where handled twice, once in http_transport
+ and once in httpd_acceptor. Clean up of the wrapper
+ module http_transport changed the action of the wrapper
+ module and made the unwanted behavior noticeable in in
+ OTP error logs. And now the unwanted error handling has
+ been removed. The cleanup helped us find bad code but
+ alas it also generates a lot of log printouts that are
+ quite disturbing to the user of the HTTP-server.</p>
+ <p>Own Id: OTP-5549 Aux Id: seq9851 </p>
+ </item>
+ <item>
+ <p>In the rewrite for 4.4 some mod_esi-environment values
+ where mistaken for ordinary header values and where
+ incorrectly transformed to strings. They are now atoms
+ again.</p>
+ <p>Own Id: OTP-5551 Aux Id: seq9854 </p>
+ </item>
+ <item>
+ <p>The HTTP server now handles "GET /\\r\
+ \\r\
+ " as well as
+ "GET / \\r\
+ \\r\
+ ". According to the RFC the whitespace is
+ not needed.</p>
+ <p>Own Id: OTP-5552 Aux Id: seq8426 </p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The ftp client now supports passive mode. Actually the
+ ftp client will always try to use passive mode and if it
+ fails it will use active mode instead. It is also
+ possible to force the ftp-client to use active mode, if
+ that is desired, by calling ftp:force_active/1 this way
+ you can get the old behavior.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5148</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.4</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The server did not handle HTTP-0.9 messages with an
+ implicit version.</p>
+ <p>Own Id: OTP-5513</p>
+ </item>
+ <item>
+ <p>An internal server timeout killed the request handling
+ process without sending a message back to the client. As
+ this timeout only affects a single request it has been
+ set to infinity (if the main server process dies the
+ request handling process will also die and the client
+ will receive an error). This might make a client that
+ does not use a timeout hang for a longer period of time,
+ but that is an expected behavior!</p>
+ <p>Own Id: OTP-5514 Aux Id: seq9806 </p>
+ </item>
+ <item>
+ <p>That a third party closes the http servers accept socket
+ is recoverable for inets, hence inets will only produce
+ an info report as there was no error in Inets but
+ measures where taken to avoid failure due to errors
+ elsewhere.</p>
+ <p>Own Id: OTP-5516 Aux Id: seq9806 </p>
+ </item>
+ <item>
+ <p>The HTTP client proxy settings where ignored. Bug
+ introduced in inets-4.3.</p>
+ <p>Own Id: OTP-5517</p>
+ </item>
+ <item>
+ <p>Inets only sent the "WWW-Authenticate" header at the
+ first attempt to get a page, if the user supplied the
+ wrong user/password combination the header was not sent
+ again. This forces the user to kill the browser entirely
+ after a failed login attempt, before the user may try to
+ login again. Inets now always send the authentication
+ header.</p>
+ <p>Own Id: OTP-5521</p>
+ </item>
+ <item>
+ <p>A major rewrite of big parts of the HTTP server code was
+ performed. There where many things that did not work
+ satisfactory. Cgi script handling can never have worked
+ properly and the cases when it did sort of work, a big
+ unnecessary delay was enforced. Headers where not always
+ treated as expected and HTTP version handling did not
+ work, all responses where sent as version HTTP/1.1 no
+ matter what.</p>
+ <p>Own Id: OTP-5537</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.3.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>When further testing the functionality of https requests
+ that goes through a proxy. We realised that alas this can
+ not currently be supported as it requires features from
+ the ssl implementation that is not currently available.
+ So for now an error message will be returned when trying
+ to use this functionality.</p>
+ <p>Own Id: OTP-5453</p>
+ </item>
+ <item>
+ <p>When trying to get a url from a server that does not
+ exist the client hanged instead of returning an error
+ message. Bug introduced in inets-4.3.</p>
+ <p>Own Id: OTP-5454</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.3</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Tunneling of SSL through a proxy has now been
+ implemented. However due to lack of test sites this has only
+ partially been verified, it is likely that there will
+ have to be future improvements in this area.</p>
+ <p>Own Id: OTP-5443</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The pipeline timeout was changed to be zero by default to
+ avoid that people by accident would create connection
+ processes that never dies and eats up the socket
+ resources.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5442</p>
+ </item>
+ <item>
+ <p>Altered the way spawn_link is used in mod_esi to avoid
+ getting, in this scenario unwanted error reports, from
+ spawn_link. (The behavior of spawn_link was altered in a
+ not backwards compatible way.)</p>
+ <p>Own Id: OTP-5444</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.2.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Sometimes EWS modules where called with an Info record
+ where the peername field was {-1, "unknown"}. This could
+ happen when a client was making a lot of requests which
+ it discards before they where answered by the server. The
+ server now ignores such requests and does not call the
+ EWS modules in this case.</p>
+ <p>Own Id: OTP-5380 Aux Id: seq9739 </p>
+ </item>
+ <item>
+ <p>The HTTP-server now returns the 408 status code upon a
+ request timeout as expected instead of the previous
+ faulty behavior of sending a 500 status code.</p>
+ <p>Own Id: OTP-5409</p>
+ </item>
+ <item>
+ <p>The content length was put in to the HTTP-headers as an
+ integer instead of as a string.</p>
+ <p>Own Id: OTP-5410</p>
+ </item>
+ <item>
+ <p>It was wrongly presumed that code:priv_dir would always
+ be writable due to how the test-server works. The
+ directory is now a configuration parameter in the
+ inets-application configuration file. Failing to
+ configure it will result in that all cookies are treated
+ as session cookies.</p>
+ <p>Own Id: OTP-5411</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>An undocumented beta version of tftp is included.</p>
+ <p>Own Id: OTP-5419</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>When sending a request through a proxy the absolute URI
+ must be used.</p>
+ <p>Own Id: OTP-5368</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Basic support for cookies was implemented. Later some
+ more functions to inspect cookies may be added.</p>
+ <p>Own Id: OTP-5331</p>
+ </item>
+ <item>
+ <p>A top tftp supervisor was added in preparation for adding
+ a tftp service in a future Inets release.</p>
+ <p>Own Id: OTP-5379</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The URI check that disables relative links that goes
+ outside the server-root still missed a few cases, in
+ spite of the improvement in OTP-5140.</p>
+ <p>Own Id: OTP-5249</p>
+ </item>
+ <item>
+ <p>The http client pipelining implementation has been
+ rewritten as the old implementation was too optimistic
+ about when to pipeline. In the process of doing this also
+ the error handling was improved, better clean up is
+ performed when the request handling process terminates
+ and better handling of the case that the httpc_manager
+ process dies and is restarted.</p>
+ <p>Own Id: OTP-5303</p>
+ </item>
+ <item>
+ <p>Improved handling of status codes 30X and 50X.</p>
+ <p>Own Id: OTP-5309</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The Inets supervision tree has been reorganized to create
+ a better balance between the Inets services. Preferably
+ they should not effect each other. The ftp service has
+ also been included in the Inets supervision tree, it was
+ for reasons unknown, not included before.</p>
+ <p>Own Id: OTP-5188</p>
+ </item>
+ <item>
+ <p>The service concept in Inets is now better documented.</p>
+ <p>Own Id: OTP-5189</p>
+ </item>
+ <item>
+ <p>The Inets shutdown times have proven to be too short
+ under some circumstances, as a heavy load, therefore they
+ have been prolonged.</p>
+ <p>Own Id: OTP-5261 Aux Id: seq9624</p>
+ </item>
+ <item>
+ <p>Options for automatic redirection and pipelining is now
+ available in the http client API.</p>
+ <p>Own Id: OTP-5304</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.0.1</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>A programming error could cause a badmatch in the
+ http-client when the http response was chunk decoded.</p>
+ <p>Own Id: OTP-5101</p>
+ </item>
+ <item>
+ <p>The parsing of HTTP messages was missing a base case.
+ This caused unexpected behavior when the separator CR and
+ LF where received in different tcp packets.</p>
+ <p>Own Id: OTP-5239</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 4.0</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>When receiving a status 100 code, the client should only
+ respond by sending the message body, if the client sent
+ an expect header in the first place. Failing to do so may
+ result in that the server receives the body twice.</p>
+ <p>Own Id: OTP-4848</p>
+ </item>
+ <item>
+ <p>mod_get now also handles http version HTTP/0.9</p>
+ <p>Own Id: OTP-4935 Aux Id: seq8426 </p>
+ </item>
+ <item>
+ <p>"Last-modified" field was incorrectly set to local time
+ with the tag GMT, it is now corrected so that the time
+ reflected is in fact GMT.</p>
+ <p>Own Id: OTP-4936</p>
+ </item>
+ <item>
+ <p>The client will only add a host-field to the request if
+ there is not one already present.</p>
+ <p>Own Id: OTP-4984</p>
+ </item>
+ <item>
+ <p>The Inets application tries to be compatible with
+ Apache. To be more compatible the option
+ 'MaxKeepAliveRequest' is renamed 'MaxKeepAliveRequests'.
+ The old name is kept for backward compatibility.</p>
+ <p>Own Id: OTP-5024</p>
+ </item>
+ <item>
+ <p>Changing the base 64 decoding to not accept invalid
+ input, uncovered a logical error in mod_security.erl An
+ already decoded string was sent as input to decode. In
+ this case, as it so happened, the two errors worked
+ together creating the illusion that everything was right.
+ This has now been corrected.</p>
+ <p>Own Id: OTP-5083</p>
+ </item>
+ <item>
+ <p>URLs where not properly scrutinised for relative paths. A
+ malicious user could exploit this to read files outside
+ the document root. This is no longer the case.</p>
+ <p>Own Id: OTP-5140</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>A HTTP 1.1 client is officially included in Inets. It is
+ loosely based on the previously unsupported code
+ contributed by Johan Blom. In this first version only the
+ most basic HTTP functionality is supported. The user API
+ has been changed.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5047</p>
+ </item>
+ <item>
+ <p>Fixed erroneous link in documentation.</p>
+ <p>Own Id: OTP-5089 Aux Id: seq8887 </p>
+ </item>
+ <item>
+ <p>Added the function quote/2 that lets you send an
+ arbitrary FTP command to the FTP client.</p>
+ <p>Own Id: OTP-5099 Aux Id: seq8961 </p>
+ </item>
+ <item>
+ <p>Started integration of the HTTP client and server code
+ too facilitate maintenance and further development.</p>
+ <p>Own Id: OTP-5110</p>
+ </item>
+ <item>
+ <p>Due to several possibilities to interpret the ftp
+ standard some newer ftp-servers have interpreted the
+ standard in such a way that the documented return value
+ of ftp:nlist/2 does not always match the actual return
+ value. Some extra checks have now been added to ensure
+ the documented return value. This will also result in
+ that ftp:nlist is not bug compatible in the case that
+ nlist is given a filename instead of a directory it will
+ now return an error instead of {ok, FileName}.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5165</p>
+ </item>
+ <item>
+ <p>Created a Users Guide for Inets. Earlier there where some
+ fake manual pages and information was scattered
+ everywhere and hard to find.</p>
+ <p>Own Id: OTP-5180</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.10</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] - When calling httpd:restart there was a file
+ descriptor and ets table leek due to the fact that the
+ semantics of the function restart is not restart but
+ reload. This is solved in inets-4.7.12 and this special
+ inets-3.0.10 release is intended for old systems only.</p>
+ <p>Own Id: OTP-6579 Aux Id: OTP-6573, seq10607 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.9</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[http,server] Illegal hexadecimal code in URL was not
+ handled. The validation of URI:s are therefore updated.</p>
+ <p>Own Id: OTP-6078 Aux Id: seq10306 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.8 </title>
+ <p>Special version featuring some small 4.1 improvements
+ without enforcing the big changes of the 4.X releases. </p>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The URI check that disables relative links that goes
+ outside the server-root missed a few cases.</p>
+ <p>Own Id: OTP-5249</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The inets shutdown times have proven to be too short
+ under some circumstances, as a heavy load, therefore they
+ have been prolonged.</p>
+ <p>Own Id: OTP-5261 Aux Id: seq9624 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.7</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[httpd] Fixed a number of transfer-encoding problems.</p>
+ <p>First part of the data received from a CGI-script was sent
+ as chunked even if the client was HTTP/1.0.</p>
+ <p>Introduced new directive
+ (<c>DisableChunkedTransferEncodingSend</c>) to turn off usage
+ of chunked transfer-encoding (when sending) since it appear's
+ some browser's have problems handling this. This applies
+ if the client is HTTP/1.1.</p>
+ <p>(Own Id: OTP-4806)
+ <br></br>
+ Aux Id: Seq 8150</p>
+ </item>
+ <item>
+ <p>[httpc] HTTP client reformats some URLs (e.g. containing %20,
+ space).</p>
+ <p>Updated client from sowap.sf.net as of 2003-09-08.</p>
+ <p>Johan Blom of Mobile Arts AB</p>
+ <p>(Own Id: OTP-4807)</p>
+ </item>
+ <item>
+ <p>[httpd] In module mod_browser, malformed search for parsed
+ header, user-agent.</p>
+ <p>Also added new os and browser</p>
+ <p>(Own Id: OTP-4808)</p>
+ </item>
+ <item>
+ <p>[ftp] FTP client doesn't notice when disk is full.</p>
+ <p>(Own Id: OTP-4822)
+ <br></br>
+ Aux Id: Seq 8175</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.6</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>On Windows the <c>ftp:ls</c> function sometimes exits.</p>
+ <p>Workaround for a problem that seems to happen only on Windows
+ when calling the ls function. Closing an already closed socket
+ will result in enotsock returned which will result in an exit.</p>
+ <p>(Own Id: OTP-4770)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.5</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Web server does not handle econnaborted accept result.</p>
+ <p>This results in an unnecessary acceptor process restart.</p>
+ <p>(Own Id: OTP-4732)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.4</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>ESI callback generates broken HTTP.</p>
+ <p>This was a problem for (at least) Netscape 4.75. It worked for
+ Mozilla 1.4a (on Solaris 8) and rumor has it that it also worked
+ for IE.</p>
+ <p> <br></br>
+ Sean Hinde</p>
+ <p>(Own Id: OTP-4696)</p>
+ </item>
+ <item>
+ <p>Log-size values ignored for security- and error disk-logs
+ (SecurityDiskLogSize and ErrorDiskLogSize in mod_disk_log).
+ Instead the TransferDiskLogSize was used.
+ <br></br>
+ Thomas Lange</p>
+ <p>(Own Id: OTP-4659)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.3</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>HTTP client called undefined function in HTTP server
+ (httpd_response:send_status/3).</p>
+ <p>(Own Id: OTP-4628)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.2</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>HTTP client <em>now</em> updated to jnets-0.1.
+ <br></br>
+ Auther: Johan Blom of Mobile Arts AB.</p>
+ <p>(Own Id: OTP-4588)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0.1</title>
+
+ <section>
+ <title>Improvements and new features</title>
+ <list type="bulleted">
+ <item>
+ <p>FTP client now supports chunked receive. Proposal of Luke Gorrie
+ provided inspiration but not algorithm.</p>
+ <p>(Own Id: OTP-4549)</p>
+ </item>
+ <item>
+ <p>HTTP client updated to jnets-0.1, now supporting proxy.
+ <br></br>
+ Auther: Johan Blom of Mobile Arts AB.</p>
+ <p>(Own Id: OTP-4552)</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Body length calculation incorrect.</p>
+ <p>(Own Id: OTP-4548)</p>
+ <p>(Aux Id: OTP-4207, Seq 7209)</p>
+ </item>
+ <item>
+ <p>HTTP-request with a BODY length longer than 0 does not work.</p>
+ <p>(Own Id: OTP-4550)</p>
+ <p>(Aux Id: Seq 7653)</p>
+ </item>
+ <item>
+ <p>Calculation of remaining chunk size incorrect.</p>
+ <p>(Own Id: OTP-4551)</p>
+ </item>
+ <item>
+ <p>Wrong module name used when attempting to stop the security
+ server (mod_sec_server instead of mod_security_server).</p>
+ <p>(Own Id: OTP-4556)</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Inets 3.0</title>
+
+ <section>
+ <title>Improvements and new features</title>
+ <list type="bulleted">
+ <item>Added HTTP client to the application.
+ <br></br>
+ Auther: Johan Blom of Mobile Arts AB.</item>
+ <item>FTP: More info in exit reason when socket operation fails.
+ <br></br>
+ (Own Id: OTP-4429)</item>
+ <item>Make install targets corrected (INSTALL_SCRIPT is used instead
+ of INSTALL_PROGRAMS for scripts).
+ <br></br>
+ (Own Id: OTP-4428)</item>
+ <item>In inets, mod_cgi crashes when a directory is protected for
+ a group or for a user and we try to execute a CGI script
+ inside this protected directory.
+ <br></br>
+ Guillaume Bongenaar.
+ <br></br>
+ (Own Id: OTP-4416)</item>
+ <item>Removed crypto application dependency.
+ <br></br>
+ Matthias Lang
+ <br></br>
+ (Own Id: OTP-4417)</item>
+ <item>Use the same read algorithm for socket type ssl as is used
+ for ip_comm. As of version 2.3.5 of the ssl application it
+ is possible to use socket option {active, once}, so the same
+ algorithm can be used for both ip_comm and ssl.
+ <br></br>
+ (Own Id: OTP-4374)
+ <br></br>
+ (Aux Id: Seq 7417)</item>
+ <item>Added inets test suite to the release. Including the
+ lightweight inets test server.</item>
+ <item>Incorrectly formated disk log entries.
+ <em>term_to_binary</em> was (incorrectly) used for the
+ external format.
+ <br></br>
+ Own Id: OTP-4228
+ <br></br>
+ Aux Id: Seq 7239</item>
+ <item>Adding verbosity printouts to 'catch' cgi problems on some
+ platforms.</item>
+ <item>
+ <p>Updated to handle HTTP/1.1.</p>
+ <list type="bulleted">
+ <item>Persistent connections are now default for http/1.1 clients</item>
+ <item>Module <c>mod_esi</c> can send data to the client in chunks.</item>
+ <item>Updated configuration directives <em>KeepAlive</em></item>
+ <item>
+ <p>New configuration directives:</p>
+ <list type="bulleted">
+ <item><em>MaxKeepAliveRequest</em></item>
+ <item><em>ErlScriptTimeout</em></item>
+ <item><em>ErlScriptNoCache</em></item>
+ <item><em>ScriptTimeout</em></item>
+ <item><em>ScriptNoCache</em></item>
+ </list>
+ </item>
+ <item>New functions in httpd_utility to ease the development of
+ http/1.1 complaint modules.</item>
+ <item>Record mod has a new field absolute_uri.</item>
+ <item>All header field names in parsed_header is in lowercase.</item>
+ <item>httpd handles chunked requests.</item>
+ <item>New module <em>mod_range</em> that handles range-requests.</item>
+ <item>New module <em>mod_responsecontrol</em> that controls how
+ the request will be handled the due to the If-Modified,
+ If-Match and If-Range http header fields.</item>
+ </list>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>POST requests not properly handled.
+ <br></br>
+ (Own Id: OTP-4409)
+ <br></br>
+ (Aux Id: Seq 7485)</item>
+ <item>
+ <p>Change in the inets API.
+ <br></br>
+ (Own Id: OTP-4408)
+ <br></br>
+ (Aux Id: Seq 7485)</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p></p>
+ </item>
+ <item>When opening the disk log (mod_disk_log), an open attempt
+ is made without a size option. If the file exist, then it is
+ opened. If the file does not exist, then another attempt is
+ made, this time with the size option.
+ <br></br>
+ (Own Id: OTP-4281)
+ <br></br>
+ (Aux Id: Seq 7312)</item>
+ <item>Changing of disk log format fails. Restart of webserver after
+ change of disk log format (DiskLogFormat) fails with
+ <em>arg_mismatch</em>.
+ <br></br>
+ (Own Id: OTP-4231)
+ <br></br>
+ (Aux Id: Seq 7244)</item>
+ </list>
+ </section>
+ </section>
+</chapter>
+
+
diff --git a/lib/inets/doc/src/part.xml b/lib/inets/doc/src/part.xml
new file mode 100644
index 0000000000..36955df6b3
--- /dev/null
+++ b/lib/inets/doc/src/part.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets User's Guide</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <docno></docno>
+ <date>2002-09-17</date>
+ <rev>A</rev>
+ <file>part.sgml</file>
+ </header>
+ <description>
+ <p>The <em>Inets Application </em> provides a set of Internet
+ related services. Currently supported are a HTTP client, a HTTP
+ server a FTP client and a TFTP client and server.</p>
+ </description>
+ <xi:include href="inets_services.xml"/>
+ <xi:include href="ftp_client.xml"/>
+ <xi:include href="http_client.xml"/>
+ <xi:include href="http_server.xml"/>
+</part>
+
+
diff --git a/lib/inets/doc/src/part_notes.xml b/lib/inets/doc/src/part_notes.xml
new file mode 100644
index 0000000000..21f464318b
--- /dev/null
+++ b/lib/inets/doc/src/part_notes.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2002</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets</title>
+ <prepared>Micael Karlberg</prepared>
+ <docno></docno>
+ <date>2002-02-28</date>
+ <rev>3.0</rev>
+ <file>part_notes.sgml</file>
+ </header>
+ <description>
+ <p>A set of services such as a Web server and a ftp client etc. </p>
+ <p>For information about older versions see
+ <url href="part_notes_history_frame.html">release notes history</url>.</p>
+ </description>
+ <xi:include file="notes.xml"/>
+</part>
+
+
diff --git a/lib/inets/doc/src/part_notes_history.xml b/lib/inets/doc/src/part_notes_history.xml
new file mode 100644
index 0000000000..3c1e6f5232
--- /dev/null
+++ b/lib/inets/doc/src/part_notes_history.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets</title>
+ <prepared>Micael Karlberg</prepared>
+ <docno></docno>
+ <date>2002-02-28</date>
+ <rev>3.0</rev>
+ <file>part_notes.sgml</file>
+ </header>
+ <include file="notes_history"></include>
+</part>
+
+
diff --git a/lib/inets/doc/src/ref_man.gif b/lib/inets/doc/src/ref_man.gif
new file mode 100644
index 0000000000..b13c4efd53
--- /dev/null
+++ b/lib/inets/doc/src/ref_man.gif
Binary files differ
diff --git a/lib/inets/doc/src/ref_man.xml b/lib/inets/doc/src/ref_man.xml
new file mode 100644
index 0000000000..7ec2c041c8
--- /dev/null
+++ b/lib/inets/doc/src/ref_man.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Inets Reference Manual</title>
+ <prepared>Joakim Greben&ouml;</prepared>
+ <docno></docno>
+ <date>1997-07-16</date>
+ <rev>2.1</rev>
+ <file>ref_man.xml</file>
+ </header>
+ <description>
+ <p>Inets is a container for Internet clients and
+ servers. Currently a FTP client, a HTTP client and server, and
+ a tftp client and server has been incorporated in Inets.</p>
+ </description>
+ <xi:include href="inets.xml"/>
+ <xi:include href="ftp.xml"/>
+ <xi:include href="tftp.xml"/>
+ <xi:include href="http.xml"/>
+ <xi:include href="httpd.xml"/>
+ <xi:include href="httpd_conf.xml"/>
+ <xi:include href="httpd_socket.xml"/>
+ <xi:include href="httpd_util.xml"/>
+ <xi:include href="mod_alias.xml"/>
+ <xi:include href="mod_auth.xml"/>
+ <xi:include href="mod_esi.xml"/>
+ <xi:include href="mod_security.xml"/>
+</application>
+
+
+
+
+
diff --git a/lib/inets/doc/src/summary.html.src b/lib/inets/doc/src/summary.html.src
new file mode 100644
index 0000000000..17637a0787
--- /dev/null
+++ b/lib/inets/doc/src/summary.html.src
@@ -0,0 +1 @@
+A set of services such as a web server and a ftp client etc \ No newline at end of file
diff --git a/lib/inets/doc/src/tftp.xml b/lib/inets/doc/src/tftp.xml
new file mode 100644
index 0000000000..96d6ae0dd5
--- /dev/null
+++ b/lib/inets/doc/src/tftp.xml
@@ -0,0 +1,637 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2006</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>tftp</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>tftp</module>
+ <modulesummary>Trivial FTP</modulesummary>
+ <description>
+ <p>This is a complete implementation of the following IETF standards:</p>
+ <list type="bulleted">
+ <item>RFC 1350, The TFTP Protocol (revision 2).</item>
+ <item>RFC 2347, TFTP Option Extension.</item>
+ <item>RFC 2348, TFTP Blocksize Option.</item>
+ <item>RFC 2349, TFTP Timeout Interval and Transfer Size Options.</item>
+ </list>
+ <p>The only feature that not is implemented in this release is
+ the "netascii" transfer mode.</p>
+ <p>The <seealso marker="#start/1">start/1</seealso> function starts
+ a daemon process which listens for UDP packets on a port. When it
+ receives a request for read or write it spawns a temporary server
+ process which handles the actual transfer of the file.</p>
+ <p>On the client side
+ the <seealso marker="#read_file/3">read_file/3</seealso>
+ and <seealso marker="#write_file/3">write_file/3</seealso>
+ functions spawns a temporary client process which establishes
+ contact with a TFTP daemon and performs the actual transfer of
+ the file.</p>
+ <p><c>tftp</c> uses a callback module to handle the actual file
+ transfer. Two such callback modules are provided,
+ <c>tftp_binary</c> and <c>tftp_file</c>. See
+ <seealso marker="#read_file/3">read_file/3</seealso> and
+ <seealso marker="#write_file/3">write_file/3</seealso> for
+ more information about these. The user can also implement own
+ callback modules, see <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso> below. A callback module provided by
+ the user is registered using the <c>callback</c> option, see
+ <seealso marker="#options">DATA TYPES</seealso> below.</p>
+ </description>
+
+ <section>
+ <title>TFTP SERVER SERVICE START/STOP </title>
+
+ <p>A TFTP server can be configured to start statically when starting
+ the Inets application. Alternatively it can be started dynamically
+ (when Inets already is started) by calling the Inets application API
+ <c>inets:start(tftpd, ServiceConfig)</c>, or
+ <c>inets:start(tftpd, ServiceConfig, How)</c>,
+ see <seealso marker="inets">inets(3)</seealso> for details.
+ The <c>ServiceConfig</c> for TFTP is described below in
+ the <seealso marker="#options">COMMON DATA TYPES</seealso>
+ section.</p>
+
+ <p>The TFTP server can be stopped using <c>inets:stop(tftpd, Pid)</c>,
+ see <seealso marker="inets">inets(3)</seealso> for details.</p>
+
+ <p>The TPFT client is of such a temporary nature that it is not
+ handled as a service in the Inets service framework.</p>
+
+ </section>
+
+ <section>
+ <marker id="options"></marker>
+ <title>COMMON DATA TYPES</title>
+ <pre>
+ ServiceConfig = Options
+ Options = [option()]
+ option() -- see below
+ </pre>
+ <p>Most of the options are common for both the client and the server
+ side, but some of them differs a little. Here are the available
+ options:</p>
+ <taglist>
+ <tag><c>{debug, Level}</c></tag>
+ <item>
+ <p><c>Level = none | error | warning | brief | normal | verbose | all</c></p>
+ <p>Controls the level of debug printouts. The default is
+ <c>none</c>.</p>
+ </item>
+ <tag><c>{host, Host}</c></tag>
+ <item>
+ <p><c>Host = hostname()</c> see
+ <seealso marker="kernel:inet">inet(3)</seealso></p>
+ <p>The name or IP address of the host where the TFTP daemon
+ resides. This option is only used by the client.</p>
+ </item>
+ <tag><c>{port, Port}</c></tag>
+ <item>
+ <p><c>Port = int()</c></p>
+ <p>The TFTP port where the daemon listens. It defaults to
+ the standardized number 69. On the server side it may
+ sometimes make sense to set it to 0, which means that
+ the daemon just will pick a free port (which one is
+ returned by the <c>info/1</c> function).</p>
+ <p>If a socket has somehow already has been connected, the
+ {udp, [{fd, integer()}]} option can be used to pass the
+ open file descriptor to gen_udp. This can be automated
+ a bit by using a command line argument stating the
+ prebound file descriptor number. For example, if the
+ Port is 69 and the file descriptor 22 has been opened by
+ setuid_socket_wrap. Then the command line argument
+ "-tftpd_69 22" will trigger the prebound file
+ descriptor 22 to be used instead of opening port 69.
+ The UDP option {udp, [{fd, 22}]} automatically be added.
+ See init:get_argument/ about command line arguments and
+ gen_udp:open/2 about UDP options.</p>
+ </item>
+ <tag><c>{port_policy, Policy}</c></tag>
+ <item>
+ <p><c>Policy = random | Port | {range, MinPort, MaxPort}</c> <br></br>
+<c>Port = MinPort = MaxPort = int()</c></p>
+ <p>Policy for the selection of the temporary port which is used
+ by the server/client during the file transfer. It defaults to
+ <c>random</c> which is the standardized policy. With this
+ policy a randomized free port used. A single port or a range
+ of ports can be useful if the protocol should pass through a
+ firewall.</p>
+ </item>
+ <tag><c>{udp, Options}</c></tag>
+ <item>
+ <p><c>Options = [Opt]</c> see
+ <seealso marker="kernel:gen_udp#open/1">gen_udp:open/2</seealso></p>
+ </item>
+ <tag><c>{use_tsize, Bool}</c></tag>
+ <item>
+ <p><c>Bool = bool()</c></p>
+ <p>Flag for automated usage of the <c>tsize</c> option. With
+ this set to true, the <c>write_file/3</c> client will
+ determine the filesize and send it to the server as
+ the standardized <c>tsize</c> option. A <c>read_file/3</c>
+ client will just acquire filesize from the server by sending
+ a zero <c>tsize</c>.</p>
+ </item>
+ <tag><c>{max_tsize, MaxTsize}</c></tag>
+ <item>
+ <p><c>MaxTsize = int() | infinity</c></p>
+ <p>Threshold for the maximal filesize in bytes. The transfer
+ will be aborted if the limit is exceeded. It defaults to
+ <c>infinity</c>.</p>
+ </item>
+ <tag><c>{max_conn, MaxConn}</c></tag>
+ <item>
+ <p><c>MaxConn = int() | infinity</c></p>
+ <p>Threshold for the maximal number of active connections.
+ The daemon will reject the setup of new connections if
+ the limit is exceeded. It defaults to <c>infinity</c>.</p>
+ </item>
+ <tag><c>{TftpKey, TftpVal}</c></tag>
+ <item>
+ <p><c>TftpKey = string()</c> <br></br>
+<c>TftpVal = string()</c></p>
+ <p>The name and value of a TFTP option.</p>
+ </item>
+ <tag><c>{reject, Feature}</c></tag>
+ <item>
+ <p><c>Feature = Mode | TftpKey</c> <br></br>
+<c>&nbsp;Mode = read | write</c> <br></br>
+<c>&nbsp;TftpKey = string()</c></p>
+ <p>Control which features that should be rejected. This is
+ mostly useful for the server as it may restrict usage of
+ certain TFTP options or read/write access.</p>
+ </item>
+ <tag><c>{callback, {RegExp, Module, State}}</c></tag>
+ <item>
+ <p><c>RegExp = string()</c> <br></br>
+<c>Module = atom()</c> <br></br>
+<c>State = term()</c></p>
+ <p>Registration of a callback module. When a file is to be
+ transferred, its local filename will be matched to the regular
+ expressions of the registered callbacks. The first matching
+ callback will be used the during the transfer. See
+ <seealso marker="#read_file/3">read_file/3</seealso> and
+ <seealso marker="#write_file/3">write_file/3</seealso>.
+ </p>
+ <p>The callback module must implement the <c>tftp</c> behavior,
+ <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>.</p>
+ </item>
+
+ <tag><c>{logger, Module}</c></tag>
+ <item>
+ <p><c>Module = module()()</c></p>
+
+ <p>Callback module for customized logging of error, warning and
+ info messages. >The callback module must implement the
+ <c>tftp_logger</c> behavior,
+ <seealso marker="#tftp_logger">LOGGER FUNCTIONS</seealso>.
+ The default module is <c>tftp_logger</c>.</p>
+ </item>
+
+ <tag><c>{max_retries, MaxRetries}</c></tag>
+ <item>
+ <p><c>MaxRetries = int()</c></p>
+
+ <p>Threshold for the maximal number of retries. By default
+ the server/client will try to resend a message up to
+ <c>5</c> times when the timeout expires.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>start(Options) -> {ok, Pid} | {error, Reason}</name>
+ <fsummary>Start a daemon process</fsummary>
+ <type>
+ <v>Options = [option()]</v>
+ <v>Pid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Starts a daemon process which listens for udp packets on a
+ port. When it receives a request for read or write it spawns
+ a temporary server process which handles the actual transfer
+ of the (virtual) file.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name>
+ <fsummary>Read a (virtual) file from a TFTP server</fsummary>
+ <type>
+ <v>RemoteFilename = string()</v>
+ <v>LocalFilename = binary | string()</v>
+ <v>Options = [option()]</v>
+ <v>LastCallbackState = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Reads a (virtual) file <c>RemoteFilename</c> from a TFTP
+ server.</p>
+ <p>If <c>LocalFilename</c> is the atom <c>binary</c>,
+ <c>tftp_binary</c> is used as callback module. It concatenates
+ all transferred blocks and returns them as one single binary
+ in <c>LastCallbackState</c>.</p>
+ <p>If <c>LocalFilename</c> is a string and there are no
+ registered callback modules, <c>tftp_file</c> is used as
+ callback module. It writes each transferred block to the file
+ named <c>LocalFilename</c> and returns the number of
+ transferred bytes in <c>LastCallbackState</c>.</p>
+ <p>If <c>LocalFilename</c> is a string and there are registered
+ callback modules, <c>LocalFilename</c> is tested against
+ the regexps of these and the callback module corresponding to
+ the first match is used, or an error tuple is returned if no
+ matching regexp is found.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name>
+ <fsummary>Write a (virtual) file to a TFTP server</fsummary>
+ <type>
+ <v>RemoteFilename = string()</v>
+ <v>LocalFilename = binary() | string()</v>
+ <v>Options = [option()]</v>
+ <v>LastCallbackState = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Writes a (virtual) file <c>RemoteFilename</c> to a TFTP
+ server.</p>
+ <p>If <c>LocalFilename</c> is a binary, <c>tftp_binary</c> is
+ used as callback module. The binary is transferred block by
+ block and the number of transferred bytes is returned in
+ <c>LastCallbackState</c>.</p>
+ <p>If <c>LocalFilename</c> is a string and there are no
+ registered callback modules, <c>tftp_file</c> is used as
+ callback module. It reads the file named <c>LocalFilename</c>
+ block by block and returns the number of transferred bytes
+ in <c>LastCallbackState</c>.</p>
+ <p>If <c>LocalFilename</c> is a string and there are registered
+ callback modules, <c>LocalFilename</c> is tested against
+ the regexps of these and the callback module corresponding to
+ the first match is used, or an error tuple is returned if no
+ matching regexp is found.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>info(daemons) -> [{Pid, Options}]</name>
+ <fsummary>Return information about all daemons</fsummary>
+ <type>
+ <v>Pid = [pid()()]</v>
+ <v>Options = [option()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Returns info about all TFTP daemon processes.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>info(servers) -> [{Pid, Options}]</name>
+ <fsummary>Return information about all servers</fsummary>
+ <type>
+ <v>Pid = [pid()()]</v>
+ <v>Options = [option()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Returns info about all TFTP server processes.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>info(Pid) -> {ok, Options} | {error, Reason}</name>
+ <fsummary>Return information about a daemon, server or client process</fsummary>
+ <type>
+ <v>Options = [option()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Returns info about a TFTP daemon, server or client process.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>change_config(daemons, Options) -> [{Pid, Result}]</name>
+ <fsummary>Changes config for all daemons
+ </fsummary>
+ <type>
+ <v>Options = [option()]</v>
+ <v>Pid = pid()</v>
+ <v>Result = ok | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Changes config for all TFTP daemon processes
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>change_config(servers, Options) -> [{Pid, Result}]</name>
+ <fsummary>Changes config for all servers
+ </fsummary>
+ <type>
+ <v>Options = [option()]</v>
+ <v>Pid = pid()</v>
+ <v>Result = ok | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Changes config for all TFTP server processes
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>change_config(Pid, Options) -> Result</name>
+ <fsummary>Changes config for a TFTP daemon, server or client process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Options = [option()]</v>
+ <v>Result = ok | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Changes config for a TFTP daemon, server or client process</p>
+ </desc>
+ </func>
+ <func>
+ <name>start() -> ok | {error, Reason}</name>
+ <fsummary>Start the Inets application</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Starts the Inets application.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="tftp_callback"></marker>
+ <title>CALLBACK FUNCTIONS</title>
+ <p>A <c>tftp</c> callback module should be implemented as a
+ <c>tftp</c> behavior and export the functions listed below.</p>
+ <p>On the server side the callback interaction starts with a call to
+ <c>open/5</c> with the registered initial callback state.
+ <c>open/5</c> is expected to open the (virtual) file. Then either
+ the <c>read/1</c> or <c>write/2</c> functions are invoked
+ repeatedly, once per transferred block. At each function call
+ the state returned from the previous call is obtained. When
+ the last block has been encountered the <c>read/1</c> or
+ <c>write/2</c> functions is expected to close the (virtual) file
+ and return its last state. The <c>abort/3</c> function is only
+ used in error situations. <c>prepare/5</c> is not used on
+ the server side.</p>
+ <p>On the client side the callback interaction is the same, but it
+ starts and ends a bit differently. It starts with a call to
+ <c>prepare/5</c> with the same arguments as <c>open/5</c> takes.
+ <c>prepare/5</c> is expected to validate the TFTP options,
+ suggested by the user and return the subset of them that it
+ accepts. Then the options is sent to the server which will perform
+ the same TFTP option negotiation procedure. The options that are
+ accepted by the server are forwarded to the <c>open/5</c> function
+ on the client side. On the client side the <c>open/5</c> function
+ must accept all option as is or reject the transfer. Then
+ the callback interaction follows the same pattern as described
+ above for the server side. When the last block is encountered in
+ <c>read/1</c> or <c>write/2</c> the returned state is forwarded to
+ the user and returned from <c>read_file</c>/3 or
+ <c>write_file/3</c>.</p>
+
+ <p> If a callback (which performs the file access
+ in the TFTP server) takes too long time (more than
+ the double TFTP timeout), the server will abort the
+ connection and send an error reply to the client.
+ This implies that the server will release resources
+ attached to the connection faster than before. The
+ server simply assumes that the client has given
+ up.</p>
+
+ <p>If the TFTP server receives yet another request from
+ the same client (same host and port) while it
+ already has an active connection to the client, it
+ will simply ignore the new request if the request is
+ equal with the first one (same filename and options).
+ This implies that the (new) client will be served
+ by the already ongoing connection on the server
+ side. By not setting up yet another connection, in
+ parallel with the ongoing one, the server will
+ consumer lesser resources.
+ </p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>prepare(Peer, Access, Filename, Mode, SuggestedOptions, InitialState) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name>
+ <fsummary>Prepare to open a file on the client side</fsummary>
+ <type>
+ <v>Peer = {PeerType, PeerHost, PeerPort}</v>
+ <v>PeerType = inet | inet6</v>
+ <v>PeerHost = ip_address()</v>
+ <v>PeerPort = integer()</v>
+ <v>Access = read | write</v>
+ <v>Filename = string()</v>
+ <v>Mode = string()</v>
+ <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v>
+ <v>&nbsp;Key = Value = string()</v>
+ <v>InitialState = [] | [{root_dir, string()}]</v>
+ <v>NewState = term()</v>
+ <v>Code = undef | enoent | eacces | enospc</v>
+ <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
+ <v>&nbsp;&nbsp;| int()</v>
+ <v>Text = string()</v>
+ </type>
+ <desc>
+ <p>Prepares to open a file on the client side.</p>
+ <p>No new options may be added, but the ones that are present in
+ <c>SuggestedOptions</c> may be omitted or replaced with new
+ values in <c>AcceptedOptions</c>.</p>
+ <p>Will be followed by a call to <c>open/4</c> before any
+ read/write access is performed. <c>AcceptedOptions</c> is
+ sent to the server which replies with those options that it
+ accepts. These will be forwarded to <c>open/4</c> as
+ <c>SuggestedOptions</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>open(Peer, Access, Filename, Mode, SuggestedOptions, State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name>
+ <fsummary>Open a file for read or write access</fsummary>
+ <type>
+ <v>Peer = {PeerType, PeerHost, PeerPort}</v>
+ <v>PeerType = inet | inet6</v>
+ <v>PeerHost = ip_address()</v>
+ <v>PeerPort = integer()</v>
+ <v>Access = read | write</v>
+ <v>Filename = string()</v>
+ <v>Mode = string()</v>
+ <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v>
+ <v>&nbsp;Key = Value = string()</v>
+ <v>State = InitialState | term()</v>
+ <v>&nbsp;InitialState = [] | [{root_dir, string()}]</v>
+ <v>NewState = term()</v>
+ <v>Code = undef | enoent | eacces | enospc</v>
+ <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
+ <v>&nbsp;&nbsp;| int()</v>
+ <v>Text = string()</v>
+ </type>
+ <desc>
+ <p>Opens a file for read or write access.</p>
+ <p>On the client side where the <c>open/5</c> call has been
+ preceded by a call to <c>prepare/5</c>, all options must be
+ accepted or rejected.</p>
+ <p>On the server side, where there is no preceding
+ <c>prepare/5</c> call, no new options may be added, but
+ the ones that are present in <c>SuggestedOptions</c> may be
+ omitted or replaced with new values in <c>AcceptedOptions</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} | {error, {Code, Text}}</name>
+ <fsummary>Read a chunk from the file</fsummary>
+ <type>
+ <v>State = NewState = term()</v>
+ <v>Bin = binary()</v>
+ <v>FileSize = int()</v>
+ <v>Code = undef | enoent | eacces | enospc</v>
+ <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
+ <v>&nbsp;&nbsp;| int()</v>
+ <v>Text = string()</v>
+ </type>
+ <desc>
+ <p>Read a chunk from the file.</p>
+ <p>The callback function is expected to close
+ the file when the last file chunk is
+ encountered. When an error is encountered
+ the callback function is expected to clean
+ up after the aborted file transfer, such as
+ closing open file descriptors etc. In both
+ cases there will be no more calls to any of
+ the callback functions.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write(Bin, State) -> {more, NewState} | {last, FileSize} | {error, {Code, Text}}</name>
+ <fsummary>Write a chunk to the file</fsummary>
+ <type>
+ <v>Bin = binary()</v>
+ <v>State = NewState = term()</v>
+ <v>FileSize = int()</v>
+ <v>Code = undef | enoent | eacces | enospc</v>
+ <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
+ <v>&nbsp;&nbsp;| int()</v>
+ <v>Text = string()</v>
+ </type>
+ <desc>
+ <p>Write a chunk to the file.</p>
+ <p>The callback function is expected to close
+ the file when the last file chunk is
+ encountered. When an error is encountered
+ the callback function is expected to clean
+ up after the aborted file transfer, such as
+ closing open file descriptors etc. In both
+ cases there will be no more calls to any of
+ the callback functions.</p>
+ </desc>
+ </func>
+ <func>
+ <name>abort(Code, Text, State) -> ok</name>
+ <fsummary>Abort the file transfer</fsummary>
+ <type>
+ <v>Code = undef | enoent | eacces | enospc</v>
+ <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
+ <v>&nbsp;&nbsp;| int()</v>
+ <v>Text = string()</v>
+ <v>State = term()</v>
+ </type>
+ <desc>
+ <p>Invoked when the file transfer is aborted.</p>
+ <p>The callback function is expected to clean
+ up its used resources after the aborted file
+ transfer, such as closing open file
+ descriptors etc. The function will not be
+ invoked if any of the other callback
+ functions returns an error, as it is
+ expected that they already have cleaned up
+ the necessary resources. It will however be
+ invoked if the functions fails (crashes).</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="tftp_logger"></marker>
+ <title>LOGGER FUNCTIONS</title>
+
+ <p>A <c>tftp_logger</c> callback module should be implemented as a
+ <c>tftp_logger</c> behavior and export the functions listed below.</p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>error_msg(Format, Data) -> ok | exit(Reason)</name>
+ <fsummary>Log an error message</fsummary>
+ <type>
+ <v>Format = string()</v>
+ <v>Data = [term()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Log an error message. See <c>error_logger:error_msg/2 for details.</c> </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>warning_msg(Format, Data) -> ok | exit(Reason)</name>
+ <fsummary>Log an error message</fsummary>
+ <type>
+ <v>Format = string()</v>
+ <v>Data = [term()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Log a warning message. See <c>error_logger:warning_msg/2 for details.</c> </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>info_msg(Format, Data) -> ok | exit(Reason)</name>
+ <fsummary>Log an error message</fsummary>
+ <type>
+ <v>Format = string()</v>
+ <v>Data = [term()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Log an info message. See <c>error_logger:info_msg/2 for details.</c> </p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+
+
diff --git a/lib/inets/doc/src/user_guide.gif b/lib/inets/doc/src/user_guide.gif
new file mode 100644
index 0000000000..e6275a803d
--- /dev/null
+++ b/lib/inets/doc/src/user_guide.gif
Binary files differ
diff --git a/lib/inets/doc/src/warning.gif b/lib/inets/doc/src/warning.gif
new file mode 100644
index 0000000000..96af52360e
--- /dev/null
+++ b/lib/inets/doc/src/warning.gif
Binary files differ