drachtio-server

Drachtio uses JSON messaging over TCP to control the server. All messages include a type property which can be one of three values:

1. request: A command sent to the server. Must be acknowledged by exactly one response.
   • rid: A unique string generated by the sender to match responses to requests.
   • command: A string indicating the action.
   • data: An object containing command-specific parameters.
2. response: An acknowledgment of a request.
   • rid: The rid from the original request.
   • data: An object containing response details.
3. sip: A message containing SIP data.
   • msg: The SIP message data.
   • transactionId: Used to match SIP responses to requests.

drachtio can be configured using three methods. Settings are applied on a per-parameter basis following this order of precedence (highest to lowest):

1. Command-line arguments
2. Environment variables
3. Configuration file (XML)

drachtio-server supports integration with Prometheus by exposing a metrics endpoint. You can enable this by using the --prometheus-scrape-port CLI flag to specify the port on which the server will listen for scrape requests.

To verify the metrics are being served, you can use curl to query the /metrics endpoint on the configured port.

# Start drachtio-server with Prometheus scraping enabled on port 9099
./drachtio --prometheus-scrape-port 9099 -f ../test/drachtio.conf.xml &

# Verify metrics via curl
$ curl 127.0.0.1:9099/metrics

To build from source, you must first install the required system dependencies. On Debian-based systems, install libcurl4-openssl-dev and libboost-all-dev.

All other third-party dependencies (including the sofia-sip stack) are located in the $(srcdir)/deps directory. sofia-sip is managed via git submodules.

Follow these steps to build:

1. Clone the repository.
2. Initialize submodules.
3. Run autogen.sh.
4. Create a build directory and run configure.
5. Run make and make install.

sudo apt install libcurl4-openssl-dev libboost-all-dev

git clone --depth=50 --branch=main https://github.com/drachtio/drachtio-server.git && cd drachtio-server
git submodule update --init --recursive
./autogen.sh
mkdir build && cd $
../configure CPPFLAGS='-DNDEBUG'
make
sudo make install

The build process produces an executable named drachtio.

• Default Config: If run without parameters, it looks for /etc/drachtio.conf.xml.
• Custom Config: Use the -f flag to specify a configuration file.
• Daemon Mode: Use the --daemon flag to run the server as a background process.
• Help: Run drachtio -h to see all available command-line options.

# Run with a specific config file
./drachtio -f ../drachtio.conf.xml

# Run as a daemon
./drachtio --daemon

You can use the official Docker image to run drachtio-server. The drachtio/drachtio-server:latest tag is kept current with the main branch.

docker pull drachtio/drachtio-server:latest

To receive specific types of SIP requests (e.g., INVITE), the client must first send a route request to the server. The server will then forward matching SIP messages to the client as sip type requests.

// Client Request to subscribe to INVITEs
{
	"type":"request"
	,"command":"route"
	,"rid":"f5885448fc9b2b8e53ff991c966d4ecc"
	,"data":{
		"verb":"invite"
	}
}

// Server Response confirming success
{
	"type":"response"
	,"rid":"f5885448fc9b2b8e53ff991c966d4ecc"
	,"data":{
		"success":true
	}
}

After establishing a TCP connection, a client must authenticate by sending an auth request containing a shared secret. The server will respond with a response message indicating if authentication was successful.

// Client Request
{
	"type":"request"
	,"command":"auth"
	,"rid":"8da95bd22b964e6be24624a6ec6313ff"
	,"data":{
		"secret":"cymru"
	}
}

// Server Response
{
	"data": {
		"authenticated":true
	}
	,"rid":"8da95bd22b964e6be24624a6ec6313ff"
	,"type":"response"
}

For faster memory management, you can build with tcmalloc. Install libgoogle-perftools-dev and use the --enable-tcmalloc=yes flag during the configuration step.

sudo apt install libgoogle-perftools-dev

# After running autogen.sh and entering the build directory:
../configure --enable-tcmalloc=yes CPPFLAGS='-DNDEBUG'

Specify which SIP addresses and protocols the server should listen on. You can define multiple contacts.

Note: SIP contact settings cannot be configured via environment variables.

<!-- XML Configuration -->
<drachtio>
  <sip>
    <contacts>
      <contact>sip:172.28.0.1:5060;transport=udp,tcp</contact>
      <contact>sip:172.28.0.1:5080;transport=udp,tcp</contact>
    </contacts>
  </sip>
</drachtio>

# Command Line
drachtio --contact "sip:172.28.0.1:5060;transport=udp,tcp" \
   --contact "sip:172.28.0.1:5080;transport=udp,tcp"

The RIP (Requests In Progress) class and associated controller methods allow the system to track requests sent by the client that are awaiting a response from the network.

• addRIP(orq, rip): Associates an outgoing request (nta_outgoing_t) with a RIP object.
• findRIPByOrq(orq, &rip): Retrieves the RIP object associated with a specific outgoing request.
• clearRIP(orq): Removes the tracking for a specific outgoing request.
• clearRIPByDialogId(dialogId): Clears all pending requests associated with a specific dialog ID.