Shkerka.ruзаметки админа
SIP, Kamailio и софтфоны

Установка и настройка Kamailio на Debian

Опубликовано: Обновлено: 8 мин чтенияАвтор: Редакция Shkerka.ru

Пошаговая установка SIP-сервера Kamailio на Debian 12 из официального репозитория проекта: база MariaDB, включение авторизации и хранения регистраций в kamailio.cfg, создание абонентов через kamctl и kamcli, проверка регистрации и балансировка вызовов на Asterisk модулем dispatcher.

Что такое Kamailio и где он нужен

Kamailio — открытый SIP-сервер, выросший из проекта OpenSER. Он работает как прокси, регистратор и сервер переадресации: принимает REGISTER, хранит местоположение абонентов, авторизует их и маршрутизирует INVITE и прочие запросы по правилам, которые вы описываете на собственном языке скрипта в kamailio.cfg.

Типичные роли Kamailio:

  • регистратор для тысяч абонентов, когда одного Asterisk уже не хватает;
  • SIP-балансировщик перед группой Asterisk или FreeSWITCH;
  • пограничный узел (SBC-функции): единая точка входа, защита от сканеров и флуда, сокрытие внутренней топологии;
  • маршрутизатор между операторами по префиксам, весам и стоимости.

Голос Kamailio не обрабатывает: транскодинг, запись и проигрывание звуков остаются за медиасерверами. Для проксирования RTP рядом ставят RTPEngine.

Основы протокола, без которых конфиг читать сложно, разобраны в статье Основы протокола SIP.

Подготовка Debian 12

Понадобится сервер с Debian 12 (bookworm), статическим IP и доступом в интернет. Обновите систему и поставьте утилиты:

apt update && apt -y upgrade
apt -y install curl gnupg ca-certificates

Если на сервере работает межсетевой экран, откройте порт 5060 для UDP и TCP (и 5061 для TLS, если планируете его включать).

Установка из официального репозитория

В самом Debian 12 есть пакет kamailio, но версия там отстаёт. Проект ведёт собственный репозиторий deb.kamailio.org с отдельной веткой для каждой стабильной версии. Ниже — ветка 6.0; перед установкой посмотрите на https://www.kamailio.org/, какая версия сейчас стабильная, и при необходимости замените kamailio60 на нужную.

curl -fsSL https://deb.kamailio.org/kamailiodebkey.gpg \
  | gpg --dearmor -o /usr/share/keyrings/kamailio.gpg

echo "deb [signed-by=/usr/share/keyrings/kamailio.gpg] http://deb.kamailio.org/kamailio60 bookworm main" \
  > /etc/apt/sources.list.d/kamailio.list

apt update
apt -y install kamailio kamailio-mysql-modules kamailio-tls-modules \
  kamailio-extra-modules kamailio-utils-modules

Проверьте установку:

kamailio -v

После установки в системе появляются:

Путь или команда Назначение
/etc/kamailio/kamailio.cfg основной конфиг и скрипт маршрутизации
/etc/kamailio/kamctlrc настройки утилит kamctl и kamdbctl
/etc/default/kamailio параметры запуска: память, путь к конфигу
kamctl управление абонентами, доменами, dispatcher
kamdbctl создание и обслуживание базы данных
kamcmd отправка RPC-команд работающему серверу

База данных MariaDB

apt -y install mariadb-server
systemctl enable --now mariadb

В Debian пользователь root в MariaDB по умолчанию входит через unix-сокет без пароля. Чтобы kamdbctl гарантированно смог создать базу, заведите для него отдельного администратора:

CREATE USER 'kamadmin'@'localhost' IDENTIFIED BY 'Сложный_пароль_1';
GRANT ALL PRIVILEGES ON *.* TO 'kamadmin'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Выполните это в консоли mariadb под root.

Настройка kamctlrc

Откройте /etc/kamailio/kamctlrc и раскомментируйте или задайте параметры:

SIP_DOMAIN=sip.example.local
DBENGINE=MYSQL
DBHOST=localhost
DBNAME=kamailio
DBRWUSER="kamailio"
DBRWPW="Пароль_для_kamailio"
DBROUSER="kamailioro"
DBROPW="Пароль_для_kamailioro"
DBROOTUSER="kamadmin"

SIP_DOMAIN — домен, в котором будут жить абоненты: имя сервера или его IP. Пароли по умолчанию (kamailiorw, kamailioro) обязательно замените.

Создайте базу:

kamdbctl create

Утилита спросит пароль kamadmin, кодировку (подойдёт utf8mb4 или предложенная по умолчанию) и предложит создать дополнительные таблицы для presence и расширенных модулей. Для начала можно ответить «да» на оба вопроса: лишние таблицы не мешают.

Настройка kamailio.cfg

Стандартный kamailio.cfg устроен как набор блоков, которые включаются директивами #!define. Добавьте в начало файла, сразу после строки #!KAMAILIO:

