From c54168c72bb42f8ffb0e341fd56cd81a89b53430 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Fri, 3 Jul 2015 09:34:23 +0200 Subject: Inets User Guide Editorial Changes --- lib/inets/doc/src/ftp_client.xml | 53 +-- lib/inets/doc/src/http_client.xml | 96 ++-- lib/inets/doc/src/http_server.xml | 851 ++++++++++++++++++----------------- lib/inets/doc/src/inets_services.xml | 59 +-- lib/inets/doc/src/introduction.xml | 57 +++ lib/inets/doc/src/part.xml | 14 +- 6 files changed, 581 insertions(+), 549 deletions(-) create mode 100644 lib/inets/doc/src/introduction.xml (limited to 'lib') diff --git a/lib/inets/doc/src/ftp_client.xml b/lib/inets/doc/src/ftp_client.xml index 2f5b8abb5f..84fa064551 100644 --- a/lib/inets/doc/src/ftp_client.xml +++ b/lib/inets/doc/src/ftp_client.xml @@ -34,38 +34,27 @@
- Introduction + Getting Started -

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.

+

FTP clients are considered to be rather temporary. Thus, + they are only started and stopped during runtime and cannot + be started at application startup. + The FTP client API is designed to allow some functions to + return intermediate results. This implies that only the process + that started the FTP client can access it with + preserved sane semantics. (This can be solved + by changing the API, using the concept of a controlling + process as with other OTP applications, but + that is something for future releases of Inets.) + If the process that started the FTP session + dies, the FTP client process terminates.

-

The client supports ipv6 as long as the underlying mechanisms - also do so.

+

The client supports IPv6 as long as the underlying mechanisms + also do so.

-
- -
- Using the FTP Client API -

The following is a simple example of an ftp session, where +

The following is a simple example of an FTP session, where the user guest with password password logs on to - the remote host erlang.org, and where the file - appl.erl is transferred from the remote to the local - host. When the session is opened, the current directory at - the remote host is /home/guest, and /home/fred - at the local host. Before transferring the file, the current - local directory is changed to /home/eproj/examples, and - the remote directory is set to - /home/guest/appl/examples.

+ the remote host erlang.org:

inets:start(). ok @@ -86,6 +75,14 @@ 9> inets:stop(ftpc, Pid). ok ]]> +

The file + appl.erl is transferred from the remote to the local + host. When the session is opened, the current directory at + the remote host is /home/guest, and /home/fred + at the local host. Before transferring the file, the current + local directory is changed to /home/eproj/examples, and + the remote directory is set to + /home/guest/appl/examples.

diff --git a/lib/inets/doc/src/http_client.xml b/lib/inets/doc/src/http_client.xml index 5c42f72cec..f4d7b751ac 100644 --- a/lib/inets/doc/src/http_client.xml +++ b/lib/inets/doc/src/http_client.xml @@ -34,103 +34,91 @@
- Introduction + Configuration -

The HTTP client default profile will be started when the inets +

The HTTP client default profile is 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 + that Erlang node. Other profiles can 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 + dynamically in runtime. Each client profile spawns a new + process to handle each request, unless a persistent connection + can be used with or without pipelining. + The client adds a host header and an empty te header if there are no such headers present in the request.

-

The client supports ipv6 as long as the underlying mechanisms also do +

The client supports IPv6 as long as the underlying mechanisms also do so.

-
-
- Configuration -

What to put in the erlang node application configuration file - in order to start a profile at application startup.

+

The following is to be put in the Erlang node application configuration file + to start a profile at application startup:

-      [{inets, [{services, [{httpc, PropertyList}]}]}]
-
-

For valid properties see + [{inets, [{services, [{httpc, PropertyList}]}]}] +

For valid properties, see httpc(3).

- Using the HTTP Client API + Getting Started +

Start Inets:

1 > inets:start(). - ok - -

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

+ ok +

The following calls use the default client profile. + Use the proxy "www-proxy.mycompany.com:8000", + except from requests to localhost. This applies to all the + following requests.

+

Example:

2 > httpc:set_options([{proxy, {{"www-proxy.mycompany.com", 8000}, ["localhost"]}}]). - ok - -

