inets: Improve httpd documentation to use types

In the translation from xml to markdown the properties
documentation for httpd was left as is, which does not
look great in ex_doc. This commit moves type documentation
from the moduledoc to specific types and extracts the
mod_* docs into their respective module.

As I did not want to migrate the mod_cgi and mod_action
docs just for them to be removed later, they have been removed
already in this doc refactor.

Author: garazdawi

lib/inets/doc/guides/hardening.md

@@ -339,16 +339,14 @@ list. The default is:
 Review this list and remove modules you do not need:
 
 - **`mod_cgi`** and **`mod_actions`** - Enable CGI script execution.
-  Deprecated in OTP 29 and scheduled for removal in OTP 30. If you still
-  need CGI support, add them explicitly to your module list. CGI introduces a
-  large attack surface (arbitrary process execution, environment variable
-  injection).
+  Removed in OTP 30. CGI introduces a large attack surface (arbitrary process
+  execution, environment variable injection).
 
 - **`mod_dir`** - Enables directory listing. Remove it to prevent information
   disclosure about your file structure.
 
 - **`mod_esi`** - Enables Erlang Scripting Interface. If used, restrict it
-  with [`erl_script_alias`](`m:httpd#prop_esi_alias`) to a whitelist of allowed modules.
+  with [`erl_script_alias`](`m:mod_esi#prop_esi_alias`) to a whitelist of allowed modules.
 
 - **`mod_trace`** - Handles HTTP TRACE requests. TRACE can be exploited in
   cross-site tracing (XST) attacks. This module is not in the default list
@@ -364,17 +362,17 @@ A minimal module chain for a static file server:
 
 If using `mod_auth`:
 
-- **Avoid [`{auth_type, plain}`](`m:httpd#prop_auth_type`)** in production. It stores passwords in
+- **Avoid [`{auth_type, plain}`](`m:mod_auth#prop_auth_type`)** in production. It stores passwords in
   cleartext files. Prefer `dets` or `mnesia`.
 
-- **Place auth files outside `document_root`**. The [`auth_user_file`](`m:httpd#prop_auth_user_file`) and
-  [`auth_group_file`](`m:httpd#prop_auth_group_file`) must not be accessible via HTTP.
+- **Place auth files outside `document_root`**. The [`auth_user_file`](`m:mod_auth#prop_auth_user_file`) and
+  [`auth_group_file`](`m:mod_auth#prop_auth_group_file`) must not be accessible via HTTP.
 
-- **Set [`auth_access_password`](`m:httpd#prop_auth_access_passwd`)** to a strong value. When not set or set to
+- **Set [`auth_access_password`](`m:mod_auth#prop_auth_access_passwd`)** to a strong value. When not set or set to
   `"NoPassword"`, no password is required for the authentication management
   API.
 
-- **Use IP-based restrictions** ([`allow_from`](`m:httpd#prop_allow_from`), [`deny_from`](`m:httpd#prop_deny_from`)) as an additional
+- **Use IP-based restrictions** ([`allow_from`](`m:mod_auth#prop_allow_from`), [`deny_from`](`m:mod_auth#prop_deny_from`)) as an additional
   layer, not as the sole access control mechanism.
 
 > #### Warning {: .warning }
@@ -401,21 +399,21 @@ Enable `mod_security` to throttle authentication brute force attempts:
 ]}}
 ```
 
-- **[`data_file`](`m:httpd#prop_data_file`)** - Path to the persistent security
+- **[`data_file`](`m:mod_security#prop_data_file`)** - Path to the persistent security
   data file. Store this outside `document_root`. Required for `mod_security`
   to persist blocked-user state across server restarts.
 
-- **[`max_retries`](`m:httpd#prop_max_retries`)** - Maximum failed authentication
+- **[`max_retries`](`m:mod_security#prop_max_retries`)** - Maximum failed authentication
   attempts before the user is blocked. Default: `3`.
 
-- **[`block_time`](`m:httpd#prop_block_time`)** - Minutes a blocked user remains
+- **[`block_time`](`m:mod_security#prop_block_time`)** - Minutes a blocked user remains
   locked out. Default: `60`.
 
-- **[`fail_expire_time`](`m:httpd#prop_fail_exp_time`)** - Minutes before a
+- **[`fail_expire_time`](`m:mod_security#prop_fail_exp_time`)** - Minutes before a
   failed attempt is forgotten. If the user does not retry within this window,
   the failure counter resets. Default: `30`.
 
-- **[`auth_timeout`](`m:httpd#prop_auth_timeout`)** - Seconds a successful
+- **[`auth_timeout`](`m:mod_security#prop_auth_timeout`)** - Seconds a successful
   authentication is remembered. After expiry the user must re-authenticate.
   Default: `30`.
 
@@ -428,13 +426,13 @@ Enable `mod_security` to throttle authentication brute force attempts:
 For runtime inspection and manual blocking, see `m:mod_security`
 ([`list_blocked_users/1`](`mod_security:list_blocked_users/1`), [`block_user/5`](`mod_security:block_user/5`), [`unblock_user/4`](`mod_security:unblock_user/4`)).
 
