diff --git a/README.md b/README.md index e6dd84c1d..6aad98e73 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Features * Automatic fallback to normal userspace operation if kernel module is unavailable * Support for *Kamailio*'s *rtpproxy* module * Legacy support for old *OpenSER* *mediaproxy* module +* HTTP, HTTPS, and WebSocket (WS and WSS) interfaces When used through the *rtpengine* module (or its older counterpart called *rtpproxy-ng*), the following additional features are available: @@ -1860,3 +1861,47 @@ command. Sample return dictionary: }, "result": "ok" } + +HTTP/WebSocket support +====================== + +If enabled in the config, *rtpengine* can handle requests made to it via HTTP, +HTTPS, or WebSocket (WS or WSS) connections. The supported HTTP URIs and +WebSocket subprotocols are described below. + +Dummy Test Interfaces +--------------------- + +For HTTP and HTTPS, the URI `/ping` is provided, which simply responds with +`pong` if requested via `GET`. For WebSockets, the subprotocol +`echo.rtpengine.com` is provided, which simply echoes back any messages that +are sent to it. + +CLI Interface +------------- + +This interface supports the same commands as the CLI tool `rtpengine-ctl` that +comes packaged with `rtpengine`. For HTTP and HTTPS, the command is appended to +the URI base `/cli/` and the request is made via `GET`, with spaces replaced by +plus signs as required by HTTP (e.g. `GET /cli/list+totals`). For WebSockets, +the subprotocol is `cli.rtpengine.com` and each WebSocket message corresponds +to one CLI command and produces one message in response. The format of each +response is exactly the same as produced by the CLI tool `rtpengine-ctl` and +therefore meant for plain text representation. + +*ng* Protocol Interface +----------------------- + +This interface can be used to send and receive *ng* protocol messages over HTTP +or WebSocket connections instead of plain UDP. + +For HTTP and HTTPS, the URI `/ng` is used, with the request being made by +`POST` and the content-type set to `application/x-rtpengine-ng`. The message +body must be in the same format as the body of an UDP-based *ng* message and +must therefore consist of a unique cookie string, followed by a single space, +followed by the message in *bencode* format. Likewise, the response will be in +the same format, including the unique cookie. + +For WebSockets, the subprotocol `ng.rtpengine.com` is used and the protocol +follows the same format. Messages must consist of a unique cookie and a string +in bencode format, and responses will also be in the same format. diff --git a/daemon/rtpengine.pod b/daemon/rtpengine.pod index 006112985..4248c5f41 100644 --- a/daemon/rtpengine.pod +++ b/daemon/rtpengine.pod @@ -694,6 +694,33 @@ tags, etc are recorded to the log. Every RTCP packet is logged in this way, while every 512th RTP packet is logged. Only applies to packets forwarded/processed in userspace. +=item B<--listen-http=>[I|IB<:>]I + +=item B<--listen-https=>[I|IB<:>]I + +Enable listening for HTTP or WebSocket connections, or their TLS-secured +counterparts HTTPS and WSS. If no interface is specified, then the listening +socket will be bound to all interfaces. + +The HTTP listener supports both HTTP and WS, while the HTTPS listener supports +both HTTPS and WSS. + +If HTTPS/WSS is enabled, a certificate must also be provided using the options +below. + +=item B<--https-cert=>I + +=item B<--https-key=>I + +Provide a server certificate and corresponding private key for the HTTPS/WSS +listener, in PEM format. + +=item B<--http-threads=>I + +Number of worker threads for HTTP/HTTPS/WS/WSS. If not specified, then the same +number as given under B will be used. If no HTTP listeners are +enabled, then no threads are created. + =back =head1 INTERFACES