An ordinary synchronous request.

+ ok +

The following is an ordinary synchronous request:

3 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} = - httpc:request(get, {"http://www.erlang.org", []}, [], []). - -

With all default values, as above, a get request can also be written - like this.

+ httpc:request(get, {"http://www.erlang.org", []}, [], []). +

With all the default values presented, a get request can also be written + as follows:

4 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} = - httpc:request("http://www.erlang.org"). - -

An ordinary asynchronous request. The result will be sent - to the calling process in the form {http, {ReqestId, Result}}

+ httpc:request("http://www.erlang.org"). +

The following is an ordinary asynchronous request:

5 > {ok, RequestId} = - httpc:request(get, {"http://www.erlang.org", []}, [], [{sync, false}]). - -

In this case the calling process is the shell, so we receive the - result.

+ httpc:request(get, {"http://www.erlang.org", []}, [], [{sync, false}]). +

The result is sent to the calling process as + {http, {ReqestId, Result}}.

+

In this case, the calling process is the shell, so the following + result is received:

6 > receive {http, {RequestId, Result}} -> ok after 500 -> error end. - ok - -

Send a request with a specified connection header.

+ ok +

This sends a request with a specified connection header:

7 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} = httpc:request(get, {"http://www.erlang.org", [{"connection", "close"}]}, - [], []). - + [], []). -

Start a HTTP client profile.

+

Start an HTTP client profile:

{ok, Pid} = inets:start(httpc, [{profile, foo}]). {ok, <0.45.0>} ]]> -

The new profile has no proxy settings so the connection will - be refused

+

The new profile has no proxy settings, so the connection is refused:

9 > httpc:request("http://www.erlang.org", foo). - {error, econnrefused} - + {error, econnrefused} -

Stop a HTTP client profile.

+

Stop the HTTP client profile:

10 > inets:stop(httpc, foo). - ok - + ok -

Alternatively:

+

Alternative way to stop the HTTP client profile:

10 > inets:stop(httpc, Pid). - ok - + ok
diff --git a/lib/inets/doc/src/http_server.xml b/lib/inets/doc/src/http_server.xml index 51ed826c7c..efa5f7a8f5 100644 --- a/lib/inets/doc/src/http_server.xml +++ b/lib/inets/doc/src/http_server.xml @@ -22,7 +22,7 @@ - HTTP server + HTTP server Ingela Anderton Andin @@ -36,62 +36,65 @@
- Introduction - + Configuration +

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.

- -

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, and Directory Listings

- -

The configuration of the server is provided as an erlang - property list, and for backwards compatibility also a configuration + 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.

+ +

The server implements numerous features, such as:

+ + Secure Sockets Layer (SSL) + Erlang Scripting Interface (ESI) + Common Gateway Interface (CGI) + 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 + + +

The configuration of the server is provided as an Erlang + property list. For backwards compatibility, a configuration file using apache-style configuration directives is supported.

-

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.

+

As of Inets 5.0 the HTTP server is an easy to + start/stop and customize web server providing the most basic + web server functionality. Depending on your needs, there + are also other Erlang-based web servers that can be of interest + such as Yaws, which, + for example, has its own + markup support to generate HTML and supports certain buzzword + technologies, such as SOAP.

-

Allmost all server functionality has been implemented using an - especially crafted server API which is described in the Erlang Web - Server API. This API can be used to advantage by all who wish +

Almost all server functionality has been implemented using an + especially crafted server API, which is described in the Erlang Web + Server API. This API can be used to enhance the core server functionality, for example with custom logging and authentication.

- -
- -
- Configuration - -

What to put in the erlang node application configuration file - in order to start a http server at application startup.

+

The following is to be put in the Erlang node application configuration + file to start an HTTP server at application startup:

[{inets, [{services, [{httpd, [{proplist_file, "/var/tmp/server_root/conf/8888_props.conf"}]}, {httpd, [{proplist_file, - "/var/tmp/server_root/conf/8080_props.conf"}]}]}]}]. - - -

The server is configured using an erlang property list. - For the available properties see - httpd(3) - For backwards compatibility also apache-like config files - are supported. + "/var/tmp/server_root/conf/8080_props.conf"}]}]}]}]. + +