#!define WITH_MYSQL
#!define WITH_AUTH
#!define WITH_USRLOCDB
  • WITH_MYSQL загружает db_mysql.so и использует строку подключения DBURL;
  • WITH_AUTH включает модули auth и auth_db: все REGISTER и INVITE от абонентов проверяются по таблице subscriber;
  • WITH_USRLOCDB сохраняет регистрации в базе, чтобы они переживали перезапуск.

Найдите определение DBURL и пропишите пароль пользователя kamailio:

#!ifndef DBURL
#!define DBURL "mysql://kamailio:Пароль_для_kamailio@localhost/kamailio"
#!endif

В секции глобальных параметров укажите, на каком адресе слушать, и под каким именем сервер знает сам себя:

listen=udp:192.0.2.10:5060
listen=tcp:192.0.2.10:5060
alias="sip.example.local"

Если абоненты подключаются из-за NAT, добавьте #!define WITH_NAT. В свежих версиях стандартного конфига рядом есть вариант для RTPEngine (WITH_RTPENGINE); какие именно опции поддерживает ваш файл, видно по блокам #!ifdef в его начале.

Проверьте синтаксис и перезапустите сервер:

kamailio -c -f /etc/kamailio/kamailio.cfg
systemctl enable kamailio
systemctl restart kamailio
systemctl status kamailio

Объём разделяемой и приватной памяти задаётся в /etc/default/kamailio параметрами SHM_MEMORY и PKG_MEMORY (в мегабайтах). Значений по умолчанию хватает для тестового стенда; при тысячах регистраций память стоит увеличить.

Добавление абонентов

Через kamctl

kamctl add 101 Пароль101
kamctl add 102 Пароль102
kamctl db show subscriber

Если домен не указан, используется SIP_DOMAIN из kamctlrc. Сменить пароль — kamctl passwd 101 НовыйПароль, удалить абонента — kamctl rm 101.

Через kamcli

kamcli — более новая утилита на Python, которую развивает сам проект; она постепенно заменяет kamctl. Устанавливается из репозитория https://github.com/kamailio/kamcli (через pip в виртуальном окружении), настройки подключения к базе и к RPC берёт из своего файла kamcli.ini. Основные команды:

kamcli subscriber add 103 Пароль103
kamcli subscriber show 103
kamcli ul show

Для повседневной работы хватает любой из двух утилит, главное — чтобы обе смотрели в одну и ту же базу.

Несколько доменов

Чтобы обслуживать абонентов нескольких доменов, добавьте #!define WITH_MULTIDOMAIN, затем создайте домены и заведите абонентов с полным адресом:

kamctl domain add domain1.test
kamctl domain reload
kamctl add 101@domain1.test Пароль

Проверка регистрации

Настройте на двух софтфонах учётные записи: логин 101 и 102, домен sip.example.local (или IP сервера), пароли из kamctl add. После регистрации проверьте на сервере:

kamctl ul show
kamcmd ul.dump

В выводе должны быть контакты обоих абонентов с IP, портом и временем истечения регистрации. Теперь 101 может позвонить 102 и наоборот: стандартный скрипт находит абонента в таблице местоположения и проксирует вызов.

Если регистрации нет, смотрите журнал и трафик:

journalctl -u kamailio -f
apt -y install sngrep
sngrep port 5060

sngrep показывает SIP-диалоги прямо в терминале. Ответ 401 Unauthorized на первый REGISTER — норма (сервер запрашивает авторизацию), а вот повторный 401 или 403 Forbidden означает неверный логин, пароль или домен.

Как устроен стандартный маршрут

Логика стандартного kamailio.cfg проходит такие этапы:

  1. REQINIT — базовые проверки: ограничение частоты запросов (модуль pike, если включён), отсев известных сканеров по User-Agent, проверка Max-Forwards, ответ на OPTIONS к самому серверу.
  2. NATDETECT — определение абонентов за NAT и исправление контакта.
  3. CANCEL и повторные запросы — передаются в существующую транзакцию.
  4. WITHINDLG — запросы внутри уже установленного диалога (BYE, re-INVITE, ACK) идут по заголовкам Route.
  5. AUTH — проверка учётных данных для REGISTER и для вызовов от своих абонентов.
  6. REGISTRAR — сохранение регистрации в таблице location.
  7. LOCATION — поиск вызываемого абонента и отправка запроса через RELAY.

Минимальный набор модулей для работы регистратора: tm, sl, rr, auth, auth_db, usrloc, registrar.

Балансировка вызовов на Asterisk: модуль dispatcher

Частая задача — раздать вызовы на несколько серверов Asterisk. Для этого используется модуль dispatcher. В kamailio.cfg загрузите его и задайте параметры:

loadmodule "dispatcher.so"

modparam("dispatcher", "db_url", DBURL)
modparam("dispatcher", "flags", 2)
modparam("dispatcher", "ds_ping_interval", 15)
modparam("dispatcher", "ds_probing_mode", 1)
modparam("dispatcher", "ds_probing_threshold", 1)
modparam("dispatcher", "ds_ping_reply_codes", "class=2;class=3;class=4")

