From b8f7153606e51517e3d361ebbd1b2a4ff08bb7dd Mon Sep 17 00:00:00 2001 From: Lars Thorsen Date: Thu, 10 Dec 2015 10:06:04 +0100 Subject: [inets] Align documentation to DTD --- lib/inets/doc/src/http_server.xml | 19 +-- lib/inets/doc/src/http_uri.xml | 10 +- lib/inets/doc/src/httpc.xml | 10 +- lib/inets/doc/src/httpd.xml | 245 ++++++++++++++------------------------ lib/inets/doc/src/notes.xml | 64 +++++----- lib/inets/doc/src/tftp.xml | 21 +--- 6 files changed, 136 insertions(+), 233 deletions(-) (limited to 'lib/inets/doc') diff --git a/lib/inets/doc/src/http_server.xml b/lib/inets/doc/src/http_server.xml index 4b6d64fc8f..5adae933cd 100644 --- a/lib/inets/doc/src/http_server.xml +++ b/lib/inets/doc/src/http_server.xml @@ -4,7 +4,7 @@
- 20042013 + 20042015 Ericsson AB. All Rights Reserved. @@ -21,18 +21,7 @@ limitations under the License. - HTTP server - Ingela Anderton Andin - - - - - - - http_server.xml - -
@@ -356,9 +345,9 @@ UserName:Password
- CGI Version 1.1, - <url href="http://www.ietf.org/rfc/rfc3875.txt">RFC 3875</url> -

The module mod_cgi enables execution of CGI scripts + CGI Version 1.1, RFC 3875 +

The module mod_cgi enables execution of + CGI scripts on the server. A file matching the definition of a ScriptAlias config directive is treated as a CGI script. A CGI script is executed by the server and its output is returned to diff --git a/lib/inets/doc/src/http_uri.xml b/lib/inets/doc/src/http_uri.xml index 64e6c7a6cc..8e0301c520 100644 --- a/lib/inets/doc/src/http_uri.xml +++ b/lib/inets/doc/src/http_uri.xml @@ -4,7 +4,7 @@

- 20122013 + 20122015 Ericsson AB. All Rights Reserved. @@ -142,14 +142,14 @@

If the fragment option is true, the URI fragment is returned as part of the parsing result, otherwise it is ignored.

-

Scheme validation fun is to be defined as follows: +

Scheme validation fun is to be defined as follows:

- + fun(SchemeStr :: string()) -> valid | {error, Reason :: term()}. - + - It is called before scheme string gets converted into scheme atom and +

It is called before scheme string gets converted into scheme atom and thus possible atom leak could be prevented

diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 31e44f405c..ca9b268a03 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -4,7 +4,7 @@
- 20042013 + 20042015 Ericsson AB. All Rights Reserved. @@ -554,8 +554,8 @@ IpDesc = string() Example: "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). - proxy defaults to {undefined, []}, + "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP address). + proxy defaults to {undefined, []}, that is, no proxy is configured and https_proxy defaults to the value of proxy. MaxSessions = integer() @@ -597,8 +597,8 @@ for details. socket_opts() = [socket_opt()] The options are appended to the socket options used by the - client. - These are the default values when a new request handler + client. + These are the default values when a new request handler is started (for the initial connect). They are passed directly to the underlying transport (gen_tcp or SSL) without verification. diff --git a/lib/inets/doc/src/httpd.xml b/lib/inets/doc/src/httpd.xml index 0fc3cb1ce7..62b92b8356 100644 --- a/lib/inets/doc/src/httpd.xml +++ b/lib/inets/doc/src/httpd.xml @@ -30,13 +30,14 @@ httpd.sgml
httpd - An implementation of an HTTP - 1.1 compliant web server, as defined in RFC 2616 + + HTTP server API -

This module provides the HTTP server start options, some administrative - functions, and specifies the Erlang web server callback - API.

+