The server is configured using an Erlang property list. + For the available properties, see + httpd(3). + For backwards compatibility, apache-like configuration files + are also supported.

-

All possible config properties are as follows

+

The available configuration properties are as follows:

httpd_service() -> {httpd, httpd()} httpd() -> [httpd_config()] @@ -103,40 +106,43 @@ debug_options() -> {all_functions, modules()} | {exported_functions, modules()} | {disable, modules()} - modules() -> [atom()] - -

{proplist_file, file()} File containing an erlang property + modules() -> [atom()] +

Here:

+ + {file, file()} +

If you use an old apace-like configuration file.

 + {proplist_file, file()} +

File containing an Erlang property list, followed by a full stop, describing the HTTP server - configuration.

-

{file, file()} If you use an old apace-like configuration file.

-

{debug, debug()} - Can enable trace on all - functions or only exported functions on chosen modules.

-

{accept_timeout, integer()} sets the wanted timeout value for - the server to set up a request connection.

- - + configuration.

 + {debug, debug()} +

Can enable trace on all functions or only exported functions + on chosen modules.

 + {accept_timeout, integer()} +

Sets the wanted time-out value for + the server to set up a request connection.

 +
- Using the HTTP Server API + Getting Started + +

Start Inets:

1 > inets:start(). - ok - -

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. -

+ ok +

Start an HTTP server with minimal required configuration. + If you specify port 0, an arbitrary available port is + used, and you can use function info to find which port + number that was picked:

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} - + {ok, 0.79.0} +

Call info:

3 > httpd:info(Pid). [{mime_types,[{"html","text/html"},{"htm","text/html"}]}, @@ -144,325 +150,312 @@ {bind_address, {127,0,0,1}}, {server_root,"/tmp"}, {port,59408}, - {document_root,"/tmp/htdocs"}] - + {document_root,"/tmp/htdocs"}] -

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. +

Reload the configuration without restarting the server: +

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. - + ok. + +

port and bind_address cannot be changed. + Clients trying to access the server during the reload + get a service temporary unavailable answer.

 5 > httpd:info(Pid, [server_root, document_root]). - [{server_root,"/tmp/www_test"},{document_root,"/tmp/www_test/htdocs"}] - + [{server_root,"/tmp/www_test"},{document_root,"/tmp/www_test/htdocs"}] - 6 > ok = inets:stop(httpd, Pid). - + 6 > ok = inets:stop(httpd, Pid). -

Alternative:

+

Alternative:

- 6 > ok = inets:stop(httpd, {{127,0,0,1}, 59408}). - + 6 > ok = inets:stop(httpd, {{127,0,0,1}, 59408}). -

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.

- - +

Notice that bind_address must be the IP address reported + by function info and cannot be the hostname that is allowed + when putting in bind_address.

Htaccess - User Configurable Authentication. -

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:

+ +

Web server users without server administrative privileges + that need to manage authentication of web pages that are local + to their user can use the per-directory runtime configurable + user-authentication scheme htaccess. + It works as follows:

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. - 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. - 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. - 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. - 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. + searched for an access file (default is .htaccess), which + 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. + The rules in an access file apply to files in the same + directory 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 is applied. + To change the rules that restrict the use of + an asset, the user only needs write access + to the directory where the asset is. + All access files in the path to a requested asset are read + once per request. This means that the load on the server + increases when htaccess is used. + If a directory is limited both by authentication directives + in the HTTP server configuration file and by the htaccess + files, the user must be allowed to get access to the file by both + methods for the request to succeed.
Access Files Directives -

In every directory under the DocumentRoot or under an - Alias 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.

- +

In every directory under DocumentRoot or under an + Alias a user can place an access file. An access file + is a plain text file that specifies the restrictions to + consider before the web server answers 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 is used.

+ + "allow" -

DIRECTIVE: "allow"

-

Syntax:Allow from subnet subnet|from all

-Default:from all

-

-

Same as the directive allow for the server config file.

+

Syntax: Allow from subnet subnet | from all

+

Default: from all

+

Same as directive allow for the server configuration file.

 - -