Маршрут отправки и перебор узлов при отказе:

route[DISPATCH] {
    # алгоритм 4 — по кругу (round-robin) внутри группы 1
    if (!ds_select_dst("1", "4")) {
        send_reply("404", "No destination");
        exit;
    }
    t_on_failure("RTF_DISPATCH");
    route(RELAY);
    exit;
}

failure_route[RTF_DISPATCH] {
    if (t_is_canceled()) {
        exit;
    }
    if (t_check_status("500") || (t_branch_timeout() && !t_branch_replied())) {
        if (ds_next_dst()) {
            t_on_failure("RTF_DISPATCH");
            route(RELAY);
            exit;
        }
    }
}

Вызов route(DISPATCH) поставьте в request_route там, где запрос адресован не локальному абоненту (например, вместо или перед route(LOCATION) для нужных номеров). Узлы группы добавляются в базу:

kamctl dispatcher add 1 sip:10.0.0.11:5060 0 0
kamctl dispatcher add 1 sip:10.0.0.12:5060 0 0
kamctl dispatcher reload
kamcmd dispatcher.list

В выводе dispatcher.list у работающих узлов флаги начинаются с A (active), у недоступных — с I или P.

Основные алгоритмы ds_select_dst:

Номер Алгоритм
0 хеш от Call-ID
1 хеш от From URI
2 хеш от To URI
3 хеш от Request URI
4 по кругу (round-robin)
5 хеш от имени пользователя при авторизации
6 случайный выбор
7 хеш от значения псевдопеременной
8 по приоритету: первый доступный узел, остальные — резерв
9 по весу (атрибут weight)
10 по текущей нагрузке (атрибуты duid, maxload)
11 относительный вес с учётом выбывших узлов

Для простого резервирования «основной + запасной» подходит алгоритм 8, для равномерной раздачи — 4 или 9.

Безопасность

Открытый в интернет SIP-сервер начинают сканировать в первые часы. Модули, которые стоит изучить:

  • pike — блокирует адреса, превышающие порог запросов;
  • permissions — списки адресов, которым разрешена регистрация или маршрутизация;
  • htable — хранение банов и счётчиков в памяти;
  • topoh / topos — сокрытие внутренних адресов и заголовков маршрутизации;
  • secfilter — фильтрация по User-Agent, IP и номерам.

Параллельно ограничьте доступ к порту 5060 на межсетевом экране и включите fail2ban по журналу Kamailio.

Что изменилось с Debian 9 и Kamailio 5.0

  • Сборка из git и самописный init-скрипт больше не нужны: пакеты из deb.kamailio.org ставят systemd-юнит и правильные пути (/etc/kamailio, /usr/lib/x86_64-linux-gnu/kamailio/modules).
  • apt-key в Debian 12 объявлен устаревшим, ключи репозиториев подключаются через signed-by, как в примере выше.
  • Для управления сервером появился kamcli, а kamctl общается с сервером через RPC-интерфейс модуля jsonrpcs вместо старого MI.

Похожий по назначению SIP-сервер — OpenSIPS; его установка описана в статье Установка и начальная настройка OpenSIPS. Полная документация по модулям Kamailio — на https://www.kamailio.org/docs/.

Частые вопросы

Чем Kamailio отличается от Asterisk?

Kamailio — SIP-прокси и регистратор: он маршрутизирует сигнализацию, авторизует абонентов и держит десятки тысяч регистраций, но не обрабатывает голос, не играет звуки и не пишет разговоры. Asterisk — B2BUA с медиаобработкой. Их часто ставят в паре: Kamailio на краю сети, Asterisk позади него.

Почему после kamctl add телефон не регистрируется?

Чаще всего в kamailio.cfg не включены WITH_MYSQL и WITH_AUTH, поэтому Kamailio не смотрит в таблицу subscriber. Также проверьте, что домен в настройках телефона совпадает с SIP_DOMAIN из kamctlrc, а порт 5060 открыт на межсетевом экране.

Нужно ли собирать Kamailio из исходников?

Обычно нет. Официальный репозиторий deb.kamailio.org содержит пакеты для актуальных Debian и Ubuntu, включая отдельные пакеты модулей. Сборка из git нужна только для разработки или нестандартных модулей.

Kamailio передаёт голос?

Нет, через Kamailio идёт только SIP-сигнализация. Если абоненты за NAT и нужен проход RTP через сервер, рядом ставят RTPEngine и подключают одноимённый модуль.

Можно ли использовать PostgreSQL вместо MariaDB?

Да: установите пакет kamailio-postgres-modules, в kamctlrc укажите DBENGINE=PGSQL, а в kamailio.cfg — WITH_PGSQL и строку подключения вида postgres://kamailio:пароль@localhost/kamailio.