Universal Port (RIPD-160):

This changes the behavior and configuration specification of the listening
ports that rippled uses to accept incoming connections for the supported
protocols: peer (Peer Protocol), http (JSON-RPC over HTTP), https (JSON-RPC)
over HTTPS, ws (Websockets Clients), and wss (Secure Websockets Clients).
Each listening port is now capable of handshaking in multiple protocols
specified in the configuration file (subject to some restrictions). Each
port can be configured to provide its own SSL certificate, or to use a
self-signed certificate. Ports can be configured to share settings, this
allows multiple ports to use the same certificate or values. The list of
ports is dynamic, administrators can open as few or as many ports as they
like. Authentication settings such as user/password or admin user/admin
password (for administrative commands on RPC or Websockets interfaces) can
also be specified per-port.

As the configuration file has changed significantly, administrators will
need to update their ripple.cfg files and carefully review the documentation
and new settings.

Changes:

* rippled-example.cfg updated with documentation and new example settings:
  All obsolete websocket, rpc, and peer configuration sections have been
  removed, the documentation updated, and a new documented set of example
  settings added.

* HTTP::Writer abstraction for sending HTTP server requests and responses
* HTTP::Handler handler improvements to support Universal Port
* HTTP::Handler handler supports legacy Peer protocol handshakes
* HTTP::Port uses shared_ptr<boost::asio::ssl::context>
* HTTP::PeerImp and Overlay use ssl_bundle to support Universal Port
* New JsonWriter to stream message and body through HTTP server
* ServerHandler refactored to support Universal Port and legacy peers
* ServerHandler Setup struct updated for Universal Port
* Refactor some PeerFinder members
* WSDoor and Websocket code stores and uses the HTTP::Port configuration
* Websocket autotls class receives the current secure/plain SSL setting
* Remove PeerDoor and obsolete Overlay peer accept code
* Remove obsolete RPCDoor and synchronous RPC handling code
* Remove other obsolete classes, types, and files
* Command line tool uses ServerHandler Setup for port and authorization info
* Fix handling of admin_user, admin_password in administrative commands
* Fix adminRole to check credentials for Universal Port
* Updated Overlay README.md

* Overlay sends IP:port redirects on HTTP Upgrade peer connection requests:
  Incoming peers who handshake using the HTTP Upgrade mechanism don't get
  a slot, and always get HTTP Status 503 redirect containing a JSON
  content-body with a set of alternate IP and port addresses to try, learned
  from PeerFinder. A future commit related to the Hub and Spoke feature will
  change the response to grant the peer a slot when there are peer slots
  available.

* HTTP responses to outgoing Peer connect requests parse redirect IP:ports:
  When the [overlay] configuration section (which is experimental) has
  http_handshake = 1, HTTP redirect responses will have the JSON content-body
  parsed to obtain the redirect IP:port addresses.

* Use a single io_service for HTTP::Server and Overlay:
  This is necessary to allow HTTP::Server to pass sockets to and from Overlay
  and eventually Websockets. Unfortunately Websockets is not so easily changed
  to use an externally provided io_service. This will be addressed in a future
  commit, and is one step necessary ease the restriction on ports configured
  to offer Websocket protocols in the .cfg file.

doc/rippled-example.cfg

@@ -6,23 +6,23 @@
 #
 # Contents
 #
-#   1. Peer Networking
+#   1. Server
 #
-#   2. Websocket Networking
+#   2. Peer Protocol
 #
-#   3. RPC Networking
+#   3. SMS Gateway
 #
-#   4. SMS Gateway
+#   4. Ripple Protocol
 #
-#   5. Ripple Protocol
+#   5. HTTPS Client
 #
-#   6. HTTPS Client
+#   6. Database
 #
-#   7. Database
+#   7. Diagnostics
 #
-#   8. Diagnostics
+#   8. Voting
 #
-#   9. Voting
+#   9. Example Settings
 #
 #-------------------------------------------------------------------------------
 #
@@ -83,15 +83,196 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 1. Peer Networking
+# 1. Server
 #