DIRECTIVE: "AllowOverRide"

-

Syntax:AllowOverRide all | none | - Directives

-Default:- None -

-AllowOverRide 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. + "AllowOverRide" + +

Syntax: AllowOverRide all | none | Directives

+

Default: none

+

AllowOverRide specifies the parameters that + access files in subdirectories are not allowed to alter the value + for. If the parameter is set to none, no further + access files is parsed.

-

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.

+

If only one access file exists, setting this parameter to + none can ease the burden on the server as the server + then stops looking for access files.

 + "AuthGroupfile" -

DIRECTIVE: "AuthGroupfile"

-

Syntax:AuthGroupFile Filename

-Default:- None -

-

-

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 +

Syntax: AuthGroupFile Filename

+

Default: none

+

AuthGroupFile indicates which file that contains the list + of groups. The 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:

+ of the group, separated by a space, for example:

-GroupName: Member1 Member2 .... MemberN
-
+GroupName: Member1 Member2 .... MemberN + "AuthName" -

DIRECTIVE: "AuthName"

-

Syntax:AuthName auth-domain

-Default:- None -

-

-

Same as the directive AuthName for the server config file.

+

Syntax: AuthName auth-domain

+

Default: none

+

Same as directive AuthName for the server + configuration file.

 + "AuthType" -

DIRECTIVE: "AuthType"

-

Syntax:AuthType Basic

-Default:Basic

-

-

AuthType Specify which authentication scheme that shall - be used. Today only Basic Authenticating using UUEncoding of - the password and user ID is implemented.

+

Syntax: AuthType Basic

+

Default: Basic

+

AuthType specifies which authentication scheme to + be used. Only Basic Authenticating using UUEncoding of + the password and user ID is implemented.

 + "AuthUserFile" -

DIRECTIVE: "AuthUserFile"

-

Syntax:AuthUserFile Filename

-Default:- None -

-

-

AuthUserFile 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 +

Syntax: AuthUserFile Filename

+

Default:none

+

AuthUserFile indicates which file that contains the list + of users. The filename must contain the absolute path to the + file. The username 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:

+ through the web server. The format of the file is one user per row. + Every row contains UserName and Password separated + by a colon, for example:

 UserName:Password
-UserName:Password
-
+UserName:Password + "deny" -

DIRECTIVE: "deny"

-

Syntax:deny from subnet subnet|from all

-Context: Limit

-

Same as the directive deny for the server config file.

+

Syntax: deny from subnet subnet | from all

+

Context: Limit

+

Same as directive deny for the server configuration file.

 - -

DIRECTIVE: "Limit"

-

-

Syntax: RequestMethods>

-Default: - None -

-

-

]]> 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 + "Limit" + +

Syntax: RequestMethods>

+

Default: none

+

]]> and </Limit> are used to enclose + a group of directives applying only to requests using + the specified methods. If no request method is specified, all request methods are verified against the restrictions.

+

Example:

 <Limit POST GET HEAD>
   order allow deny
   require group group1
   allow from 123.145.244.5
-</Limit>
-
+</Limit> - -

DIRECTIVE: "order"

-Syntax:order allow deny | deny allow

-Default: allow deny

-

-

order, defines if the deny or allow control shall - be preformed first.

-

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.

-

If the order is set to deny allow then only users from networks - specified to be in the allowed subset will succeed to request + "order" + +

Syntax: order allow deny | deny allow

+

Default: allow deny

+

order defines if the deny or allow control is to + be performed first.

+

If the order is set to allow deny, the users + network address is first controlled to be in the allow subset. + If the user network address is not in the allowed subset, the user + is denied to get the asset. If the network address is in the + allowed subset, a second control is performed. That is, + the user network address is not in the subset of network + addresses to be denied as specified by parameter deny.

+

If the order is set to deny allow, only users from networks + specified to be in the allowed subset succeeds to request assets in the limited area.

 - -

DIRECTIVE: "require"

-

Syntax:require - group group1 group2...|user user1 user2...

-Default:- None -

-Context: Limit

-

-

See the require directive in the documentation of mod_auth(3) - for more information.

+ "require" + +

