MT#55897 Restructure general README.md

We have to restructure project's general README.md
in order to make all recently added documentation sources
(including RTD) be compliant and let it look centralized and
good organized.

The root of the repository still has the README.md, but
it only shows general summary on the project and then gives
links to the extended documentation sources:
- RTD stored
- GitHub stored

Change-Id: Ief160669432ecb3e22df16d9278df863da995991

docs/call_recording.md

@@ -0,0 +1,9 @@
+# Call Recording
+
+Call recording can be accomplished in one of two ways: 
+
+* The *rtpengine* daemon can write `libpcap`-formatted captures directly (`--recording-method=pcap`);
+
+* The *rtpengine* daemon can write audio frames into a sink in `/proc/rtpengine` (`--recording-method=proc`). These frames must then be consumed within a short period by another process; while this can be any process, the packaged `rtpengine-recording` daemon is a useful ready implementation of a call recording solution. The recording daemon uses `ffmpeg` libraries to implement a variety of on-the-fly format conversion and mixing options, as well as metadata logging. See `rtpengine-recording -h` for details.
+
+**Important note**: The *rtpengine* daemon emits data into a "spool directory" (`--recording-dir` option), by default `/var/spool/rtpengine`. The recording daemon is then configured to consume this using the `--spool-dir` option, and to store the final emitted recordings (in whatever desired target format, etc.) in `--output-dir`. Ensure that the `--spool-dir` and the `--output-dir` are **different** directories, or you will run into problems (as discussed in [#81](https://github.com/sipwise/rtpengine/issues/808)).

docs/compiling_and_installing.md

@@ -0,0 +1,138 @@
+# Compiling and Installing
+
+## Package Repositories
+
+Prebuilt packages for some newer releases of Debian are available on [this repository](https://dfx.at/rtpengine)
+
+## Compiling on a Debian System
+
+On a Debian system, everything can be built and packaged into Debian packages
+by executing `dpkg-buildpackage` (which can be found in the `dpkg-dev` package) in the main directory.
+This script will issue an error and stop if any of the dependency packages are
+not installed. The script `dpkg-checkbuilddeps` can be used to check missing dependencies.
+(See the note about G.729 at the end of this section.)
+
+This will produce a number of `.deb` files, which can then be installed using the
+`dpkg -i` command.
+
+The generated files are (with version 6.2.0.0 being built on an amd64 system):
+
+* `ngcp-rtpengine_6.2.0.0+0~mr6.2.0.0_all.deb`
+
+	This is a meta-package, which doesn't contain or install anything on its own, but rather
+	only depends on the other packages to be installed. Not strictly necessary to be installed.
+
+* `ngcp-rtpengine-daemon_6.2.0.0+0~mr6.2.0.0_amd64.deb`
+
+	This installed the userspace daemon, which is the main workhorse of rtpengine. This is
+	the minimum requirement for anything to work.
+
+* `ngcp-rtpengine-iptables_6.2.0.0+0~mr6.2.0.0_amd64.deb`
+
+	Installs the plugin for `iptables` and `ip6tables`. Necessary for in-kernel operation.
+
+* `ngcp-rtpengine-kernel-dkms_6.2.0.0+0~mr6.2.0.0_all.deb`
+
+	Kernel module, DKMS version of the package. Recommended for in-kernel operation. The kernel
+	module will be compiled against the currently running kernel using DKMS.
+
+* `ngcp-rtpengine-kernel-source_6.2.0.0+0~mr6.2.0.0_all.deb`
+
+	If DKMS is unavailable or not desired, then this package will install the sources for the kernel
+	module for manual compilation. Required for in-kernel operation, but only if the DKMS package
+	can't be used.
+
+* `ngcp-rtpengine-recording-daemon_6.2.0.0+0~mr6.2.0.0_amd64.deb`
+
+	Optional separate userspace daemon used for call recording features.
+
+* `-dbg...` or `-dbgsym...` packages
+
+	Debugging symbols for the various components. Optional.
+
+For transcoding purposes, Debian provides an additional package `libavcodec-extra` to replace
+the regular `libavcodec` package. It is recommended to install this extra package to offer support
+for additional codecs.
+
+To support the G.729 codec for transcoding purposes, the external library *bcg729* is required. Please
+see the section on *G.729 support* below for details.
+
+## Manual Compilation
+
+There are 3 main parts to *rtpengine* plus one optional component, which can be
+found in the respective subdirectories. Running `make` on the top source
+directory will build all parts. Running `make check` additionally will run the
+test suite.
+
+* `daemon`
+
+	The userspace daemon and workhorse, minimum requirement for anything to work. Running `make`
+	will compile the binary, which will be called `rtpengine`. The following software packages
+	including their development headers are required to compile the daemon:
+
+	- *pkg-config*
+	- *GLib* including *GThread* and *GLib-JSON* version 2.x
+	- *zlib*
+	- *OpenSSL*
+	- *PCRE* library
+	- *XMLRPC-C* version 1.16.08 or higher
+	- *hiredis* library
+	- *gperf*
+	- *libcurl* version 3.x or 4.x
+	- *libevent* version 2.x
+	- *libpcap*
+	- *libsystemd*
+	- *spandsp*
+	- *MySQL* or *MariaDB* client library (optional for media playback and call recording daemon)
+	- *libiptc* library for iptables management (optional)
+	- *ffmpeg* codec libraries for transcoding (optional) such as *libavcodec*, *libavfilter*, *libswresample*
+	- *bcg729* for full G.729 transcoding support (optional)
+	- *libmosquitto*
+	- *libwebsockets*
+	- *libopus*
+
+	The `Makefile` contains a few Debian-specific flags, which may have to removed for compilation to
+	be successful. This will not affect operation in any way.
+
+	If you do not wish to (or cannot) compile the optional iptables management feature, the
+	`Makefile` also contains a switch to disable it. See the `--iptables-chain` option for
+	a description. The name of the `make` switch and its default value is `with_iptables_option=yes`.
+
+	Similarly, the transcoding feature can be excluded via a switch in the `Makefile`, making it
+	unnecessary to have the *ffmpeg* libraries installed. The name of the `make` switch and
+	its default value is `with_transcoding=yes`.
+
+	Both `Makefile` switches can be provided to the `make` system via environment variables, for
+	example by building with the shell command `with_transcoding=no make`.
+
+* `iptables-extension`
+
+	Required for in-kernel packet forwarding.
+
+	With the `iptables` development headers installed, issuing `make` will compile the plugin for
+	`iptables` and `ip6tables`. The file will be called `libxt_RTPENGINE.so` and needs to be copied
+	into the `xtables` module directory. It is copied on `make install`. The location of this
+	directory can be determined through `pkg-config xtables --variable=xtlibdir` on newer systems,
+	and/or is usually either `/lib/xtables/` or `/usr/lib/x86_64-linux-gnu/xtables/`.
+
+* `kernel-module`
+
+	Required for in-kernel packet forwarding.
+
+	Compilation of the kernel module requires the kernel development headers to be installed in
+	`/lib/modules/$VERSION/build/`, where *$VERSION* is the output of the command `uname -r`. For
+	example, if the command `uname -r` produces the output `3.9-1-amd64`, then the kernel headers
+	must be present in `/lib/modules/3.9-1-amd64/build/`. The last component of this path (`build`)
+	is usually a symlink somewhere into `/usr/src/`, which is fine.
+
+	Successful compilation of the module will produce the file `xt_RTPENGINE.ko`. The module can be inserted
+	into the running kernel manually through `insmod xt_RTPENGINE.ko` (which will result in an error if
+	depending modules aren't loaded, for example the `x_tables` module), but it's recommended to copy the
+	module into `/lib/modules/$VERSION/updates/`, followed by running `depmod -a`.  This copying is performed
+	on `make install`. After this, the module can be loaded by issuing `modprobe xt_RTPENGINE`.
+
+* `recording-daemon`
+
+	Optional component for the call recording feature. Prerequisites are
+	usage of the kernel module and availability of transcoding (via
+	*ffmpeg*)

docs/http_websocket_support.md

@@ -0,0 +1,43 @@
+# 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.
+
+## Prometheus Stats Exporter
+
+The Prometheus metrics can be found under the URI `/metrics`.

docs/janus_interface_and_replacement.md

@@ -0,0 +1,35 @@
+# *Janus* Interface and Replacement Functionality
+
+*Rtpengine* supports a limited and narrow subset of the features provided by
+[Janus](https://janus.conf.meetecho.com/), specifically the basic business
+logic behind the *videoroom* plugin. This makes it possible to use *rtpengine*
+as a drop-in replacement for *Janus* for this one specific use case, and has
+the benefit of being able to use all the extra features that *rtpengine*
+provides, such as transcoding, in-kernel packet forwarding for improved
+performance, etc.
+
+The required subset of the *Janus* API is exposed via *rtpengine*'s HTTP/WS
+interface. The HTTP admin API is connected to the `/admin` URI path using a
+JSON payload (same as *Janus* does), while the module communication happens on
+the WS protocol `janus-protocol`, also with JSON payloads (same as *Janus*
+does). Unlike *Janus*, both HTTP and WS endpoints are running on the same port.
+In fact, there is no real distinction between both interfaces, therefore both
+admin and non-admin messages can be sent via either interface. HTTPS and WSS
+are also supported.
+
+Token-based plugin authentication works similar to how it works in *Janus*
+except that only the single *videoroom* plugin is supported. The configuration
+setting `janus-secret` must be set to enable clients to connect to this
+simulated *Janus* interface and make use of its features.
+
+Under the hood the functionality of the *videoroom* plugin is facilitated using
+*rtpengine*'s `publish` and `subscribe` methods, which are mapped directly to
+the respective *Janus* methods. One *Janus* video room becomes one *rtpengine*
+call, with a distinctive and unique call ID based on the video room ID.
+
+There's currently no support for customising the SDP features and options used
+within the *Janus* drop-in mode, and, as *Janus* is WebRTC-specific, all SDPs
+produced from this mode can be used directly by WebRTC clients. Non-WebRTC
+clients can participate in the same video room as *Janus* clients if the
+respective mapped `publish` and `subscribe` methods are used, and with the call
+ID mapped to the video room ID.

docs/tcpng_control_protocol.md

@@ -0,0 +1,5 @@
+# The *tcp-ng* Control Protocol
+
+*rtpengine* also has support for *ng* control protocol where transport is
+TCP (If enabled in the config via the --listen-tcp-ng option). Everything
+said for UDP based *ng* protocol counts for TCP variant too.

docs/transcoding.md

@@ -0,0 +1,179 @@
+# Transcoding
+
+Currently transcoding is supported for audio streams. The feature can be disabled on a compile-time
+basis, and is enabled by default.
+
+Even though the transcoding feature is available by default, it is not automatically engaged for
+normal calls. Normally *rtpengine* leaves codec negotiation up to the clients involved in the call
+and does not interfere. In this case, if the clients fail to agree on a codec, the call will fail.
+
+The transcoding feature can be engaged for a call by instructing *rtpengine* to do so by using
+one of the transcoding options in the *ng* control protocol, such as `transcode` or `ptime` (see below).
+If a codec is requested via the `transcode` option that was not originally offered, transcoding will
+be engaged for that call.
+
+With transcoding active for a call, all unsupported codecs will be removed from the SDP. Transcoding
+happens in userspace only, so in-kernel packet forwarding will not be available for transcoded codecs.
+However, even if the transcoding feature has been engaged for a call, not all codecs will necessarily
+end up being transcoded. Codecs that are supported by both sides will simply be passed through
+transparently (unless repacketization is active). In-kernel packet forwarding will still be available
+for these codecs.
+
+The following codecs are supported by *rtpengine*:
+
+* G.711 (a-Law and µ-Law)
+* G.722
+* G.723.1
+* G.729
+* Speex
+* GSM
+* iLBC
+* Opus
+* AMR (narrowband and wideband)
+* EVS (if supplied -- see below)
+
+Codec support is dependent on support provided by the `ffmpeg` codec libraries, which may vary from
+version to version. Use the `--codecs` command line option to have *rtpengine* print a list of codecs
+and their supported status. The list includes some codecs that are not listed above. Some of these
+are not actual VoIP codecs (such as MP3), while others lack support for encoding by *ffmpeg* at the
+time of writing (such as QCELP or ATRAC). If encoding support for these codecs becomes available
+in *ffmpeg*, *rtpengine* will be able to support them.
+
+Audio format conversion including resampling and mono/stereo up/down-mixing happens automatically
+as required by the codecs involved. For example, one side could be using stereo Opus at 48 kHz
+sampling rate, and the other side could be using mono G.711 at 8 kHz, and *rtpengine* will perform
+the necessary conversions.
+
+If repacketization (using the `ptime` option) is requested, the transcoding feature will also be
+engaged for the call, even if no additional codecs were requested.
+
+## G.729 support
+
+As *ffmpeg* does not currently provide an encoder for G.729, transcoding support for it is available
+via the [bcg729](https://www.linphone.org/technical-corner/bcg729/) library
+(mirror on [GitHub](https://github.com/BelledonneCommunications/bcg729)). The build system looks for
+the *bcg729* headers in a few locations and uses the library if found. If the library is located
+elsewhere, see `daemon/Makefile` to control where the build system is looking for it.
+
+In a Debian build environment, `debian/control` lists a build-time dependency
+on *bcg729*. Newer Debian releases (currently *bullseye*, *bookworm*, *sid*)
+include *bcg729* as a package so nothing needs to be done there. Older Debian
+releases do not currently include a *bcg729* package, but one can be built
+locally using these instructions on
+[GitHub](https://github.com/ossobv/bcg729-deb). *Sipwise* provides a
+pre-packaged version of this as part of our [C5
+CE](https://www.sipwise.com/products/class-5-softswitch-carrier-grade-for-voice-over-ip/)
+product which is [available
+here](https://deb.sipwise.com/spce/mr6.2.1/pool/main/b/bcg729/).
+
+Alternatively the build dependency
+can be removed from `debian/control` or by switching to a different Debian build profile.
+Set the environment variable
+`export DEB_BUILD_PROFILES="pkg.ngcp-rtpengine.nobcg729"` (or use the `-P` flag to the *dpkg* tools)
+and then build the *rtpengine* packages.
+
+## DTMF transcoding
+
+*Rtpengine* supports transcoding between RFC 2833/4733 DTMF event packets (`telephone-event` payloads)
+and in-band DTMF audio tones. When enabled, *rtpengine* translates DTMF event packets to in-band DTMF
+audio by generating DTMF tones and injecting them into the audio stream, and translates in-band DTMF
+tones by running the audio stream through a DSP, and generating DTMF event packets when a DTMF tone
+is detected.
+
+Support for DTMF transcoding can be enabled in one of two ways:
+
+* In the forward direction, DTMF transcoding is enabled by adding the codec `telephone-event` to the
+  list of codecs offered for transcoding. Specifically, if the incoming SDP body doesn't yet list
+  `telephone-event` as a supported codec, adding the option *codec → transcode → telephone-event* would
+  enable DTMF transcoding. The receiving RTP client can then accept this codec and start sending DTMF
+  event packets, which *rtpengine* would translate into in-band DTMF audio. If the receiving RTP client
+  also offers `telephone-event` in their behalf, *rtpengine* would then detect in-band DTMF audio coming
+  from the originating RTP client and translate it to DTMF event packets.
+
+* In the reverse direction, DTMF transcoding is enabled by adding the option `always transcode` to the
+  `flags` if the incoming SDP body offers `telephone-event` as a supported codec. If the receiving RTP
+  client then rejects the offered `telephone-event` codec, DTMF transcoding is then enabled and is
+  performed in the same way as described above.
+
+Enabling DTMF transcoding (in one of the two ways described above) implicitly enables the flag
+`always transcode` for the call and forces all of the audio to pass through the transcoding engine.
+Therefore, for performance reasons, this should only be done when really necessary.
+
+## T.38
+
+*Rtpengine* can translate between fax endpoints that speak T.38 over UDPTL and fax endpoints that speak
+T.30 over regular audio channels. Any audio codec can theoretically be used for T.30 transmissions, but
+codecs that are too compressed will make the fax transmission fail. The most commonly used audio codecs
+for fax are the G.711 codecs (`PCMU` and `PCMA`), which are the default codecs *rtpengine* will use in
+this case if no other codecs are specified.
+
+For further information, see the section on the `T.38` dictionary key below.
+
+## AMR and AMR-WB
+
+As AMR supports dynamically adapting the encoder bitrate, as well as restricting the available bitrates,
+there are some slight peculiarities about its usage when transcoding.
+
+When setting the bitrate, for example as `AMR-WB/16000/1/23850` in either the `codec-transcode` or the
+`codec-set` options, that bitrate will be used as the highest permitted bitrate for the encoder. If
+no `mode-set` parameter is communicated in the SDP, then that is the bitrate that will be used.
+
+If a `mode-set` is present, then the highest bitrate from that mode set which is lower or equal to the
+given bitrate will be used. If only higher bitrates are allowed by the mode set, then the next higher
+bitrate will be used.
+
+To produce an SDP that includes the `mode-set` option (when adding AMR to the codec list via
+`codec-transcode`), the full format parameter string can be appended to the codec specification, e.g.
+`codec-transcode-AMR-WB/16000/1/23850//mode-set=0,1,2,3,4,5;octet-align=1`. In this example, the bitrate
+23850 won't actually be used, as the highest permitted mode is 5 (18250 bps) and so that bitrate will
+be used.
+
+If a literal `=` cannot be used due to parsing constraints (i.e. being wrongly interpreted as a
+key-value pair), it can be escaped by using two dashes instead, e.g.
+`codec-transcode-AMR-WB/16000/1/23850//mode-set--0,1,2,3,4,5;octet-align--1`
+
+The default (highest) bitrates for AMR and AMR-WB are 6700 and 14250, respectively.
+
+If a Codec Mode Request (CMR) is received from the AMR peer, then *rtpengine* will adhere to the request
+and switch encoder bitrate unconditionally, even if it's a higher bitrate than originally desired.
+
+To enable sending CMRs to the AMR peer, the codec-specific option `CMR-interval` is provided. It takes
+a number of milliseconds as argument. Throughout each interval, *rtpengine* will track which AMR frame
+types were received from the peer, and then based on that will make a decision at the end of the
+interval. If a higher bitrate is allowed by the mode set that was not received from the AMR peer at all,
+then *rtpengine* will request switching to that bitrate per CMR. Only the next-highest bitrate mode that
+was not received will ever be requested, and a CMR will be sent only once per interval. Full example to
+specify a CMR interval of 500 milliseconds (with `=` escapes):
+`codec-transcode-AMR-WB/16000/1/23850//mode-set--0,1,2/CMR-interval--500`
+
+Similar to the `CMR-interval` option, *rtpengine* can optionally attempt to periodically increase the
+outgoing bitrate without being requested to by the peer via a CMR. To enable this, set the option
+`mode-change-interval` to the desired interval in milliseconds. If the last CMR from the AMR peer was
+longer than this interval ago, *rtpengine* will increase the bitrate by one step if possible. Afterwards,
+the interval starts over.
+
+## EVS
+
+Enhanced Voice Services (EVS) is a patent-encumbered codec for which (at the
+time of writing) no implementation exists which can be freely used and
+distributed. As such, support for EVS is only available if an implementation is
+supplied separately. Currently the only implementation supported is the
+ETSI/3GPP reference implementation (either floating-point or fixed-point). Any
+licensing issues that might result from such usage are the responsibility of
+the user of this software.
+
+The EVS codec implementation can be provided as a shared object library (*.so*)
+which is loaded in during runtime (at startup). The supported implementations
+can be seen as subdirectories within the `evs/` directory. Currently supported
+are version 17.0.0 of the ETSI/3GPP reference implementation, [*126.442*](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1464) for the
+fixed-point implementation and [*126.443*](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1465) for the floating-point implementation.
+(The floating-point implementation seems to be significantly faster, but is not
+bit-precise.)
+
+To supply the codec implementation as a shared object during runtime, extract
+the reference implementation's *.zip* file and apply the provided `patch`
+([from here](https://github.com/sipwise/rtpengine/tree/master/evs)) that is
+appropriate for the chosen implementation. Run the build using `make`
+(suggested build flags are `RELEASE=1 make`) and it should produce a file
+`lib3gpp-evs.so`. Point *rtpengine* to this file using the `evs-lib-path=`
+option to enable support for EVS.

docs/troubleshooting.md

@@ -1,5 +1,5 @@
 Troubleshooting Overview
-==========================
+========================
 
 This is the page, which describes troubleshooting aspects of the RTPEngine project.
 

docs/usage.md

@@ -0,0 +1,178 @@
+# Usage
+
+## Userspace Daemon
+
+The options are described in detail in the rtpengine(1) man page. If you're
+reading this on Github, you can view the current master's man page
+[here](https://github.com/sipwise/rtpengine/blob/master/daemon/rtpengine.pod).
+
+## In-kernel Packet Forwarding
+
+In normal userspace-only operation, the overhead involved in processing each individual RTP or media packet
+is quite significant. This comes from the fact that each time a packet is received on a network interface,
+the packet must first traverse the stack of the kernel's network protocols, down to locating a process's
+file descriptor. At this point the linked user process (the daemon) has to be signalled that a new packet
+is available to be read, the process has to be scheduled to run, once running the process must read the packet,
+which means it must be copied from kernel space to user space, involving an expensive context switch. Once the
+packet has been processed by the daemon, it must be sent out again, reversing the whole process.
+
+All this wouldn't be a big deal if it wasn't for the fact that RTP traffic generally consists of many small
+packets being transferred at high rates. Since the forwarding overhead is incurred on a per-packet basis, the
+ratio of useful data processed to overhead drops dramatically.
+
+For these reasons, *rtpengine* provides a kernel module to offload the bulk of the packet forwarding
+duties from user space to kernel space. Using this technique, a large percentage of the overhead can be
+eliminated, CPU usage greatly reduced and the number of concurrent calls possible to be handled increased.
+
+In-kernel packet forwarding is implemented as an *iptables* module
+(or more precisely, an *x\_tables* module). As such, it comes in two parts, both of
+which are required for proper operation. One part is the actual kernel module called `xt_RTPENGINE`. The
+second part is a plugin to the `iptables` and `ip6tables` command-line utilities to make it possible to
+actually add the required rule to the tables.
+
+### Overview ###
+
+In short, the prerequisites for in-kernel packet forwarding are:
+
+1. The `xt_RTPENGINE` kernel module must be loaded.
+2. An `iptables` and/or `ip6tables` rule must be present in the `INPUT` chain (or in a custom user-defined
+   chain which is then called by the `INPUT` chain) to send packets
+   to the `RTPENGINE` target. This rule should be limited to UDP packets, but otherwise there
+   are no restrictions.
+3. The `rtpengine` daemon must be running.
+4. All of the above must be set up with the same forwarding table ID (see below).
+
+The sequence of events for a newly established media stream is then:
+
+1. The SIP proxy (e.g. *Kamailio*) controls *rtpengine* and informs it about a newly established call.
+2. The `rtpengine` daemon allocates local UDP ports and sets up preliminary forward rules
+   based on the info received
+   from the SIP proxy. Only userspace forwarding is set up, nothing is pushed to the kernel module yet.
+3. An RTP packet is received on the local port.
+4. It traverses the *iptables* chains and gets passed to the *xt\_RTPENGINE* module.
+5. The module doesn't recognize it as belonging to an established stream and thus ignores it.
+6. The packet continues normal processing and eventually ends up in the daemon's receive queue.
+7. The daemon reads it, processes it and forwards it. It also updates some internal data.
+8. This userspace-only processing and forwarding continues for a little while, during which time information
+   about additional streams and/or endpoints may be obtained from the SIP proxy.
+9. After a few seconds, when the daemon is satisfied with what it has learned about the media endpoints,
+   it pushes the forwarding rules to the kernel.
+10. From this moment on, the kernel module will recognize incoming packets belonging to those streams
+    and will forward them on its own. It will stop those packets from traversing the network stacks any
+    further, so the daemon will not see them any more on its receive queues.
+11. In-kernel forwarding is allowed to cease to work at any given time, either accidentally (e.g. by
+    removal of the *iptables* rule) or deliberately (the daemon will do so in case of a re-invite), in which
+    case forwarding falls back to userspace-only operation.
+
+### The Kernel Module ###
+
+The kernel module supports multiple forwarding tables (not to be confused with the tables managed
+by *iptables*), which are identified through their ID number. By default, up to 64 forwarding tables
+can be created and used, giving them the ID numbers 0 through 63.
+
+Each forwarding table can be thought of a separate proxy instance. Each running instance of the
+*rtpengine* daemon controls one such table, and each table can only be controlled by one
+running instance of the daemon at any given time. In the most common setup, there will be only a single
+instance of the daemon running and there will be only a single forwarding table in use, with ID zero.
+
+The kernel module can be loaded with the command `modprobe xt_RTPENGINE`. With the module loaded, a new
+directory will appear in `/proc/`, namely `/proc/rtpengine/`. After loading, the directory will contain
+only two pseudo-files, `control` and `list`. The `control` file is write-only and is used to create and
+delete forwarding tables, while the `list` file is read-only and will produce a list of currently
+active forwarding tables. With no tables active, it will produce an empty output.
+
+The `control` pseudo-file supports two commands, `add` and `del`, each followed by the forwarding table
+ID number. To manually create a forwarding table with ID 42, the following command can be used:
+
+	echo 'add 42' > /proc/rtpengine/control
+
+After this, the `list` pseudo-file will produce the single line `42` as output. This will also create a
+directory called `42` in `/proc/rtpengine/`, which contains additional pseudo-files to control this
+particular forwarding table.
+
+To delete this forwarding table, the command `del 42` can be issued like above. This will only work
+if no *rtpengine* daemon is currently running and controlling this table.
+
+Each subdirectory `/proc/rtpengine/$ID/` corresponding to each forwarding table contains the pseudo-files
+`blist`, `control`, `list` and `status`. The `control` file is write-only while the others are read-only.
+The `control` file will be kept open by the *rtpengine* daemon while it's running to issue updates
+to the forwarding rules during runtime. The daemon also reads the `blist` file on a regular basis, which
+produces a list of currently active forwarding rules together with their stats and other details
+within that table in a binary format. The same output,
+but in human-readable format, can be obtained by reading the `list` file. Lastly, the `status` file produces
+a short stats output for the forwarding table.
+
+Manual creation of forwarding tables is normally not required as the daemon will do so itself, however
+deletion of tables may be required after shutdown of the daemon or before a restart to ensure that the
+daemon can create the table it wants to use.
+
+The kernel module can be unloaded through `rmmod xt_RTPENGINE`, however this only works if no forwarding
+table currently exists and no *iptables* rule currently exists.
+
+### The *iptables* module ###
+
+In order for the kernel module to be able to actually forward packets, an *iptables* rule must be set up
+to send packets into the module. Each such rule is associated with one forwarding table. In the simplest case,
+for forwarding table 42, this can be done through:
+
+	iptables -I INPUT -p udp -j RTPENGINE --id 42
+
+If IPv6 traffic is expected, the same should be done using `ip6tables`.
+
+It is possible but not strictly
+necessary to restrict the rules to the UDP port range used by *rtpengine*, e.g. by supplying a parameter
+like `--dport 30000:40000`. If the kernel module receives a packet that it doesn't recognize as belonging
+to an active media stream, it will simply ignore it and hand it back to the network stack for normal
+processing.
+
+The `RTPENGINE` rule need not necessarily be present directly in the `INPUT` chain. It can also be in a
+user-defined chain which is then referenced by the `INPUT` chain, like so:
+
+	iptables -N rtpengine
+	iptables -I INPUT -p udp -j rtpengine
+	iptables -I rtpengine -j RTPENGINE --id 42
+
+This can be a useful setup if certain firewall scripts are being used.
+
+## Summary
+
+A typical start-up sequence including in-kernel forwarding might look like this:
+
+	# this only needs to be one once after system (re-) boot
+	modprobe xt_RTPENGINE
+	iptables -I INPUT -p udp -j RTPENGINE --id 0
+	ip6tables -I INPUT -p udp -j RTPENGINE --id 0
+
+	# ensure that the table we want to use doesn't exist - usually needed after a daemon
+	# restart, otherwise will error
+	echo 'del 0' > /proc/rtpengine/control
+
+	# start daemon
+	/usr/bin/rtpengine --table=0 --interface=10.64.73.31 --interface=2001:db8::4f3:3d \
+	--listen-ng=127.0.0.1:2223 --tos=184 --pidfile=/run/rtpengine.pid --no-fallback
+
+## Running Multiple Instances
+
+In some cases it may be desired to run multiple instances of *rtpengine* on the same machine, for example
+if the host is multi-homed and has multiple usable network interfaces with different addresses. This is
+supported by running multiple instances of the daemon using different command-line options (different
+local addresses and different listening ports), together with
+multiple different kernel forwarding tables.
+
+For example, if one local network interface has address 10.64.73.31 and another has address 192.168.65.73,
+then the start-up sequence might look like this:
+
+	modprobe xt_RTPENGINE
+	iptables -I INPUT -p udp -d 10.64.73.31 -j RTPENGINE --id 0
+	iptables -I INPUT -p udp -d 192.168.65.73 -j RTPENGINE --id 1
+
+	echo 'del 0' > /proc/rtpengine/control
+	echo 'del 1' > /proc/rtpengine/control
+
+	/usr/bin/rtpengine --table=0 --interface=10.64.73.31 \
+	--listen-ng=127.0.0.1:2223 --tos=184 --pidfile=/run/rtpengine-10.pid --no-fallback
+	/usr/bin/rtpengine --table=1 --interface=192.168.65.73 \
+	--listen-ng=127.0.0.1:2224 --tos=184 --pidfile=/run/rtpengine-192.pid --no-fallback
+
+With this setup, the SIP proxy can choose which instance of *rtpengine* to talk to and thus which local
+interface to use by sending its control messages to either port 2223 or port 2224.