Fine-Grained TCP Configuration Using the “tcp_mgm” Module

OpenSIPS 3.3 introduces a new module which offers full control over the configuration of individual TCP connections. From filtering by the employed TCP-based protocol (e.g. BIN, TLS, MSRP, SMPP, etc.), all the way down to specific combinations of remote and local IPv4 or IPv6 addresses, OpenSIPS platform developers now have the ability to cherry-pick and fine-tune any of the TCP connections taking place on their OpenSIPS server.

The vision for this feature is to allow for personalized settings based on the nature of the TCP path, for example:

• a set of TCP-based SIP Trunks which could use a slightly bumped connection_timeout since they are hosted across Europe, in the US
• a pool of TCP users all of which require the no_new_conn property since they are NAT’ed and OpenSIPS will never be able to connect to them, rather only accept connections from them
• an OpenSIPS-OpenSIPS binary replication TCP connection which has a high throughput and requires the parallel_read flag to be enabled
• a TCP connection opened by the Back-to-Back module during some internal callback which doesn’t give programmatic access inside the opensips.cfg script so we can configure the connection’s behaviour

These examples just scratch the surface of the possible use-cases for the TCP paths defined using tcp_mgm. Of course, if no defined filter matches a given connection or if the module is not loaded at all, OpenSIPS will simply use the global TCP connection settings just as it did before, in a fully backwards-compatible manner.

Now, let’s dive deeper into the module’s structure!

TCP Connection Profile

A TCP connection profile is nothing more than the already known set of global TCP parameters, gathered into an easily manageable structure. For now, there are 12 configurable attributes within a TCP connection profile. Along with their default values, they are as follows:

• connection_timeout (100 ms)
• con_lifetime (120 s)
• msg_read_timeout (4 s)
• send_threshold (0 us, i.e. “not set”)
• no_new_conn (0, i.e. “disabled”)
• alias_mode (0, i.e. “never create a ‘backwards’ alias of the connection”)
• parallel_read (0, i.e. “disabled”)
  • Tip: this is a new feature introduced in 3.3, where a SIP TCP reader can optionally “pass along” the connection to another reader before performing its opensips.cfg processing, thus achieving some degree of processing parallelism on that respective connection
• keepalive (1, i.e. “enabled”)
• keepcount (9)
• keepidle (7200 s)
• keepinterval (75 s)
• attrs (module-specific settings, gathered into a params list, e.g. “max_msg_chunks=10;foo_bar=20;baz=7”)

Each of these attributes has a corresponding global opensips.cfg parameter, such that there is no need to load the tcp_mgm module when there is no use-case for it. OpenSIPS will work just as before, with near-zero added overhead.

TCP Path

Building on top of a TCP connection profile is a TCP Path, which is synonymous to a rule. These rules can only be defined using an SQL table (see the new tcp_mgm table in the DB Schema for 3.3) and they consist of the following fields:

• protocol
  • the matched TCP-based protocol. Example values: “tcp”, “msrp”, “bin”, “tls”, “wss”, “hep_tcp”, etc.).
  • Default: “any”, matching all TCP protocols
• remote_addr
  • the IP address of the remote side, i.e. not OpenSIPS. Full CIDR notation is supported, e.g. 192.168.122.0/24. Higher prefix lengths are evaluated first, e.g. a /32 takes priority over a /28.
  • Default: NULL, synonymous to 0.0.0.0/0 and “any”.
• remote_port
  • filter by remote side TCP port.
  • Default: 0 (match any remote port)
• local_addr
  • the OpenSIPS TCP socket IP address or TCP socket tag (see the socket parameter documentation for more info on socket tags)
  • Default: NULL (match any OpenSIPS TCP listener)
• local_port
  • filter by local TCP port.
  • Default: 0 (match any OpenSIPS TCP listener port)
• priority
  • prioritize one rule over another, lower is better
  • Default: 0
• connection_profile
  • For simplicity reasons, I will “attach” the profile as a whole here, but the tcp_mgm table actually includes each individual profile field (column) here. For now, we have not made a separate table holding profiles only which is then referenced & reused from the TCP paths table, but this can be a starting point for future enhancements!

Notice that a rule has two major components: some filters and a connection profile. The more filters we bake into a rule (e.g. protocol, remote IP, local address, local port…) the more restrictive the rule becomes, thus its profile will apply to less connections.

Regarding the DB schema: since tcp_mgm has no external dependencies, it will be part of the core opensips package, which means the DB schema will also get installed via the standard DB schema install of the opensips-cli tool.

Feedback

We did quite a bit of brainstorming before coming up with this set of features and table structure for tcp_mgm, and at least in our opinion, they are more than enough to allow for some very useful, practical setups which were not possible before.

If you have any suggestions for how this can work even better for you and for everyone else, do make sure to open a thread on one of the mailing lists or even open up a feature request on the tracker with your ideas – the OpenSIPS 3.3 beta release is almost a month away, so there is plenty of time!