Syntax: require + group group1 group2... | user user1 user2...

+

Default: none

+

Context: Limit

+

For more information, see directive require in + mod_auth(3).

 - +
- -
Dynamic Web Pages -

The Inets HTTP server provides two ways of creating dynamic web - pages, each with its own advantages and disadvantages.

-

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.

-

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.

- + +

Inets HTTP server provides two ways of creating dynamic web + pages, each with its own advantages and disadvantages:

+ + CGI scripts +

Common Gateway Interface (CGI) scripts 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. +

+ ESI-functions +

Erlang Server Interface (ESI) functions provide a tight and efficient + interface to the execution of Erlang functions. This interface, + on the other hand, is Inets specific.

 + +
- The Common Gateway Interface (CGI) Version 1.1, RFC 3875. -

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 + 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 - the client.

-

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:

+ the client.

+

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 can be + empty.

+

Example:

"Content-Type:text/plain\nAccept-Ranges:none\n\nsome very - plain text" + plain text" -

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.

-

Support for CGI-1.1 is implemented in accordance with the RFC - 3875.

+

The server interprets the message headers and most of them + are transformed into HTTP headers and sent back to the + client together with the message-body.

+

Support for CGI-1.1 is implemented in accordance with + RFC 3875.

- Erlang Server Interface (ESI) -

The erlang server interface is implemented by the - module mod_esi.

+ ESI +

The Erlang server interface is implemented by + module mod_esi.

- ERL Scheme + ERL Scheme

The erl scheme is designed to mimic plain CGI, but without - the extra overhead. An URL which calls an Erlang erl function + the extra overhead. An URL that calls an Erlang erl function has the following syntax (regular expression):

-http://your.server.org/***/Module[:/]Function(?QueryString|/PathInfo) - -

*** above depends on how the ErlScriptAlias config - directive has been used

-

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 +http://your.server.org/***/Module[:/]Function(?QueryString|/PathInfo) +

*** depends on how the ErlScriptAlias config + directive has been used.

+

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 function + with arity three, as it permits to send chunks of the + web page 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 backwards compatibility reasons. - See mod_esi(3) for - implementation details of the esi callback function.

+ For implementation details of the ESI callback function, + see mod_esi(3).

- EVAL Scheme + EVAL Scheme

The eval scheme is straight-forward and does not mimic the - behavior of plain CGI. An URL which calls an Erlang eval + behavior of plain CGI. An URL that calls an Erlang eval function has the following syntax:

-http://your.server.org/***/Mod:Func(Arg1,...,ArgN) - -

*** above depends on how the ErlScriptAlias config - directive has been used

-

The module (Mod) referred to must be found in the code - path, and data returned by the function (Func) is passed +http://your.server.org/***/Mod:Func(Arg1,...,ArgN) +

*** depends on how the ErlScriptAlias config + directive has been used.

+

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 mod_esi(3) for implementation details of the esi - callback function.

+ function must take the form as specified in + the CGI specification. For implementation details of the ESI + callback function, + see mod_esi(3).

The eval scheme can seriously threaten the - integrity of the Erlang node housing a Web server, for - example:

+ integrity of the Erlang node housing a web server, for + example:

-http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[]))) - -

which effectively will close down the Erlang node, - therefor, use the erl scheme instead, until this - security breach has been fixed.

-

Today there are no good way of solving this problem - and therefore Eval Scheme may be removed in future - release of Inets.

+http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[]))) +

This effectively closes down the Erlang node. + Therefore, use the erl scheme instead, until this + security breach is fixed.

+

Today there are no good ways of solving this problem + and therefore the eval scheme can be removed in future + release of Inets.
- -
- Logging -

There are three types of logs supported. Transfer logs, - security logs and error logs. The de-facto standard Common + Logging + +

Three types of logs are 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:

remotehost rfc931 authuser [date] "request" status bytes

+

Here:

remotehost - Remote hostname + Remote hostname. rfc931 - The client's remote username (RFC 931). + The client remote username (RFC 931). authuser - The username with which the user authenticated himself. + The username used for authentication. [date] Date and time of the request (RFC 1123). "request" @@ -473,7 +466,7 @@ http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[ The content-length of the document transferred.