An implementation of an HTTP 1.1 compliant web server, as defined in + RFC 2616. + Provides web server start options, administrative functions, and + an Erlang callback API.
@@ -78,8 +79,7 @@ list.

- - {proplist_file, path()} + {proplist_file, path()}

If this property is defined, Inets expects to find all other properties defined in this file. The @@ -87,8 +87,7 @@ properties.

 - - {file, path()} + {file, path()}

If this property is defined, Inets expects to find all other properties defined in this file, which uses Apache-like @@ -121,8 +120,7 @@

Mandatory Properties

- - {port, integer()} + {port, integer()}

The port that the HTTP server listen to. If zero is specified as port, an arbitrary available port @@ -130,22 +128,19 @@ determine which port was picked.

 - - {server_name, string()} + {server_name, string()}

The name of your server, normally a fully qualified domain name.

 - - {server_root, path()} + {server_root, path()}

Defines the home directory of the server, where log files, and so on, can be stored. Relative paths specified in other properties refer to this directory.

 - - {document_root, path()} + {document_root, path()}

Defines the top directory for the documents that are available on the HTTP server.

@@ -155,15 +150,13 @@

Communication Properties

- - {bind_address, ip_address() | hostname() | any} + {bind_address, ip_address() | hostname() | any}

Default is any. any is denoted * in the Apache-like configuration file.

 - - {profile, atom()} + {profile, atom()}

Used together with bind_address and port to uniquely identify @@ -176,8 +169,7 @@

- - {socket_type, ip_comm | {ip_comm, Config::proplist()} | {essl, Config::proplist()}} + {socket_type, ip_comm | {ip_comm, Config::proplist()} | {essl, Config::proplist()}}

For ip_comm configuration options, see gen_tcp:listen/2, some options @@ -187,15 +179,13 @@

Default is ip_comm.

 - - {ipfamily, inet | inet6} + {ipfamily, inet | inet6}

Default is inet, legacy option inet6fb4 no longer makes sense and will be translated to inet.

 - - {minimum_bytes_per_second, integer()} + {minimum_bytes_per_second, integer()}

If given, sets a minimum of bytes per second value for connections.

If the value is unreached, the socket closes for that connection.

@@ -206,8 +196,7 @@

Erlang Web Server API Modules

- - {modules, [atom()]} + {modules, [atom()]}

