Network listeners and their services are specified via configuration.
<listeners> <sslconfig> <optional_no_ca>false</optional_no_ca> <certificate_file>/path/to/server.crt</certificate_file> <key_file>/path/to/server.key</key_file> <ca_chain>/path/to/ca.crt</ca_chain> <layer>tlsv1:all,!sslv2,!sslv3,cipher_server_preference</layer> <ciphers>EECDH+AES128+AESGCM:EDH+AES128+AESGCM:!DSS</ciphers> </sslconfig> <consoles type="mtev_console" require_env="MTEV_CONTROL"> <listener address="127.0.0.1" port="32322"> <config> <line_protocol>telnet</line_protocol> </config> </listener> </consoles> <web type="control_dispatch" address="*"> <config> <document_root>/path/to/docroot</document_root> </config> <listener port="80" /> <listener port="443" ssl="on" /> </web> </listeners>
This example demonstrates many powerful concepts of the libmtev configuration system.
There are three listener stanzas nested above and we'll walk through each. The first
<listener address="127.0.0.1" port="32322">. With this, you can telnet to
127.0.0.1 port 32322 and talk with your libmtev application. The console is extensible
so you can add application-specific command, control, and interrogation capabilities.
This listener has a
<config> stanza underneath it that sets
line_protocol is a configuration option for listeners of type
note that the listener's
type attribute was actually set in a parent node. Most
systems in libmtev will recusively merge from ancestors down to the a specimen node
and use that result. Here
type is simply an attribute, so merging is just replacing.
This node also has an
sslconfig, but it doesn't use it, so we'll ignore that for now.
require_env attribute requires the
MTEV_CONTROL environment variable to be set
for this listener to be active; if unspecified, it is active.
The next two listener stanzas are for port 80 and 443. They are in a
web node that has
address attributes set (those are inherited by the listeners). The
config node (child of
web) and the
sslconfig node (child of
listeners) are also
inherited into the
listener nodes. The
config is arbitrary and passed into the listener.
sslconfig is passed into the ssl subsystem and is uniform across all listener types.
The following attributes are supported for listeners:
The type of listener simply references a named eventer callback in the system (one registered with
eventer_name_callback(...). libmtev support four built-in listener types:
mtev_console. Applications can arbitrarily extend the system by naming callbacks.
This optionally requires conditions around an environment variable. See
The address is either a filesystem path (AF_UNIX), an IPv4 address or an IPv6 address. The type is intuited from the input string. If the special string
inet:*is used, then the IPv4
in_addr_anyaddress is used for listening. IF
inet6:*is used, then the IPv6
in_addr_anyaddress is used for listening.
Specifies the port on which to listen. This has no meaning for AF_UNIX-based addresses.
If the value here is
on, then the socket passes through SSL negotiation before handed to the underlying system driving the specified listener type.
If the value here is
on, the new events created for accepted connections will be fanned out across threads in the event pool owning the listening socket (usually the default event pool). A different pool can be selected by additionally supplying
on, this will select a named pool on which to distribute new connection events. The value of this attribute should be the name of an event pool. If not pool exists with the specified name, the pool containing the listening event will be used.
on, a new dedicated thread will be spawned to handle accepting new connections in a blocking fashion.
The ssl config allow specification of many aspects of how SSL is negotiated with connecting clients. SSL config supports the follwing keys:
This specifies the SSL protocol options we present and is the form
<protocol>[:<option>,[<option>[,...]]]. Options may be negated with an antecedent
!. Tokens are matched case-insensitively.
Protocols supported (depending on openssl):
Options supported (depending on openssl):
The default layer string is
Specifies the path to a PEM encoded certificate file.
Specifies the path to a PEM encoded key file. It must not be encrypted with a password.
Specifies the CA chaing file (PEM encoded) that should be used to validate client supplied certificates.
Specifies a PEM encoded certificate revocation list file. If not specified, no revocation is enforced.
Specifies which ciphers should be supported, expressed in the OpenSSL cipher list format. Check the OpenSSL manual for more details. If not specified, the default ciphers supported by the OpenSSL library are used.
Specifies which NPN (next-protocol-negotiation) to offer. If omitted,
h2is used and the http2 protocol is exposed. Specifying
nonewill disable this NPN registration.
Each listener can access the
config passed to it; see type-specific documentation.