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, HPM plugins are invoked. Processing ends when one plugin signals that the request was handled. The order depends on the HPM plugin 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 file directives

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
console_server_ip
An IPv6 address (or v4-mapped address) to expose the management console frontend on.
Default: ::1
console_server_port
The TCP port number to expose the management console frontend on.
Default: 8899
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
default_domain

Default: (inherited from system)

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
The hostname that the server uses to identify itself (e.g. Server: header in HTTP responses).
Default: (inherited from system)
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, HPM 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
hpm_plugin_list
Path to a text file which lists the filenames of HPM plugins to load, one per line.
Default: (unspecified)
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_private_key_path
Filesystem path to the key file needed to unlock the TLS certificate.
Default: (unset)
http_support_ssl
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
listen_port
The TCP port to expose the HTTP protocol service on. (The IP address is fixed to the wildcard address.)
Default: 80
listen_ssl_port
The TCP port to expose implicit-TLS HTTP protocol service (HTTPS) on. (The IP address is fixed to the wildcard address.)
Default: (unset)
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: (unspecified)
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, RPCE §2.2.2.6).

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: (unspecified)
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)
thread_charge_num
The maximum number of connections that each thread is allowed to process.
Default: 20
thread_init_num
The minimum number of client processing threads to keep around.
Default: 5
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)