-#-------------------
+#----------
+#
+#
+#
+#   rippled offers various server protocols to clients making inbound
+#   connections. The listening ports rippled uses are "universal" ports
+#   which may be configured to handshake in one or more of the available
+#   supported protocols. These universal ports simplify administration:
+#   A single open port can be used for multiple protocols.
+#
+#   NOTE    At least one server port must be defined in order
+#           to accept incoming network connections.
+#
+#
+# [server]
+#
+#   A list of port names and key/value pairs. A port name must start with a
+#   letter and contain only letters and numbers. The name is not case-sensitive.
+#   For each name in this list, rippled will look for a configuration file
+#   section with the same name and use it to create a listening port. The
+#   name is informational only; the choice of name does not affect the function
+#   of the listening port.
+#
+#   Key/value pairs specified in this section are optional, and apply to all
+#   listening ports unless the port overrides the value in its section. They
+#   may be considered default values.
+#
+#   Suggestion:
+#
+#       To avoid a conflict with port names and future configuration sections,
+#       we recommend prepending "port_" to the port name. This prefix is not
+#       required, but suggested.
+#
+#   This example defines two ports with different port numbers and settings:
+#
+#       [server]
+#       port_public
+#       port_private
+#       port = 80
+#
+#       [port_public]
+#       ip=0.0.0.0
+#       port = 443
+#       protocol=peer,https
+#
+#       [port_private]
+#       ip=127.0.0.1
+#       protocol=http
+#
+#   When rippled is used as a command line client (for example, issuing a
+#   server stop command), the first port advertising the http or https 
+#   protocol will be used to make the connection.
+#
+#
+#
+# [<name>]
+#
+#   A series of key/value pairs that define the settings for the port with
+#   the corresponding name. These keys are possible:
+#
+#   ip = <IP-address>
+#
+#       Required. Determines the IP address of the network interface to bind
+#       to. To bind to all available interfaces, uses 0.0.0.0
+#
+#   port = <number>
+#
+#       Required. Sets the port number to use for this port.
+#
+#   protocol = [ http, https, peer ]
+#
+#       Required. A comma-separated list of protocols to support:
+#
+#       http        JSON-RPC over HTTP
+#       https       JSON-RPC over HTTPS
+#       ws          Websockets
+#       wss         Secure Websockets
+#       peer        Peer Protocol
+#
+#       Restrictions:
+#   
+#       Only one port may be configured to support the peer protocol.
+#       A port cannot have websocket and non websocket protocols at the
+#       same time. It is possible have both Websockets and Secure Websockets
+#       together in one port.
+#
+#       NOTE    If no ports support the peer protocol, rippled cannot
+#               receive incoming peer connections or become a superpeer.
+#
+#   user = <text>
+#   password = <text>
+#
+#       When set, these credentials will be required on HTTP/S requests.
+#       The credentials must be provided using HTTP's Basic Authentication
+#       headers. If either or both fields are empty, then no credentials are
+#       required. IP address restrictions, if any, will be checked in addition
+#       to the credentials specified here.
+#
+#       When acting in the client role, rippled will supply these credentials
+#       using HTTP's Basic Authentication headers when making outbound HTTP/S
+#       requests.
+#
+#   admin = no | allow
+#
+#       Controls whether or not administrative commands are allowed. These
+#       commands may be issued over http, https, ws, or wss if configured
+#       on the port. If unspecified, the default is to not allow
+#       administrative commands.
+#
+#   admin_user = <text>
+#   admin_password = <text>
+#
+#       When set, clients must provide these credentials in the submitted
+#       JSON for any administrative command requests submitted to the HTTP/S,
+#       WS, or WSS protocol interfaces. If administrative commands are
+#       disabled for a port, these credentials have no effect.
+#
+#       When acting in the client role, rippled will supply these credentials
+#       in the submitted JSON for any administrative command requests when
+#       invoking JSON-RPC commands on remote servers.
+#
+#   ssl_key = <filename>
+#   ssl_cert = <filename>
+#   ssl_chain = <filename>
+#
+#       Use the specified files when configuring SSL on the port.
+#
+#       NOTE    If no files are specified and secure protocols are selected,
+#               rippled will generate an internal self-signed certificate.
+#
+#       The files have these meanings:
+#
+#       ssl_key
+#
+#           Specifies the filename holding the SSL key in PEM format.
+#
+#       ssl_cert
+#
+#           Specifies the path to the SSL certificate file in PEM format.
+#           This is not needed if the chain includes it.
+#
+#       ssl_chain
+#
+#           If you need a certificate chain, specify the path to the
+#           certificate chain here. The chain may include the end certificate.
+#
+#
+#
+# [rpc_admin_allow]
+#
+#   Specify a list of IP addresses allowed to have admin access. One per line.
+#   If you want to test the output of non-admin commands add this section and
+#   just put an ip address not under your control.
+#   Defaults to 127.0.0.1.
+#
+#
+#
+# [rpc_startup]
+#
+#   Specify a list of RPC commands to run at startup.
+#
+#   Examples:
+#     { "command" : "server_info" }
+#     { "command" : "log_level", "partition" : "ripplecalc", "severity" : "trace" }
+#
+#
+#
+# [websocket_ping_frequency]
+#
+#   <number>
+#
+#   The amount of time to wait in seconds, before sending a websocket 'ping'
+#   message. Ping messages are used to determine if the remote end of the
+#   connection is no longer available.
+#   
+#
+#
+#-------------------------------------------------------------------------------
+#
+# 2. Peer Protocol
+#
+#-----------------
 #
 #   These settings control security and access attributes of the Peer to Peer
