Deploying Kamailio

Introduction

Kamailio is a high-performance, open-source SIP (Session Initiation Protocol) server capable of handling thousands of calls per second. Originally forked from SIP Express Router (SER), Kamailio has become one of the most widely deployed SIP servers, powering VoIP networks, unified communications platforms, and real-time communication systems worldwide.

Written in C for maximum performance, Kamailio provides a flexible and extensible framework for building SIP-based applications. Its modular architecture allows you to enable only the features you need, from basic call routing to advanced features like presence, WebRTC gateway, and carrier-grade billing.

Key highlights of Kamailio:

High Performance: Handle thousands of concurrent calls with minimal resource usage
SIP Proxy/Registrar/Location: Full SIP server functionality for VoIP networks
Load Balancing: Distribute calls across multiple media servers
Authentication: Support for digest authentication, database backends, and LDAP
NAT Traversal: Built-in NAT handling for clients behind firewalls
WebRTC Gateway: Bridge WebRTC clients to traditional SIP networks
TLS/SRTP Support: Secure communications with encryption
Presence Server: SIP presence and SIMPLE messaging support
Database Integration: MySQL, PostgreSQL, SQLite, and more
Extensible: Lua, Python, and JavaScript scripting support
Open Source: GPLv2 licensed with commercial-friendly options

This guide walks through deploying Kamailio on Klutch.sh using Docker for SIP-based communication services.

Why Deploy Kamailio on Klutch.sh

Deploying Kamailio on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kamailio without complex configuration.

Persistent Storage: Attach persistent volumes for your database and configuration. User registrations and settings survive restarts.

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on expected call volume.

Environment Variable Management: Securely store database credentials and SIP secrets through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Kamailio instance for your SIP domain.

Always-On Availability: Your SIP server remains accessible 24/7.

Prerequisites

Before deploying Kamailio on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Kamailio configuration
Basic familiarity with Docker and containerization concepts
Understanding of SIP protocol and VoIP concepts
(Optional) A custom domain for your SIP server

Understanding Kamailio Architecture

Kamailio uses a modular, event-driven architecture:

Core Engine: The main SIP message processing engine written in C for maximum performance.

Modules: Loadable modules provide specific functionality (authentication, database access, NAT handling, etc.).

Configuration Script: kamailio.cfg defines routing logic, module loading, and server behavior.

Database Backend: Optional database for user credentials, location data, and configuration.

RPC Interface: Remote procedure call interface for management and monitoring.

Preparing Your Repository

To deploy Kamailio on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

kamailio-deploy/
├── Dockerfile
├── kamailio.cfg
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM kamailio/kamailio:5.7