Defines which modules the HTTP server uses when handling requests. Default is [mod_alias, mod_auth, mod_esi, @@ -224,60 +213,52 @@

Limit properties

- - {customize, atom()} + {customize, atom()}

A callback module to customize the inets HTTP servers behaviour see httpd_custom_api

- - {disable_chunked_transfer_encoding_send, boolean()} + {disable_chunked_transfer_encoding_send, boolean()}

Allows you to disable chunked transfer-encoding when sending a response to an HTTP/1.1 client. Default is false.

 - - {keep_alive, boolean()} + {keep_alive, boolean()}

Instructs the server whether to use persistent connections when the client claims to be HTTP/1.1 compliant. Default is true.

 - - {keep_alive_timeout, integer()} + {keep_alive_timeout, integer()}

The number of seconds the server waits for a subsequent request from the client before closing the connection. Default is 150.

 - - {max_body_size, integer()} + {max_body_size, integer()}

Limits the size of the message body of an HTTP request. Default is no limit.

 - - {max_clients, integer()} + {max_clients, integer()}

Limits the number of simultaneous requests that can be supported. Default is 150.

 - - {max_header_size, integer()} + {max_header_size, integer()}

Limits the size of the message header of an HTTP request. Default is 10240.

 - - {max_content_length, integer()} + {max_content_length, integer()}

Maximum content-length in an incoming request, in bytes. Requests with content larger than this are answered with status 413. @@ -285,15 +266,13 @@

- - {max_uri_size, integer()} + {max_uri_size, integer()}

Limits the size of the HTTP request URI. Default is no limit.

 - - {max_keep_alive_request, integer()} + {max_keep_alive_request, integer()}

The number of requests that a client can do on one connection. When the server has responded to the number of @@ -306,8 +285,7 @@

Administrative Properties

- - {mime_types, [{MimeType, Extension}] | path()} + {mime_types, [{MimeType, Extension}] | path()}

MimeType = string() and Extension = string(). Files delivered to the client are MIME typed according to RFC @@ -323,24 +301,21 @@ text/plain asc txt

Default is [{"html","text/html"},{"htm","text/html"}].

 - - {mime_type, string()} + {mime_type, string()}

When the server is asked to provide a document type that cannot be determined by the MIME Type Settings, the server uses this default type.

 - - {server_admin, string()} + {server_admin, string()}

Defines the email-address of the server administrator to be included in any error messages returned by the server.

 - - {server_tokens, none|prod|major|minor|minimal|os|full|{private, string()}} + {server_tokens, none|prod|major|minor|minimal|os|full|{private, string()}}

Defines the look of the value of the server header.

Example: Assuming the version of Inets is 5.8.1, @@ -367,8 +342,7 @@ text/plain asc txt

By default, the value is as before, that is, minimal.

 - - {log_format, common | combined} + {log_format, common | combined}

Defines if access logs are to be written according to the common log format or the extended common log format. @@ -411,8 +385,7 @@ text/plain asc txt

- - {error_log_format, pretty | compact} + {error_log_format, pretty | compact}

Default is pretty. If the error log is meant to be read directly by a human, pretty is the best option.

@@ -434,60 +407,57 @@ text/plain asc txt

URL Aliasing Properties - Requires mod_alias

- - {alias, {Alias, RealName}} + {alias, {Alias, RealName}}

Alias = string() and RealName = string(). alias allows documents to be stored in the local file system instead of the document_root location. URLs with a path beginning with url-path is mapped to local files beginning with - directory-filename, for example: + directory-filename, for example:

{alias, {"/image", "/ftp/pub/image"}} - Access to http://your.server.org/image/foo.gif would refer to +

Access to http://your.server.org/image/foo.gif would refer to the file /ftp/pub/image/foo.gif.

 - - {re_write, {Re, Replacement}} + {re_write, {Re, Replacement}}

Re = string() and Replacement = string(). re_write allows documents to be stored in the local file system instead of the document_root location. URLs are rewritten by re:replace/3 to produce a path in the local file-system, - for example: + for example:

{re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}} - Access to http://your.server.org/~bob/foo.gif would refer to +

Access to http://your.server.org/~bob/foo.gif would refer to the file /home/bob/public/foo.gif. In an Apache-like configuration file, Re is separated from Replacement with one single space, and as expected backslashes do not need to be backslash escaped, the - same example would become: + same example would become:

ReWrite ^/[~]([^/]+)(.*)$ /home/\1/public\2 - Beware of trailing space in Replacement to be used. +

Beware of trailing space in Replacement to be used. If you must have a space in Re, use, for example, the character encoding \040, see re(3).

 - - {directory_index, [string()]} + {directory_index, [string()]}

directory_index 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 can be given, in which case the server - returns the first it finds, for example: + returns the first it finds, for example:

{directory_index, ["index.hml", "welcome.html"]} - Access to http://your.server.org/docs/ would return +

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 does not exist.

@@ -497,38 +467,35 @@ text/plain asc txt

CGI Properties - Requires mod_cgi

- - {script_alias, {Alias, RealName}} + {script_alias, {Alias, RealName}}

Alias = string() and RealName = string(). Have the same behavior as property alias, except that they also mark 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: + scripts beginning with directory-filename, for example:

{script_alias, {"/cgi-bin/", "/web/cgi-bin/"}} - Access to http://your.server.org/cgi-bin/foo would cause +

Access to http://your.server.org/cgi-bin/foo would cause the server to run the script /web/cgi-bin/foo.

 - - {script_re_write, {Re, Replacement}} + {script_re_write, {Re, Replacement}}