-#   server section of the rippled process. Peer Networking implements the
+#   server section of the rippled process. Peer Protocol implements the
 #   Ripple Payment protocol. It is over peer connections that transactions
-#   and validations are passed from to machine to machine, to make up the
-#   components of closed ledgers.
+#   and validations are passed from to machine to machine, to determine the
+#   contents of validated ledgers.
 #
 #
 #
@@ -130,21 +311,6 @@
 #
 #
 #
-# [peer_ip]
-#
-#   IP address or domain to bind to allow external connections from peers.
-#   Defaults to not binding, which disallows external connections from peers.
-#
-#   Examples: 0.0.0.0 - Bind on all interfaces.
-#
-#
-#
-# [peer_port]
-#
-#   If peer_ip is supplied, corresponding port to bind to for peer connections.
-#
-#
-#
 # [peer_private]
 #
 #   0 or 1.
@@ -238,243 +404,7 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 2. Websocket Networking
-#
-#------------------------
-#
-#   These settings control security and access attributes of the Websocket
-#   server section of the rippled process, primarily used to service
-#   client requests and backend applications.
-#
-#
-#
-# [websocket_public_ip]
-#
-#   IP address or domain to bind to allow untrusted connections from clients.
-#   In the future, this option will go away and the peer_ip will accept
-#   websocket client connections.
-#
-#   Examples: 0.0.0.0 - Bind on all interfaces.
-#             127.0.0.1 - Bind on localhost interface.  Only local programs may connect.
-#
-#
-#
-# [websocket_public_port]
-#
-#   Port to bind to allow untrusted connections from clients.  In the future,
-#   this option will go away and the peer_ip will accept websocket client
-#   connections.
-#
-#
-#
-# [websocket_public_secure]
-#
-#   0, 1 or 2.
-#   0: Provide ws service for websocket_public_ip/websocket_public_port.
-#   1: Provide both ws and wss service for websocket_public_ip/websocket_public_port. [default]
-#   2: Provide wss service only for websocket_public_ip/websocket_public_port.
-#
-#   Browser pages like the Ripple client will not be able to connect to a secure
-#   websocket connection if a self-signed certificate is used.  As the Ripple
-#   reference client currently shares secrets with its server, this should be
-#   enabled.
-#
-#
-#
-# [websocket_ping_frequency]
-#
-#   <number>
-#
-#   The amount of time to wait in seconds, before sending a websocket 'ping'
-#   message. Ping messages are used to determine if the remote end of the
-#   connection is no longer available.
-#   
-#
-#
-# [websocket_ip]
-#
-#   IP address or domain to bind to allow trusted ADMIN connections from backend
-#   applications.
-#
-#   Examples: 0.0.0.0 - Bind on all interfaces.
-#             127.0.0.1 - Bind on localhost interface.  Only local programs may connect.
-#
-#
-#
-# [websocket_port]
-#
-#   Port to bind to allow trusted ADMIN connections from backend applications.
-#
-#
-#
-# [websocket_secure]
-#
-#   0, 1, or 2.
-#   0: Provide ws service only for websocket_ip/websocket_port. [default]
-#   1: Provide ws and wss service for websocket_ip/websocket_port
-#   2: Provide wss service for websocket_ip/websocket_port.
-#
-#
-#
-# [websocket_ssl_cert]
-#
-#   Specify the path to the SSL certificate file in PEM format.
-#   This is not needed if the chain includes it.
-#
-#
-#
-# [websocket_ssl_chain]
-#
-#   If you need a certificate chain, specify the path to the certificate chain
-#   here.  The chain may include the end certificate.
-#
-#
-#
-# [websocket_ssl_key]
-#
-#   Specify the filename holding the SSL key in PEM format.
-#
-#
-#
-#-------------------------------------------------------------------------------
-#
-# 3. RPC Networking
-#
-#------------------
-#
-#   This group of settings configures security and access attributes of the
-#   RPC server section of the rippled process, used to service both local
-#   and optional remote clients.
-#
-#
-#
-# [rpc_allow_remote]
-#
-#   0 or 1.
-#
-#   0: Allow RPC connections only from 127.0.0.1. [default]
-#   1: Allow RPC connections from any IP.
-#
-#
-#
-# [rpc_admin_allow]
-#
-#   Specify a list of IP addresses allowed to have admin access. One per line.
-#   If you want to test the output of non-admin commands add this section and
-#   just put an ip address not under your control.
-#   Defaults to 127.0.0.1.
-#
-#
-#
-# [rpc_admin_user]
-#
-#   As a server, require this as the admin user to be specified.  Also, require
-#   rpc_admin_user and rpc_admin_password to be checked for RPC admin functions.
-#   The request must specify these as the admin_user and admin_password in the
-#   request object.
-#
-#   As a client, supply this to the server in the request object.
-#
-#
-#
-# [rpc_admin_password]
-#
-#   As a server, require this as the admin password to be specified.  Also,
-#   require rpc_admin_user and rpc_admin_password to be checked for RPC admin
-#   functions.  The request must specify these as the admin_user and
-#   admin_password in the request object.
-#
-#   As a client, supply this to the server in the request object.
-#
-#
-#
-# [rpc_ip]
-#
-#   IP address or domain to bind to allow insecure RPC connections.
-#   Defaults to not binding, which disallows RPC connections.
-#
-#
-#
-# [rpc_port]
-#
-#   If rpc_ip is supplied, corresponding port to bind to for peer connections.
-#
-#
-#
-# [rpc_user]
-#
-#   As a server, require this user to be specified and require rpc_password to
-#   be checked for RPC access via the rpc_ip and rpc_port. The user and password
-#   must be specified via HTTP's basic authentication method.
-#   As a client, supply this to the server via HTTP's basic authentication
-#   method.
-#
-#
-#
-# [rpc_password]
-#
-#   As a server, require this password to be specified and require rpc_user to
-#   be checked for RPC access via the rpc_ip and rpc_port. The user and password
-#   must be specified via HTTP's basic authentication method.
-#   As a client, supply this to the server via HTTP's basic authentication
-#   method.
-#
-#
-#
-# [rpc_startup]
-#
-#   Specify a list of RPC commands to run at startup.
-#
-#   Examples:
-#     { "command" : "server_info" }
-#     { "command" : "log_level", "partition" : "ripplecalc", "severity" : "trace" }
-#
-#
-#
-# [rpc_secure]
-#
-#   0 or 1.
-#
-#   0: Server certificates are not provided for RPC clients using SSL [default]
-#   1: Client RPC connections wil be provided with SSL certificates.
-#
-#   Note that if rpc_secure is enabled, it will also be necessary to configure
-#   the certificate file settings located in rpc_ssl_cert, rpc_ssl_chain, and
-#   rpc_ssl_key
-#
-#
-#
-# [rpc_ssl_cert]
-#
-#   <pathname>
-#
-#   A file system path leading to the SSL certificate file to use for secure
-#   RPC.  The file is in PEM format. The file is not needed if the chain
-#   includes it.
-#
-#
-#
-# [rpc_ssl_chain]
-#
-#   <pathname>
-#
-#   A file system path leading to the file with the certificate chain.
-#   The chain may include the end certificate.
-#
-#
-#
-# [rpc_ssl_key]
-#
-#   <pathname>
-#
-#   A file system path leading to the file with the SSL key.
-#   The file is in PEM format.
-#
-#
-#
-#-------------------------------------------------------------------------------
-#
-# 4. SMS Gateway
+# 3. SMS Gateway
 #
 #---------------
 #