Internal server errors are recorded in the error log file. The - format of this file is a more ad hoc format than the logs using + format of this file is a more unplanned format than the logs using Common Logfile Format, but conforms to the following syntax:

[date] access to path failed for @@ -481,73 +474,79 @@ http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[

- The Erlang Web Server API -

The process of handling a HTTP request involves several steps + Erlang Web Server API +

The process of handling an HTTP request involves several steps, such as:

- Seting up connections, sending and receiving data. - URI to filename translation - Authenication/access checks. - Retriving/generating the response. - Logging + Setting up connections, sending and receiving data. + URI to filename translation. + Authentication/access checks. + Retrieving/generating the response. + Logging. -

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.

+

To provide customization and extensibility of the request + handling of the HTTP servers, most of these steps are handled by + one or more modules. These modules can be replaced or removed at + runtime and new ones can be added. For each request, all modules are + traversed in the order specified by the module 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 Section + Inets Web Server Modules.

+

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.

+ Erlang webserver API module sequence or generate data to be used + by consecutive Erlang Web Server API modules. This is + possible owing to an internal list of key-value tuples, referred to + as interaction data.

Interaction data enforces module dependencies and - should be avoided if possible. This means the order - of modules in the Modules property is significant.

+ is to be avoided if possible. This means that the order + of modules in the modules property is significant.
API Description -

Each module implements server functionality - using the Erlang Web Server API should implement the following +

Each module that implements server functionality + using the Erlang web server API is to implement the following call back functions:

- do/1 (mandatory) - the function called when - a request should be handled. - load/2 - store/2 - remove/1 + do/1 (mandatory) - the function called when + a request is to be handled + load/2 + store/2 + remove/1

The latter functions are needed only when new config - directives are to be introduced. For details see - httpd(3)

+ directives are to be introduced. For details, see + httpd(3).

- Inets Web Server Modules

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.

+ Inets Web Server Modules + +

The convention is that + all modules implementing some web server functionality has the + name mod_*. When configuring the web server, an appropriate + selection of these modules is to be present in the module + directive. Notice that there are some interaction dependencies + to take into account, so the order of the modules cannot be + random.

- mod_action - Filetype/Method-Based Script Execution. -

Runs CGI scripts whenever a file of a - certain type or HTTP method (See RFC 1945) is requested. + mod_action - Filetype/Method-Based Script Execution +

This module runs CGI scripts whenever a file of a + certain type or HTTP method (see + RFC 1945RFC 1945) + is requested.

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias

Exports the following Erlang Web Server API interaction data, if possible:

@@ -559,48 +558,51 @@ http://your.server.org/eval?httpd_example:print(atom_to_list(apply(erlang,halt,[
mod_alias - URL Aliasing -

This module makes it possible to map different parts of the - host file system into the document tree e.i. creates aliases and +

The mod_alias + module makes it possible to map different parts of the + host file system into the document tree, that is, creates aliases and redirections.

Exports the following Erlang Web Server API interaction data, if possible:

{real_name, PathData} - PathData is the argument used for API function mod_alias:path/3. + PathData is the argument used for API function + mod_alias:path/3.
- mod_auth - User Authentication -

This module provides for basic user authentication using - textual files, dets databases as well as mnesia databases.

+ mod_auth - User Authentication +

The mod_auth(3) + module provides for basic user authentication using + textual files, Dets databases as well as Mnesia databases.

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias

Exports the following Erlang Web Server API interaction data:

{remote_user, User} - The user name with which the user has authenticated himself. + The username used for authentication.
- Mnesia as Authentication Database + Mnesia As Authentication Database -

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 +

If Mnesia is used as storage method, Mnesia must be + started before the HTTP server. The first time Mnesia is + started, the schema and the tables must be created before + Mnesia is started. A simple example of a module with two + functions that creates and start Mnesia is provided + here. Function first_start/0 is to be used the first + time. It creates the schema and the tables. + start/0 is to be used in consecutive startups. + start/0 starts Mnesia and waits for the tables to be initiated. This function must only be used when the - schema and the tables already is created.

+ schema and the tables are already created.

-module(mnesia_test). @@ -624,28 +626,28 @@ first_start() -> start() -> mnesia:start(), - mnesia:wait_for_tables([httpd_user, httpd_group], 60000). - + mnesia:wait_for_tables([httpd_user, httpd_group], 60000). -

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 +

To create the Mnesia tables, we use two records defined in + mod_auth.hrl, so that file must be included. first_start/0 + creates a schema that specifies on which nodes the database is to 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 of + how to create the table, see + mnesia, documentation for + more information. As the implementation of the mod_auth_mnesia + saves one row for each user, the type must be bag. + When the schema and the tables are created, function + mnesia:start/0 + is used to start Mnesia and + waits for the tables to be loaded. Mnesia uses the + directory specified as mnesia_dir at startup if specified, + otherwise Mnesia uses the current directory. For security + reasons, ensure that the Mnesia tables are stored outside + the document tree of the HTTP server. If they are placed in the + directory which it protects, clients can download the tables. + Only the Dets and Mnesia storage + methods allow writing of dynamic user data to disk. plain is a read only method.

@@ -653,19 +655,19 @@ start() ->
mod_cgi - CGI Scripts -

This module handles invoking of CGI scripts

+

This module handles invoking of CGI scripts.

mod_dir - Directories

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 + instead of a file. This module must be removed from the Modules config directive if directory listings is unwanted.

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias

Exports the following Erlang Web Server API interaction data:

@@ -677,27 +679,27 @@ start() ->
- mod_disk_log - Logging Using disk_log. + mod_disk_log - Logging Using Disk_Log.

Standard logging using the "Common Logfile Format" and - disk_log(3).

+ kernel:disk_log(3).

Uses the following Erlang Web Server API interaction data:

- remote_user - from mod_auth + remote_user - from mod_auth
mod_esi - Erlang Server Interface -

This module implements - the Erlang Server Interface (ESI) that provides a tight and - efficient interface to the execution of Erlang functions.

-

Uses the following Erlang Web Server API interaction data: +

The mod_esi(3) + module implements the Erlang Server Interface (ESI) providing a + tight and efficient interface to the execution of Erlang functions.

+

Uses the following Erlang web server API interaction data:

- remote_user - from mod_auth + remote_user - from mod_auth -

Exports the following Erlang Web Server API interaction data: +

Exports the following Erlang web server API interaction data:

{mime_type, MimeType} @@ -709,11 +711,11 @@ start() ->
mod_get - Regular GET Requests

This module is responsible for handling GET requests to regular - files. GET requests for parts of files is handled by mod_range.

-

Uses the following Erlang Web Server API interaction data: + files. GET requests for parts of files is handled by mod_range.

+

Uses the following Erlang web server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias
@@ -725,7 +727,7 @@ start() ->

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias
@@ -736,13 +738,13 @@ start() ->

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias

Exports the following Erlang Web Server API interaction data:

{remote_user_name, User} - The user name with which the user has authenticated himself. + The username used for authentication.
@@ -750,84 +752,83 @@ start() -> mod_log - Logging Using Text Files.

Standard logging using the "Common Logfile Format" and text files.

-

Uses the following Erlang Webserver API interaction data: +

Uses the following Erlang Web Server API interaction data:

- remote_user - from mod_auth + remote_user - from mod_auth
mod_range - Requests with Range Headers -

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.

-

Note that request for multiple parts of a document will report a +

This module responses to requests for one or many ranges of a + file. This is especially useful when downloading large files, + as a broken download can be resumed.

+

Notice that request for multiple parts of a document report a size of zero to the log file.

-

Uses the following Erlang Webserver API interaction data: +

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias
mod_response_control - Requests with If* Headers -

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.

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. -

+

This module controls that the conditions in the requests are + fulfilled. For example, a request can specify that the answer + only is of interest if the content is unchanged since the last + retrieval. If the content is changed, the range request is to + be converted to a request for the whole file instead.

+

If a client sends more than one of the header fields that + restricts the servers right to respond, the standard does not + specify how this is to be handled. + httpd(3) controls each + field in the following order and if one of the fields does not + match the current state, the request is rejected with a proper + response:

+

If-modified

+

If-Unmodified

+

If-Match

+

If-Nomatch

- 1.If-modified

- - 2.If-Unmodified

- - 3.If-Match

- - 4.If-Nomatch

-

-

Uses the following Erlang Webserver API interaction data: +

Uses the following Erlang Web Server API interaction data:

- real_name - from mod_alias + real_name - from mod_alias -

Exports the following Erlang Webserver API interaction data: +

Exports the following Erlang Web Server API interaction data:

{if_range, send_file} - The conditions for the range request was not fulfilled. + The conditions for the range request are not fulfilled. The response must not be treated as a range request, instead it - must be treated as a ordinary get request. + must be treated as an ordinary get request.
mod_security - Security Filter -

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 +

The mod_security + module serves as a filter for authenticated requests + handled in mod_auth(3). + It provides a 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.

+ well as blocking of users, and it calls a configurable + callback module when the events occur.

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.

+ API to block or unblock users manually. This API can also list + blocked users or users who have been authenticated within a + configurable amount of time.

mod_trace - TRACE Request -

mod_trace is responsible for handling of TRACE requests. +

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 + the request message that the responding web server or proxy received.

diff --git a/lib/inets/doc/src/inets_services.xml b/lib/inets/doc/src/inets_services.xml index f78485cb64..d100216ebb 100644 --- a/lib/inets/doc/src/inets_services.xml +++ b/lib/inets/doc/src/inets_services.xml @@ -22,7 +22,7 @@ - Introduction + Inets Ingela Anderton Andin @@ -34,45 +34,26 @@
- Purpose -

Inets is a container for Internet clients and - servers. Currently, an 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 2616.

-
- -
- Prerequisites -

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.

-
- -
- The Service Concept -

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.

-

Services that should be configured for startup at application - startup time should be put into the erlang node configuration file - on the form:

+ Service Concept +

Each client and server in Inets is viewed as a service. + Services can be configured to be started at application startup or + dynamically in runtime. To run Inets as a distributed + application that handles application failover and takeover, + configure the services to be started at application startup. + When starting the Inets application, the Inets + top supervisor starts a number of subsupervisors and worker + processes for handling the provided services. + When starting services dynamically, new children are added to the + supervision tree, unless the service is started with the standalone + option. In this case the service is linked to the calling process + and all OTP application features, such as soft upgrade, are lost.

+

Services to be configured for startup at application startup are to + be put into the Erlang node configuration file + on the following form:

-      [{inets, [{services, ListofConfiguredServices}]}].
-
-

For details of exactly what to put in the list of configured - services see the documentation for the services that should be - configured.

+ [{inets, [{services, ListofConfiguredServices}]}]. +

For details of what to put in the list of configured services, + see the documentation for the services to be configured.

diff --git a/lib/inets/doc/src/introduction.xml b/lib/inets/doc/src/introduction.xml new file mode 100644 index 0000000000..ef3e109df5 --- /dev/null +++ b/lib/inets/doc/src/introduction.xml @@ -0,0 +1,57 @@ + + + + +
+ + 19972013 + Ericsson AB. 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. + + + + Introduction + Ingela Anderton Andin + + + + + 2004-09-28 + A + inets_services.xml +
+ +
+ Purpose +

Inets is a container for Internet clients and servers + including the following:

+ + An FTP client + A TFTP client and server + An client and server + +

The HTTP client and server are HTTP 1.1 compliant as + defined in + RFC 2616.

+
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language, concepts of OTP, and has a basic + understanding of the FTP, TFTP, and HTTP protocols.

+
+ + + diff --git a/lib/inets/doc/src/part.xml b/lib/inets/doc/src/part.xml index 1640ff507c..3b817eecf2 100644 --- a/lib/inets/doc/src/part.xml +++ b/lib/inets/doc/src/part.xml @@ -30,10 +30,18 @@ part.sgml -

The Inets Application 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.

+

The Inets application provides a set of + Internet-related services as follows:

+ + An FTP client + A TFTP client and server + An client and server + +

The HTTP client and server are HTTP 1.1 compliant as + defined in + RFC 2616.

 + -- cgit v1.2.3