-### CGI and ESI Execution
+### ESI Execution
 
-- **[`script_alias`](`m:httpd#prop_script_alias`)** maps URL paths to CGI script directories. Ensure the
+- **`script_alias`** maps URL paths to ESI script directories. Ensure the
   mapped directory contains only intended scripts and is not writable by the
   web server process.
 
-- **[`erl_script_alias`](`m:httpd#prop_esi_alias`)** controls which Erlang modules can be called via ESI.
+- **[`erl_script_alias`](`m:mod_esi#prop_esi_alias`)** controls which Erlang modules can be called via ESI.
   Always specify an explicit whitelist:
 
   ```erlang
@@ -443,10 +441,10 @@ For runtime inspection and manual blocking, see `m:mod_security`
 
   Never use a wildcard or overly broad module list.
 
-- **[`script_timeout`](`m:httpd#prop_script_timeout`)** and **[`erl_script_timeout`](`m:httpd#prop_esi_timeout`)** default to 15 seconds.
+- **`script_timeout`** and **[`erl_script_timeout`](`m:mod_esi#prop_esi_timeout`)** default to 15 seconds.
   Review whether this is appropriate for your use case.
 
-- **[`script_nocache`](`m:httpd#prop_script_nocache`)** and **[`erl_script_nocache`](`m:httpd#prop_esi_nocache`)** - When set to `true`, the
+- **`script_nocache`** and **[`erl_script_nocache`](`m:mod_esi#prop_esi_nocache`)** - When set to `true`, the
   server adds HTTP header fields preventing proxies from caching dynamic
   responses. Default: `false`. Enable these to prevent stale or sensitive
   dynamic content from being served from proxy caches.
@@ -455,8 +453,8 @@ For runtime inspection and manual blocking, see `m:mod_security`
 >
 > The `script_alias` path resolution can bypass `mod_auth` directory
 > protections depending on module ordering. Ensure `mod_auth` appears
-> before `mod_cgi` in the module chain, and test that authentication
-> is enforced on CGI paths.
+> before `mod_esi` in the module chain, and test that authentication
+> is enforced on ESI paths.
 
 ### Logging
 

lib/inets/doc/guides/http_server.md

@@ -34,7 +34,6 @@ 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
@@ -43,10 +42,10 @@ The server implements numerous features, such as:
 
 The configuration of the server is provided as an Erlang property list.
 
-As of `Inets` 5\.0 the HTTP server is an easy to start/stop and customize web
+The HTTP server is an easy to start/stop and customize web
 server providing the most basic web server functionality. Inets is designed for
 embedded systems and if you want a full-fledged web server there are other
-erlang open source alternatives.
+Erlang open source alternatives.
 
 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
@@ -165,45 +164,14 @@ and cannot be the hostname that is allowed when putting in `bind_address`.
 `Inets` HTTP server provides two ways of creating dynamic web pages, each with
 its own advantages and disadvantages:
 
-- **_CGI scripts (deprecated)_** - 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.
 
 ### CGI Version 1.1, RFC 3875
 
 > #### Note {: .info }