@@ -510,7 +440,7 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 5. Ripple Protocol
+# 4. Ripple Protocol
 #
 #-------------------
 #
@@ -654,7 +584,7 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 6. HTTPS Client
+# 5. HTTPS Client
 #
 #----------------
 #
@@ -694,7 +624,7 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 7. Database
+# 6. Database
 #
 #------------
 #
@@ -767,7 +697,7 @@
 #
 #-------------------------------------------------------------------------------
 #
-# 8. Diagnostics
+# 7. Diagnostics
 #
 #---------------
 #
@@ -823,7 +753,7 @@
 #   
 #-------------------------------------------------------------------------------
 #
-# 9. Voting
+# 8. Voting
 #
 #----------
 #
@@ -873,41 +803,84 @@
 #           owner_reserve = 5000000      # 5 XRP
 #
 #-------------------------------------------------------------------------------
-
-# Allow other peers to connect to this server.
 #
-[peer_ip]
-0.0.0.0
-
-[peer_port]
-51235
-
-# Allow untrusted clients to connect to this server.
+# 9. Example Settings
 #
-[websocket_public_ip]
-0.0.0.0
-
-[websocket_public_port]
-5006
-
-# Provide trusted websocket ADMIN access to the localhost.
+#--------------------
 #
-[websocket_ip]
-127.0.0.1
-
-[websocket_port]
-6006
-
-# Provide trusted json-rpc ADMIN access to the localhost.
+#   Administrators can use these values as a starting poing for configuring
+#   their instance of rippled, but each value should be checked to make sure
+#   it meets the business requirements for the organization.
 #
