http¶
Name¶
http — Central server for RPC and the message database
Synopsis¶
http [-c config]
Description¶
http(8gx) is a trivial HTTP server. It understands the special HTTP methods as used by RPC-over-HTTP protocol as used by Outlook, it can serve files verbatim, or forward requests to a FastCGI server such as php-fpm(8).
Options¶
- -c config
- Read configuration directives from the given file. If this option is not specified, /etc/gromox/http.cfg will be read if it exists.
- -?
- Display option summary.
URI processing order¶
- Requests are passed to the mod_rewrite(4gx) module (built-in) to have their URI potentially rewritten.
- If a HTTP request is using the methods RPC_IN_DATA or RPC_OUT_DATA, the data stream is handed off to the exchange_emsmdb(4gx) plugin.
- Otherwise, HTTP processing modules (HPM) are invoked. Processing ends when one module signals that the request was handled. The order depends on the HPM list (cf. http.cfg(5gx):hpm_plugin_list).
- Otherwise, the mod_fastcgi(4gx) module (built-in) is invoked. Processing ends if the module handled the request.
- Otherwise, the mod_cache(4gx) module (built-in) is invoked. Processing ends if the module handled the request.
- Otherwise, the request is rejected.
RPC-over-HTTP¶
RPC-over-HTTP utilizes two special HTTP methods, RPC_IN_DATA and RPC_OUT_DATA. These requests can, similarly to HTTP CONNECT, be very long-lived. The RPC data stream is handled by the included exchange_emsmdb(4gx) plugin.
Configuration directives¶
The usual config file location is /etc/gromox/http.cfg.
- block_interval_auths
- The amount of time a user is blocked from connecting to the service after too many failed logins.Default: 1 minute
- config_file_path
- Colon-separated list of directories which will be scanned when locating further configuration files, especially those used by plugin instances.Default: /etc/gromox/http:/etc/gromox
- context_average_mem
- Default: 256K
- context_num
- Default: 400
- data_file_path
- Colon-separated list of directories which will be scanned when locating data files.Default: /usr/share/gromox/http
- fastcgi_cache_size
- If the HTTP request to a CGI endpoint uses Chunked Transfer Encoding and the Content-Length field contains a larger value than this limit, the data is buffered in a file /tmp/http-%d (%d replaced by internal context id).Default: 256K
- fastcgi_exec_timeout
- Maximum execution time for CGI scripts.Default: 10 minutes
- fastcgi_max_size
- If the Content-Length of a HTTP request to a CGI endpoint is larger than this value, the request is rejected.Default: 4M
- host_id
- A unique identifier for this system. It is used for the Server HTTP responses header, for service plugins like exmdb_provider(4gx), which makes use of it for SMTP HELO lines, for DSN report texts, for MIDB database/EML cache. The identifier should only use characters allowed for hostnames.Default: (system hostname)
- hpm_cache_size
- If the HTTP request to a HPM endpoint uses Chunked Transfer Encoding and the Content-Length field contains a larger value than this limit, the data is buffered in a file /tmp/http-%d (%d replaced by internal context id).Default: 512K
- hpm_max_size
- If the Content-Length of a HTTP request to a HPM endpoint is larger than this value, the request is rejected.Default: 4M
- hpm_plugin_ignore_errors
- If set to yes, HTTP processing modules that fail to load on startup are ignored. If set to no, the daemon will exit if any plugin cannot be loaded.Default: no
- hpm_plugin_list
- Path to a text file which lists the filenames of HTTP processing modules (plugins) to load, one per line.Default: (built-in list)
- http_auth_times
- The number of login tries a user is allowed before the account is blocked.Default: 10
- http_certificate_passwd
- The password to unlock TLS certificates.Default: (unset)
- http_certificate_path
- Filesystem path to a certificate file for use with encrypted connection. The complete certificate chain should be present (as there is no other config directive to pull CA certs in).Default: (unset)
- http_conn_timeout
- If a HTTP connection stalls for the given period, the connection is terminated.Default: 3 minutes
- http_debug
- If set to 1, prints all incoming and outgoing HTTP traffic to stderr.Default: 0
- http_listen_addr
- AF_INET6 socket address to bind the HTTP service to.Default: ::
- http_listen_port
- The TCP port to expose the HTTP protocol service on.Default: 80
- http_listen_tls_port
- The TCP port to expose implicit-TLS HTTP protocol service (HTTPS) on.Default: (unset)
- http_private_key_path
- Filesystem path to the key file needed to unlock the TLS certificate.Default: (unset)
- http_support_tls
- This flag controls whether (or not) the server offers TLS at all. The default is false because you need a certificate for this first.Default: false
- http_thread_charge_num
- The maximum number of connections that each thread is allowed to process.Default: 20
- http_thread_init_num
- The minimum number of client processing threads to keep around.Default: 5
- proc_plugin_ignore_errors
- If set to yes, processor plugins that fail to load on startup are ignored. If set to no, the daemon will exit if any plugin cannot be loaded.Default: no
- proc_plugin_list
- Path to a text file which lists the filenames of processor plugins to load, one per line.Default: (built-in list)
- proc_plugin_path
- Filesystem path for processor plugins.Default: /usr/libexec/gromox
- request_max_mem
- The maximum hint size for fragmented RPC PDU requests that will be allowed (C706 §12.6.3.7, MS-RPCE v33 §2.2.2.6).
- tls_min_proto
- The lowest TLS version to offer. Possible values are: tls1.0, tls1.1, tls1.2, and, if supported by the system, tls1.3.Default: tls1.2
- running_identity
- An unprivileged user account to switch the process to after startup. To inhibit the switch, assign the empty value.Default: gromox
- service_plugin_ignore_errors
- If set to yes, service plugins that fail to load on startup are ignored. If set to no, the daemon will exit if any plugin cannot be loaded.Default: no
- service_plugin_list
- Path to a text file which lists the filenames of service plugins to load, one per line.Default: (built-in list)
- service_plugin_path
- Path to a secondary directory where service plugins will be loaded from if a primary search in standard directories (as per ld.so(8)) was unsuccessful.Default: /usr/lib/gromox
- state_path
- Directory for runtime variadic data.Default: /var/lib/gromox
- tcp_mss_size
- Sets the TCP_MAXSEG socket option with the given MSS value for the listening socket(s), cf. tcp(7).Default: 0 (do not limit the MSS)
- user_default_lang
- Default: en
Files¶
- /usr/lib/gromox/libgxh_*.so: HTTP processing plugins
- /usr/lib/gromox/libgxp_*.so: PDU processing plugins
- /usr/lib/gromox/libgxs_*.so: service plugins
Normative references¶
- MS-RPCE: Remote Procedure Call Protocol Extensions
- DCERPC / C706: Technical Standard DCE 1.1: Remote Procedure Call by The Open Group, 1997
See also¶
gromox(7), mod_cache(4gx), mod_fastcgi(4gx), mod_rewrite(4gx)