http(8gx)

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 (which is fixed): ews, mh_emsmdb, mh_nsp, oxdisco, oab.

•   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 has a HTTP body larger than the limit given here, the data is buffered in a file rather than kept in memory. If the request uses Chunked Transfer Encoding, a file is used unconditionally.
    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 or 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

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 connections. 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_log_file
    Target for log messages here. Special values: "-" (stderr/syslog depending on parent PID) or "syslog" are recognized.
    Default: - (auto)

http_log_level
    Maximum verbosity of logging. 1=crit, 2=error, 3=warn, 4=notice, 5=info, 6=debug.
    Default: 4 (notice)

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

msrpc_debug
    Log every completed RPC call and the return code of the operation in a minimal fashion to stderr. Level 1 emits RPCs with a failure return code, level 2 emits all RPCs. Note the daemon log level needs to be "debug" (6), too.
    Default: 0

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

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)