-[rpc_ip]
-127.0.0.1
+# Server
+#
+#   These example configuration settings create these ports:
+#
+#   "peer"
+#
+#       Peer protocol open to everyone. This is required to accept
+#       incoming rippled connections. This does not affect automatic
+#       or manual outgoing Peer protocol connections.
+#
+#   "rpc"
+#
+#       Administrative RPC commands over HTTPS, when originating from
+#       the same machine (via the loopback adapter at 127.0.0.1).
+#
+#   "wss_admin"
+#
+#       Admin level API commands over Secure Websockets, when originating
+#       from the same machine (via the loopback adapter at 127.0.0.1).
+#
+#   This port is commented out but can be enabled by removing
+#   the '#' from each corresponding line including the entry under [server]
+#
+#   "wss_public"
+#
+#       Guest level API commands over Secure Websockets, open to everyone.
+#   
+#   For HTTPS and Secure Websockets ports, if no certificate and key file
+#   are specified then a self-signed certificate will be generated on startup.
+#   If you have a certificate and key file, uncomment the corresponding lines
+#   and ensure the paths to the files are correct.
+#
+#   NOTE
+#
+#       To accept connections on well known ports such as 80 (HTTP) or
+#       443 (HTTPS), most operating systems will require rippled to
+#       run with administrator privileges, or else rippled will not start.
 
-[rpc_port]
-5005
+[server]
+port_rpc
+port_peer
+port_wss_admin
+#port_ws_public
+#ssl_key = /etc/ssl/private/server.key
+#ssl_cert = /etc/ssl/certs/server.crt
 
-[rpc_allow_remote]
-0
+[port_rpc]
+port = 5005
+ip = 127.0.0.1
+admin = allow
+protocol = https
+
+[port_peer]
+port = 51235
+ip = 0.0.0.0
+protocol = peer
+
+[port_wss_admin]
+port = 6006
+ip = 127.0.0.1
+admin = allow
+protocol = wss
+
+#[port_ws_public]
+#port = 5005
+#ip = 127.0.0.1
+#protocol = wss
+
+#-------------------------------------------------------------------------------
 
 [node_size]
 medium
@@ -962,22 +935,7 @@ n9LdgEtkmGB9E2h3K4Vp7iGUaKuq23Zr32ehxiU8FWY7xoxbWTSA    RL5
 [rpc_startup]
 { "command": "log_level", "severity": "warning" }
 
-# Configure SSL for WebSockets.  Not enabled by default because not everybody
-# has an SSL cert on their server, but if you uncomment the following lines and
-# set the path to the SSL certificate and private key the WebSockets protocol
-# will be protected by SSL/TLS.
-#[websocket_secure]
-#1
-
-#[websocket_ssl_cert]
-#/etc/ssl/certs/server.crt
-
-#[websocket_ssl_key]
-#/etc/ssl/private/server.key
-
 # Defaults to 0 ("no") so that you can use self-signed SSL certificates for
 # development, or internally.
 #[ssl_verify]
 #0
-
-