diff options
Diffstat (limited to 'lib/inets/doc/src')
36 files changed, 9338 insertions, 0 deletions
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 Binary files differnew file mode 100644 index 0000000000..94b3868792 --- /dev/null +++ b/lib/inets/doc/src/book.gif 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ö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 <CRLF> or + <NL>. 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 </Limit> 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 <Limit POST GET HEAD> +\011 order allow deny +\011 require group group1 +\011 allow from 123.145.244.5 +\011 </Limit> + </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<!--#command tag1="value1" tag2="value2" --> + </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ö</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ö</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ö</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 Binary files differnew file mode 100644 index 0000000000..64968ae68a --- /dev/null +++ b/lib/inets/doc/src/inets.gif 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 Binary files differnew file mode 100644 index 0000000000..90e1d2130d --- /dev/null +++ b/lib/inets/doc/src/marting_tankar.sdw diff --git a/lib/inets/doc/src/min_head.gif b/lib/inets/doc/src/min_head.gif Binary files differnew file mode 100644 index 0000000000..67948a6378 --- /dev/null +++ b/lib/inets/doc/src/min_head.gif 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ö</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ö</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} <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} <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ö</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. <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. <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() <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 Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/inets/doc/src/note.gif diff --git a/lib/inets/doc/src/notes.gif b/lib/inets/doc/src/notes.gif Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/inets/doc/src/notes.gif 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>[email protected]</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>[email protected]</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>[email protected]</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 <descriptor>) + 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>[email protected]</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>[email protected]</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>[email protected]</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 Binary files differnew file mode 100644 index 0000000000..b13c4efd53 --- /dev/null +++ b/lib/inets/doc/src/ref_man.gif 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ö</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> Mode = read | write</c> <br></br> +<c> 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> Key = Value = string()</v> + <v>InitialState = [] | [{root_dir, string()}]</v> + <v>NewState = term()</v> + <v>Code = undef | enoent | eacces | enospc</v> + <v> | badop | eexist | baduser | badopt</v> + <v> | 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> Key = Value = string()</v> + <v>State = InitialState | term()</v> + <v> InitialState = [] | [{root_dir, string()}]</v> + <v>NewState = term()</v> + <v>Code = undef | enoent | eacces | enospc</v> + <v> | badop | eexist | baduser | badopt</v> + <v> | 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> | badop | eexist | baduser | badopt</v> + <v> | 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> | badop | eexist | baduser | badopt</v> + <v> | 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> | badop | eexist | baduser | badopt</v> + <v> | 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 Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/inets/doc/src/user_guide.gif diff --git a/lib/inets/doc/src/warning.gif b/lib/inets/doc/src/warning.gif Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/inets/doc/src/warning.gif |