-> `mod_cgi` and `mod_actions` are deprecated since OTP 29 and will be removed in OTP 30.
-> Use `mod_esi` instead for dynamic page generation.
->
-
-The module `mod_cgi` enables execution of
-[CGI scripts](http://www.ietf.org/rfc/rfc3875.txt) 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
-can be empty.
-
-Example:
-
-```text
-"Content-Type:text/plain\nAccept-Ranges:none\n\nsome very
-	plain text"
-```
-
-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](http://www.ietf.org/rfc/rfc3875.txt).
+> `mod_cgi` and `mod_actions` are removed since OTP 39.
 
 ### ESI
 
@@ -318,26 +286,8 @@ 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_actions - Filetype/Method-Based Script Execution
-
-> #### Note {: .info }
-> `mod_cgi` and `mod_actions` are deprecated since OTP 29 and will be removed in OTP 30.
-> Use `mod_esi` instead for dynamic page generation.
->
-
-This module runs CGI scripts whenever a file of a certain type or HTTP method
-(see [RFC 1945](http://tools.ietf.org/html/rfc1945)) is requested.
-
-Uses the following Erlang Web Server API interaction data:
-
-- `real_name` \- from `m:mod_alias`.
-
-Exports the following Erlang Web Server API interaction data, if possible:
-
-- **`{new_request_uri, RequestURI}`** - An alternative `RequestURI` has been
-  generated.
-
 ### mod_alias - URL Aliasing
+{: #mod_alias }
 
 The `m: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.
@@ -348,6 +298,7 @@ Exports the following Erlang Web Server API interaction data, if possible:
   `mod_alias:path/3`.
 
 ### mod_auth - User Authentication
+{: #mod_auth }
 
 The `m:mod_auth` module provides for basic user authentication using textual
 files, Dets databases as well as Mnesia databases.
@@ -411,16 +362,8 @@ 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.
 
-### mod_cgi - CGI Scripts
-
-> #### Note {: .info }
-> `mod_cgi` and `mod_actions` are deprecated since OTP 29 and will be removed in OTP 30.
-> Use `mod_esi` instead for dynamic page generation.
->
-
-This module handles invoking of CGI scripts.
-
 ### mod_dir - Directories
+{: #mod_dir }
 
 This module generates an HTML directory listing (Apache-style) if a client sends
 a request for a directory instead of a file. This module must be removed from
@@ -436,6 +379,7 @@ Exports the following Erlang Web Server API interaction data:
   a `MimeType`.
 
 ### mod_disk_log - Logging Using Disk_Log.
+{: #mod_disk_log }
 
 Standard logging using the "Common Logfile Format" and `m:disk_log`.
 
@@ -444,6 +388,7 @@ Uses the following Erlang Web Server API interaction data:
 - `remote_user` \- from `mod_auth`
 
 ### mod_esi - Erlang Server Interface
+{: #mod_esi }
 
 The `m:mod_esi` module implements the Erlang Server Interface (ESI) providing a
 tight and efficient interface to the execution of Erlang functions.
@@ -458,6 +403,7 @@ Exports the following Erlang web server API interaction data:
   a `MimeType`
 
 ### mod_get - Regular GET Requests
+{: #mod_get }
 
 This module is responsible for handling GET requests to regular files. GET
 requests for parts of files is handled by `mod_range`.
@@ -467,6 +413,7 @@ Uses the following Erlang web server API interaction data:
 - `real_name` \- from `m:mod_alias`
 
 ### mod_head - Regular HEAD Requests
+{: #mod_head }
 
 This module is responsible for handling HEAD requests to regular files. HEAD
 requests for dynamic content is handled by each module responsible for dynamic
@@ -477,6 +424,7 @@ Uses the following Erlang Web Server API interaction data:
 - `real_name` \- from `m:mod_alias`
 
 ### mod_log - Logging Using Text Files.
+{: #mod_log }
 
 Standard logging using the "Common Logfile Format" and text files.
 
@@ -485,6 +433,7 @@ Uses the following Erlang Web Server API interaction data:
 - `remote_user` \- from `mod_auth`
 
 ### mod_range - Requests with Range Headers
+{: #mod_range }
 
 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
@@ -498,6 +447,7 @@ Uses the following Erlang Web Server API interaction data:
 - `real_name` \- from `m:mod_alias`
 
 ### mod_responsecontrol - Requests with If\* Headers
+{: #mod_responsecontrol }
 
 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
@@ -529,6 +479,7 @@ Exports the following Erlang Web Server API interaction data:
   must be treated as an ordinary get request.
 
 ### mod_security - Security Filter
+{: #mod_security }
 
 The `m:mod_security` module serves as a filter for authenticated requests
 handled in `m:mod_auth`. It provides a possibility to restrict users from access
@@ -541,6 +492,7 @@ blocked users or users who have been authenticated within a configurable amount
 of time.
 
 ### mod_trace - TRACE Request
+{: #mod_trace }
 
 `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.

lib/inets/doc/notes.md

@@ -2627,7 +2627,7 @@ limitations under the License.
 
   `ossl` will work for as long as the ssl application supports it.
 
-  See the httpd [socket_type](`m:httpd#props_comm`) communication property or
+  See the httpd [socket_type](`m:httpd#prop_socket_type`) communication property or
   the httpc [request/4,5](`httpc:request/4`) function for more info.
 
   Own Id: OTP-9230
@@ -2636,7 +2636,7 @@ limitations under the License.
 
 ### Fixed Bugs and Malfunctions
 
-- \[httpd] Wrong [security property](`m:httpd#props_sec`) names used in
+- \[httpd] Wrong [security property](`t:mod_security:security_option/0`) names used in
   documentation.
 
   `security_data_file` used instead of `data_file`.
@@ -2762,7 +2762,7 @@ limitations under the License.
   instead.
 
   See the `http_option` option in the [request/4,5](`httpc:request/4`) or the
-  [socket-type](`m:httpd#props_comm`) section of the Communication properties
+  [socket_type](`m:httpd#prop_socket_type`) section of the Communication properties
   chapter for more info,
 
   Own Id: OTP-7907
@@ -2777,8 +2777,8 @@ limitations under the License.
 
 - \[httpd] - Improved mod_alias. Now able to do better URL rewrites.
 
-  See [URL aliasing properties](`m:httpd#props_alias`) and the
-  [CGI properties](`m:httpd#props_cgi`) section(s) for more info,
+  See [URL aliasing properties](`t:mod_alias:url_alias_option/0`) and the
+  CGI properties section(s) for more info,
 
   Own Id: OTP-8573
 
@@ -3103,8 +3103,7 @@ limitations under the License.
 
   Default is `inet6fb4` which emulates the behaviour of the previous version.
 
-  See the [Communication properties](`m:httpd#props_comm`) section for more
-  info.
+  See the [Communication properties](`t:httpd:communication_option/0`) section for more info.
 
   Own Id: OTP-8069