Re = string() and Replacement = string(). Have the same behavior as property re_write, except that they also mark 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: + scripts beginning with directory-filename, for example:

{script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}} - Access to http://your.server.org/cgi-bin/17/foo would cause +

Access to http://your.server.org/cgi-bin/17/foo would cause the server to run the script /web/17/cgi-bin/foo.

 - - {script_nocache, boolean()} + {script_nocache, boolean()}

If script_nocache is set to true, the HTTP server by default adds the header fields necessary to prevent proxies from @@ -536,8 +503,7 @@ text/plain asc txt Default to false.

 - - {script_timeout, integer()} + {script_timeout, integer()}

The time in seconds the web server waits between each chunk of data from the script. If the CGI script does not deliver @@ -545,8 +511,7 @@ text/plain asc txt closed. Default is 15.

 - - {action, {MimeType, CgiScript}} - requires mod_action + {action, {MimeType, CgiScript}} - requires mod_action

MimeType = string() and CgiScript = string(). action adds an action activating a CGI script @@ -559,8 +524,7 @@ text/plain asc txt {action, {"text/plain", "/cgi-bin/log_and_deliver_text"}} - - {script, {Method, CgiScript}} - requires mod_action + {script, {Method, CgiScript}} - requires mod_action

Method = string() and CgiScript = string(). script adds an action activating a CGI script @@ -579,17 +543,16 @@ text/plain asc txt

ESI Properties - Requires mod_esi

- - {erl_script_alias, {URLPath, [AllowedModule]}} + {erl_script_alias, {URLPath, [AllowedModule]}}

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: + and function, for example:

{erl_script_alias, {"/cgi-bin/example", [httpd_example]}} - A request to +

A request to http://your.server.org/cgi-bin/example/httpd_example:yahoo would refer to httpd_example:yahoo/3 or, if that does not exist, httpd_example:yahoo/2 and @@ -597,8 +560,7 @@ text/plain asc txt not be allowed to execute.

 - - {erl_script_nocache, boolean()} + {erl_script_nocache, boolean()}

If erl_script_nocache is set to true, the server adds HTTP header fields preventing proxies from caching the @@ -607,8 +569,7 @@ text/plain asc txt Default is false.

 - - {erl_script_timeout, integer()} + {erl_script_timeout, integer()}

If erl_script_timeout sets the time in seconds the server waits between each chunk of data to be delivered through @@ -616,8 +577,7 @@ text/plain asc txt for scripts that use the erl scheme.

 - - {eval_script_alias, {URLPath, [AllowedModule]}} + {eval_script_alias, {URLPath, [AllowedModule]}}

URLPath = string() and AllowedModule = atom(). Same as erl_script_alias but for scripts @@ -629,24 +589,21 @@ text/plain asc txt

Log Properties - Requires mod_log

- - {error_log, path()} + {error_log, path()}

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.

 - - {security_log, path()} + {security_log, path()}

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.

 - - {transfer_log, path()} + {transfer_log, path()}

Defines the filename of the access log file to be used to log incoming requests. If the filename does not begin with a @@ -657,8 +614,7 @@ text/plain asc txt

Disk Log Properties - Requires mod_disk_log

- - {disk_log_format, internal | external} + {disk_log_format, internal | external}

Defines the file format of the log files. See disk_log for details. If the internal file format is used, the @@ -668,16 +624,14 @@ text/plain asc txt external.

 - - {error_disk_log, path()} + {error_disk_log, path()}

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.

 - - {error_disk_log_size, {MaxBytes, MaxFiles}} + {error_disk_log_size, {MaxBytes, MaxFiles}}

MaxBytes = integer() and MaxFiles = integer(). Defines the properties of the (disk_log(3)) error log @@ -686,8 +640,7 @@ text/plain asc txt used before the first file is truncated and reused.

 - - {security_disk_log, path()} + {security_disk_log, path()}