# Install additional modules if needed
RUN apt-get update && apt-get install -y \
    kamailio-mysql-modules \
    kamailio-tls-modules \
    kamailio-websocket-modules \
    && rm -rf /var/lib/apt/lists/*

# Copy custom configuration
COPY kamailio.cfg /etc/kamailio/kamailio.cfg

# Create directories
RUN mkdir -p /var/run/kamailio

# Set permissions
RUN chown -R kamailio:kamailio /var/run/kamailio

# Expose SIP ports
EXPOSE 5060/udp
EXPOSE 5060/tcp
EXPOSE 5061/tcp

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD kamctl stats || exit 1

CMD ["kamailio", "-DD", "-E", "-f", "/etc/kamailio/kamailio.cfg"]

Configuration File

Create a kamailio.cfg configuration file:

#!KAMAILIO

# Global parameters
debug=2
log_stderror=yes
fork=no
children=4

# Listen on all interfaces
listen=udp:0.0.0.0:5060
listen=tcp:0.0.0.0:5060

# Modules section
loadmodule "jsonrpcs.so"
loadmodule "kex.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "sl.so"
loadmodule "rr.so"
loadmodule "pv.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"

# Module parameters
modparam("usrloc", "db_mode", 0)
modparam("registrar", "default_expires", 3600)

# Routing logic
request_route {
    # Per-request initial checks
    route(REQINIT);

    # Handle CANCEL
    if (is_method("CANCEL")) {
        if (t_check_trans()) {
            route(RELAY);
        }
        exit;
    }

    # Handle retransmissions
    if (!is_method("ACK")) {
        if (t_precheck_trans()) {
            t_check_trans();
            exit;
        }
        t_check_trans();
    }

    # Record route for dialogs
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    # Handle REGISTER
    if (is_method("REGISTER")) {
        route(REGISTRAR);
        exit;
    }

    # Relay requests
    route(RELAY);
}

# Initial request checks
route[REQINIT] {
    if (!mf_process_maxfwd_header("10")) {
        sl_send_reply("483", "Too Many Hops");
        exit;
    }

    if (!sanity_check("1511", "7")) {
        xlog("Malformed SIP message from $si:$sp\n");
        exit;
    }
}

# Registration handling
route[REGISTRAR] {
    if (!save("location")) {
        sl_reply_error();
    }
    exit;
}

# Relay route
route[RELAY] {
    if (!t_relay()) {
        sl_reply_error();
    }
    exit;
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`SIP_DOMAIN`	Yes	-	Primary SIP domain
`DB_HOST`	No	-	Database host for persistent storage
`DB_USER`	No	-	Database username
`DB_PASSWORD`	No	-	Database password
`DEBUG_LEVEL`	No	2	Logging verbosity (0-4)

Deploying Kamailio on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile kamailio.cfg .dockerignore README.md
git commit -m "Initial Kamailio deployment configuration"
git remote add origin https://github.com/yourusername/kamailio-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kamailio” or “sip-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kamailio Dockerfile.

Configure Traffic

Kamailio requires specific port configuration:

For SIP over UDP/TCP, configure port 5060
For SIP over TLS, configure port 5061

Note: SIP traffic has specific requirements. Consult Klutch.sh documentation for UDP port configuration.

Set Environment Variables

In the environment variables section, add:

Variable	Value
`SIP_DOMAIN`	`sip.example.com`
`DEBUG_LEVEL`	`2`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/lib/kamailio`	1 GB	Location database and state
`/etc/kamailio`	100 MB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the Kamailio container

Configure DNS

Set up DNS records for your SIP domain:

A record: sip.example.com -> Your Klutch.sh IP
SRV record: _sip._udp.example.com -> sip.example.com:5060

Initial Setup and Configuration

Testing Registration

Test SIP registration with a softphone:

Configure your SIP client with your Kamailio server address
Use UDP port 5060
Register with a test user
Verify registration in Kamailio logs

Adding User Authentication

For production, enable database-backed authentication:

Enable the auth_db module in kamailio.cfg
Configure database connection parameters
Create user accounts using kamctl:

kamctl add user1 password123

Enabling TLS

Secure your SIP communications:

Generate or obtain SSL certificates
Enable the tls module
Configure certificate paths
Update listen directives for TLS

WebRTC Gateway

Enable WebRTC support:

Load websocket module
Configure WebSocket listener
Enable SRTP/DTLS for media encryption
Test with WebRTC clients

Production Best Practices

Security Recommendations

TLS Encryption: Enable TLS for all SIP signaling
Strong Authentication: Use strong passwords and consider certificate-based auth
Firewall Rules: Restrict SIP access to known networks
Fail2Ban: Implement rate limiting and ban rules
Regular Updates: Keep Kamailio updated for security patches

Performance Optimization

Child Processes: Tune children count based on load
Memory: Allocate sufficient shared memory for busy systems
Database Caching: Enable caching for database-backed features
Load Balancing: Use dispatcher module for media server distribution

Monitoring

Monitor your SIP infrastructure:

SIP Statistics: Use kamctl to view call statistics
RPC Monitoring: Enable SNMP or custom monitoring
Log Analysis: Monitor for registration failures and attacks
Call Quality: Implement RTP quality monitoring

Troubleshooting Common Issues

Registration Failures

Symptoms: Clients cannot register.

Solutions:

Check Kamailio logs for error messages
Verify authentication credentials
Check firewall rules for UDP/TCP 5060
Test NAT traversal settings

Call Setup Failures

Symptoms: Calls don’t connect.

Solutions:

Verify routing configuration
Check media server connectivity
Review SDP negotiation in logs
Test codec compatibility

NAT Issues

Symptoms: One-way audio or call drops.

Solutions:

Enable nathelper module
Configure RTP proxy for media relay
Check NAT keepalive settings
Test with clients on same network

Additional Resources

Conclusion

Deploying Kamailio on Klutch.sh gives you a powerful, carrier-grade SIP server for building VoIP and real-time communication systems. The combination of Kamailio’s proven performance and Klutch.sh’s deployment simplicity means you can focus on your communication application rather than infrastructure.

With support for thousands of concurrent calls, extensive protocol support, and flexible scripting, Kamailio handles everything from small office phone systems to large-scale telecommunications platforms. Whether you’re building a VoIP service, unified communications platform, or WebRTC gateway, Kamailio on Klutch.sh provides the reliable foundation you need.