Table of Contents
This document describes an embedded basic web server that can deliver static and Common Gateway Interface (CGI) dynamic content to a web client, commonly a browser. Due to the limitations of this web server, and/or of its configuration capabilities, a proxy server is recommended to address special requirements. An Nginx example is attached and described as a basic template for such a proxy server.
The web server can be configured through settings in confd.conf - see the manual pages of the section called “CONFIGURATION PARAMETERS” .
Here is a brief overview of what you can configure on the web server:
"toggle web server": the web server can be turned on or off
"toggle transport": enable HTTP and/or HTTPS, set IPs, ports, redirects, certificates, etc.
"hostname": set the hostname of the web server and decide whether to block requests for other hostnames
"/": set the docroot from where all static content is served
"/login": set the docroot from where static content is served for URL paths starting with /login
"/custom": set the docroot from where static content is served for URL paths starting with /custom
"/cgi": toggle CGI support and set the docroot from where dynamic content is served for URL paths starting with /cgi
"non-authenticated paths": by default all URL paths, except those needed for the login page are hidden from non-authenticated users; authentication is done by calling the JSONRPC "login" method
"allow symlinks": allow symlinks from under the docroot
"cache": set the cache time window for static content
"log": several logs are available to configure in terms of file paths - an access log, a full HTTP traffic/trace log and a browser/JavaScript log
"custom headers": set custom headers across all static and dynamic content, including requests to "/jsonrpc".
In addition to what is configurable, the web server also GZip-compresses responses automatically if the browser handles such responses, either by compressing the response on the fly, or, if requesting a static file, like "/bigfile.txt", by responding with the contents of "/bigfile.txt.gz", if there is such a file.
The web server includes CGI functionality, disabled by default. Once you enable it in confd.conf - see the manual pages of the section called “CONFIGURATION PARAMETERS” , you can write CGI scripts, that will be called with the following ConfD environment variables prefixed with CONFD_ when a user has logged-in via JSON-RPC:
"JSONRPC_SESSIONID": the JSON-RPC session id (cookie)
"JSONRPC_START_TIME": the start time of the JSON-RPC session
"JSONRPC_END_TIME": the end time of the JSON-RPC session
"JSONRPC_READ": the latest JSON-RPC read transaction
"JSONRPC_READS": a comma-separated list of JSON-RPC read transactions
"JSONRPC_WRITE": the latest JSON-RPC write transaction
"JSONRPC_WRITES": a comma-separated of JSON-RPC write transactions
"MAAPI_USER": the MAAPI username
"MAAPI_GROUPS": a comma-separated list of MAAPI groups
"MAAPI_UID": the MAAPI UID
"MAAPI_GID": the MAAPI GID
"MAAPI_SRC_IP": the MAAPI source IP address
"MAAPI_SRC_PORT": the MAAPI source port
"MAAPI_USID": the MAAPI USID
"MAAPI_READ": the latest MAAPI read transaction
"MAAPI_READS": a comma-separated list of MAAPI read transactions
"MAAPI_WRITE": the latest MAAPI write transaction
"MAAPI_WRITES": a comma-separated of MAAPI write transactions
Server or HTTP specific information is also exported as environment variables:
"SERVER_SOFTWARE":
"SERVER_NAME":
"GATEWAY_INTERFACE":
"SERVER_PROTOCOL":
"SERVER_PORT":
"REQUEST_METHOD":
"REQUEST_URI":
"DOCUMENT_ROOT":
"DOCUMENT_ROOT_MOUNT":
"SCRIPT_FILENAME":
"SCRIPT_TRANSLATED":
"PATH_INTO":
"PATH_TRANSLATED":
"SCRIPT_NAME":
"REMOTE_ADDR":
"REMOTE_HOST":
"SERVER_ADDR":
"LOCAL_ADDR":
"QUERY_STRING":
"CONTENT_TYPE":
"CONTENT_LENGTH":
"HTTP_*": HTTP headers e.g. "Accept" value is exported as HTTP_ACCEPT
In various scenarios, the web server has to be tweaked for performance, security or just browser-compatibility purposes. Such fine-grained tweaks are not considered with the embedded web server, and should be handled by installing a so called reverse-proxy to handle these fine requirements, while forwarding some requests to the embedded web server, either for retrieving static or dynamic content, either for accessing the JSONRPC or REST API.
Under examples.confd/nginx-proxy , there is a basic configuration for setting up Nginx as a reverse proxy.
This configuration has been tested with nginx 1.6.2 and higher.
Common configurations have been set to sensible defaults for performance and security, but keep in mind that this is not intended as an out-of-the-box production configuration.
A quick way to test this is by starting a ConfD example on the default port (i.e. 8008 ) and running "make nginx" from within the examples.confd/nginx-proxy folder. You should now be able to open your browser at "http://localhost:8090", and interact with the running example, although traffic will be routed via the nginx proxy.
The nginx configuration file starts within the examples.confd/nginx-proxy /nginx/nginx.conf file. A number of configurations have been enabled for a development environment only, marked with "DEV ONLY" in order to enable easy debugging in the CLI. Similarly, some configurations are marked with "CHANGEME" to denote the most important configurations that you should adapt to your environment, if you will start using this configuration as a base for a production-quality nginx configuration.
Under the examples.confd/nginx-proxy /nginx/conf.d folder there are modular configurations. Some of them are not enabled by default in "nginx.conf" such as "sec.cors.conf" which enables Cross-Origin Resource Sharing on your server.