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)