Defines the filename of the (disk_log(3)) access log file logging incoming security events, that is, authenticated @@ -695,8 +648,7 @@ text/plain asc txt is assumed to be relative to the server_root.

 - - {security_disk_log_size, {MaxBytes, MaxFiles}} + {security_disk_log_size, {MaxBytes, MaxFiles}}

MaxBytes = integer() and MaxFiles = integer(). Defines the properties of the disk_log(3) access log @@ -705,8 +657,7 @@ text/plain asc txt used before the first file is truncated and reused.

 - - {transfer_disk_log, path()} + {transfer_disk_log, path()}

Defines the filename of the (disk_log(3)) access log file logging incoming requests. If the filename does not begin @@ -714,8 +665,7 @@ text/plain asc txt server_root.

 - - {transfer_disk_log_size, {MaxBytes, MaxFiles}} + {transfer_disk_log_size, {MaxBytes, MaxFiles}}

MaxBytes = integer() and MaxFiles = integer(). Defines the properties of the disk_log(3) access log @@ -735,32 +685,29 @@ text/plain asc txt

The properties for directories are as follows:

- - {allow_from, all | [RegxpHostString]} + {allow_from, all | [RegxpHostString]}

Defines a set of hosts to be granted access to a - given directory, for example: + given directory, for example:

{allow_from, ["123.34.56.11", "150.100.23"]} - The host 123.34.56.11 and all machines on the 150.100.23 +

The host 123.34.56.11 and all machines on the 150.100.23 subnet are allowed access.

 - - {deny_from, all | [RegxpHostString]} + {deny_from, all | [RegxpHostString]}

Defines a set of hosts - to be denied access to a given directory, for example: + to be denied access to a given directory, for example:

{deny_from, ["123.34.56.11", "150.100.23"]} - The host 123.34.56.11 and all machines on the 150.100.23 +

The host 123.34.56.11 and all machines on the 150.100.23 subnet are not allowed access.

 - - {auth_type, plain | dets | mnesia} + {auth_type, plain | dets | mnesia}

Sets the type of authentication database that is used for the directory. The key difference between the different methods is @@ -770,8 +717,7 @@ text/plain asc txt configuration files.

 - - {auth_user_file, path()} + {auth_user_file, path()}

Sets the name of a file containing the list of users and passwords for user authentication. The filename can be either @@ -795,8 +741,7 @@ text/plain asc txt clients can download it.

 - - {auth_group_file, path()} + {auth_group_file, path()}

Sets the name of a file containing the list of user groups for user authentication. The filename can be either @@ -818,16 +763,14 @@ text/plain asc txt can download it.

 - - {auth_name, string()} + {auth_name, string()}

Sets the name of the authorization realm (auth-domain) for a directory. This string informs the client about which username and password to use.

 - - {auth_access_password, string()} + {auth_access_password, string()}

If set to other than "NoPassword", the password is required for all API calls. If the password is set to "DummyPassword", the @@ -837,15 +780,13 @@ text/plain asc txt text in the configuration file.

 - - {require_user, [string()]} + {require_user, [string()]}

Defines users to grant access to a given directory using a secret password.

 - - {require_group, [string()]} + {require_group, [string()]}

Defines users to grant access to a given directory using a secret password.

@@ -856,8 +797,7 @@ text/plain asc txt

Htaccess Authentication Properties - Requires mod_htaccess

- - {access_files, [path()]} + {access_files, [path()]}

Specifies the filenames that are used for access files. When a request comes, every directory in the path @@ -877,16 +817,14 @@ text/plain asc txt

The properties for the security directories are as follows:

- - {data_file, path()} + {data_file, path()}

Name of the security data file. The filename can either be absolute or relative to the server_root. This file is used to store persistent data for module mod_security.

 - - {max_retries, integer()} + {max_retries, integer()}

Specifies the maximum number of attempts to authenticate a user before the user is blocked out. If a user @@ -898,16 +836,14 @@ text/plain asc txt Default is 3. Can be set to infinity.

 - - {block_time, integer()} + {block_time, integer()}

