Ask AI

For a deeper understanding of SIP trunking fundamentals, see our comprehensive SIP Trunking explained guide and learn about SIP vs VoIP differences.

Prerequisites

Before getting started, ensure you have:

• A Debian-like server (Ubuntu 20.04+ recommended)
• Root or sudo access
• Basic knowledge of SIP and Linux shell
• A public IP address (if registering remote clients)
• A Telnyx Mission Control Portal account for SIP trunk connectivity

For additional setup guidance, refer to the Telnyx SIP Trunking Quickstart documentation.

Installing Kamailio

Assuming a Debian-like server, Kamailio can be easily installed via apt-get. The registration feature of Kamailio requires a database. For simplicity, SQLite will be used in this example. Start by installing Kamailio and the associated SQLite module, along with the optional command line interface for SQLite (useful for querying the Kamailio database):

Copy
sudo apt-get install kamailio kamailio-sqlite-modules sqlite3

Setting up the SQLite database

Open up the kamctlrc file with your preferred editor:

Copy
sudo nano /etc/kamailio/kamctlrc

Uncomment and set the following variables:

Copy
DBENGINE=SQLITE
DB_PATH="/tmp/kamailio_sqlite.db"

While editing the kamctlrc file, also set the SIP_DOMAIN variable. This is needed to run Kamailio and have a softphone register with it. The SIP_DOMAIN variable should be set to the Kamailio host's public IP or domain name:

Copy
SIP_DOMAIN=<Kamailio host's public IP or domain name>

At this point, create the database with the kamdbctl command:

Copy
kamdbctl create

Required Kamailio parameters

The following table outlines the essential Kamailio parameters that must be configured for SIP registration to work properly:

Configuring Kamailio for registration

Edit the main Kamailio configuration file:

Copy
sudo nano /etc/kamailio/kamailio.cfg

Enable the required modules by uncommenting or adding these lines:

Copy
#!define WITH_SQLITE
#!define WITH_USRLOCDB

The key modules you need for registration are:

• registrar: Handles SIP REGISTER requests
• usrloc: Manages user location records (Address of Record)
• auth_db: Provides authentication against a database

For production deployments, also consider enabling:

• pike: Rate limiting to prevent DoS attacks
• htable: Hash table for caching
• permissions: IP-based access control

Kamailio usrloc module database modes

The usrloc module supports multiple database modes, each with different performance and persistence trade-offs. Choose based on your deployment requirements:

Configure the mode in your kamailio.cfg:

Copy
modparam("usrloc", "db_mode", 1)

Adding users for authentication

To add users for authentication, use the kamctl utility:

Copy
kamctl add testuser testpassword

This creates a subscriber entry in the database. Users will authenticate using these credentials when their softphone registers.

Telnyx trunk settings mapping

When connecting Kamailio to Telnyx SIP Trunks, map these settings in your configuration:

For detailed configuration steps, consult the Telnyx SIP configuration guide and developer configuration guides.

Configuration options comparison

When setting up SIP registration, you have several architectural choices. Here's how they compare:

Security best practices

"The default Kamailio config is not production-ready. You must enable authentication, rate limiting, and strict header validation to secure your server. When users are allowed to create their own passwords, there will be weak passwords—at thousands of SIP packets per second, it's worthwhile for attackers to guess credentials."

— Daniel-Constantin Mierla, Co-Founder and Core Developer, Kamailio Project

Implement these security measures for production deployments:

Enable digest authentication

Copy
route[AUTH] {
    if (!is_method("REGISTER|INVITE")) return;
    
    if (!auth_check("$fd", "subscriber", "1")) {
        auth_challenge("$fd", "0");
        exit;
    }
    consume_credentials();
}

Rate limiting with pike module

Copy
modparam("pike", "sampling_time_unit", 2)
modparam("pike", "reqs_density_per_unit", 16)
modparam("pike", "remove_latency", 4)

route[PIKE] {
    if (!pike_check_req()) {
        xlog("L_ALERT", "PIKE: Blocking $si\n");
        exit;
    }
}

Block known malicious user agents

Copy
if ($ua =~ "(friendly-scanner|sipvicious|sipcli)") {
    xlog("L_WARN", "Blocked scanner from $si\n");
    exit;
}

For comprehensive security guidance, review the Kamailio Security Wiki and NIST SP 800-58: Security Considerations for VoIP Systems.

Starting Kamailio

After completing the configuration, start the Kamailio service:

Copy
sudo systemctl start kamailio
sudo systemctl enable kamailio

Check the status to ensure it's running:

Copy
sudo systemctl status kamailio

Setting up Zoiper softphone

1. Download and install Zoiper from the app store on your Android device
2. Open Zoiper and select Add account
3. When asked whether there are a username and password, select Yes, then Manual configuration
4. Choose SIP Account and configure:
   • Account name: Any descriptive name
   • Host: Kamailio host's public IP or domain name
   • Username: The username created with kamctl add
   • Password: The corresponding password

Once saved, registration should be successful. For alternative softphone options, see our guide on configuring Linphone with Telnyx.

Verifying registration

On the Kamailio side, use the SQLite command line interface to verify successful registration:

Copy
sqlite3 /tmp/kamailio_sqlite.db
sqlite> SELECT * FROM location;

Successfully registered users will appear in the location table with their contact information, including the device's current IP address and port.

You can also use the kamcmd tool to dump user locations:

Copy
kamcmd ul.dump

Integrating with Telnyx for PSTN connectivity

To connect your Kamailio registrar to the PSTN through Telnyx:

1. Create a Telnyx account and complete verification
2. Set up a SIP Connection with credential-based authentication
3. Purchase phone numbers in the Mission Control Portal
4. Configure Kamailio to route outbound calls through Telnyx

Learn more about SIP trunk setup in our step-by-step SIP trunk guide and understand SIP channels and how they work.

Next steps

This setup provides a foundation for using Kamailio as a SIP registrar. From here, you can:

• Integrate with FreeSWITCH for media handling
• Add TLS encryption for secure signaling (see Nick vs Networking Kamailio security guide)
• Configure dispatcher module for load balancing
• Set up presence and instant messaging
• Explore DIDs and SIP numbers for advanced number management

For additional learning, the Nick vs Networking Kamailio 101 series provides excellent tutorials on Kamailio configuration.

Additional resources

• Telnyx SIP Trunking Product Page
• Telnyx Developer Portal
• Telnyx Support Center
• Kamailio Official Documentation
• Kamailio GitHub Repository

To learn more about SIP Trunking and its uses, explore our SIP Trunking page or test it yourself in the Telnyx Mission Control Portal.

Have questions about SIP trunk registration in Kamailio? Join our subreddit.

Sign up for emails of our latest articles and news