Specifies the number of minutes a user is blocked. After this timehas passed, the user automatically regains access. Default is 60.

 - - {fail_expire_time, integer()} + {fail_expire_time, integer()}

Specifies the number of minutes a failed user authentication is remembered. If a user authenticates after this @@ -916,8 +852,7 @@ text/plain asc txt Default is 30.

 - - {auth_timeout, integer()} + {auth_timeout, integer()} Specifies the number of seconds a successful user authentication is remembered. After this time has passed, the diff --git a/lib/inets/doc/src/notes.xml b/lib/inets/doc/src/notes.xml index 8c4fdfdf70..7ebb3ddffa 100644 --- a/lib/inets/doc/src/notes.xml +++ b/lib/inets/doc/src/notes.xml @@ -4,7 +4,7 @@
- 20022014 + 20022015 Ericsson AB. All Rights Reserved. @@ -1807,23 +1807,21 @@

[httpd] - Issues with ESI erl_script_timeout.

-

- - -

The erl_script_timeout config option is ducumented - as a number of seconds. But when parsing the config, in the - new format (not a config file), it was handled as if in - number of milliseconds.

- - -

When the erl-script-timeout time was exceeded, the server - incorrectly marked the answer as sent, thereby leaving - client hanging (with an incomplete answer). - This has been changed, so that now the socket will be - closed.

- - -

+ + +

The erl_script_timeout config option is ducumented + as a number of seconds. But when parsing the config, in the + new format (not a config file), it was handled as if in + number of milliseconds.

+ + +

When the erl-script-timeout time was exceeded, the server + incorrectly marked the answer as sent, thereby leaving + client hanging (with an incomplete answer). + This has been changed, so that now the socket will be + closed.

+ +

Own Id: OTP-8509

@@ -1899,20 +1897,19 @@

[httpc] Several more or less critical fixes:

-

- - -

Initial call between the httpc manager and request - handler was synchronous.

-

When the manager starts a new request handler, - this is no longer a synchronous operation. Previously, - the new request handler made the connection to the - server and issuing of the first request (the reason - for starting it) in the gen_server init function. - If the connection for some reason "took some time", - the manager hanged, leaving all other activities by - that manager also hanging.

- + + +

Initial call between the httpc manager and request + handler was synchronous.

+

When the manager starts a new request handler, + this is no longer a synchronous operation. Previously, + the new request handler made the connection to the + server and issuing of the first request (the reason + for starting it) in the gen_server init function. + If the connection for some reason "took some time", + the manager hanged, leaving all other activities by + that manager also hanging.

+ - -

+

As a side-effect of these changes, some modules was also renamed, and a new api module, httpc, has been introduced diff --git a/lib/inets/doc/src/tftp.xml b/lib/inets/doc/src/tftp.xml index 00d9d53376..10398f5088 100644 --- a/lib/inets/doc/src/tftp.xml +++ b/lib/inets/doc/src/tftp.xml @@ -4,7 +4,7 @@

- 20062013 + 20062015 Ericsson AB. All Rights Reserved. @@ -216,12 +216,9 @@ five times when the time-out expires.

- -
- change_config(daemons, Options) -> [{Pid, Result}] Changes configuration for all daemons. @@ -234,8 +231,6 @@

Changes configuration for all TFTP daemon processes.

- - @@ -251,8 +246,6 @@

Changes configuration for all TFTP server processes.

- - @@ -268,7 +261,6 @@

Changes configuration for a TFTP daemon, server, or client process.

- @@ -282,8 +274,6 @@

Returns information about all TFTP daemon processes.

- - @@ -297,8 +287,6 @@

Returns information about all TFTP server processes.

- - @@ -341,9 +329,7 @@ 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.

- - - + @@ -359,8 +345,6 @@ port. When it receives a request for read or write, it spawns a temporary server process handling the actual transfer of the (virtual) file.

- - @@ -393,7 +377,6 @@ matching regexp is found.

-
-- cgit v1.2.3