Kamailio 6.1 常用 CLI 命令与工具详解

Kamailio 6.1 常用 CLI 命令与工具详解：kamailio 主程序启动参数与语法检查、kamctl 管理命令族、kamcmd RPC 实时管控逐命令实测，usrloc 位置表增查删闭环与排障实录。

KamailioKamailio即时通信2026/10/22

Kamailio 6.1 常用 CLI 命令与工具详解

目标：把 Kamailio 6.1.5 的四个命令行工具（kamailio 主程序、kamctl、kamcmd、kamdbctl）的常用命令一次讲全——每个命令配真实输入与实测回显，覆盖服务管理、运行状态观测、cfg 参数热改、usrloc 位置表增查删闭环与常见报错排障。已在 Ubuntu 22.04（kamailio 6.1.5，x86_64，监听 5070）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Kamailio：6.1.5（官方 apt 仓库安装，安装与配置见《Ubuntu 22.04 安装 Kamailio 6.1 指南》）
  • 监听：udp/tcp 0.0.0.0:5070（alias 10.0.0.8），服务以 service kamailio start 运行中
  • 工具路径（实测 which）：
    • /usr/sbin/kamailio：SIP 主程序（守护进程本体）
    • /usr/sbin/kamctl：管理脚本，版本号 kamctl 6.1.0，经 jsonrpcs 模块 FIFO 通信
    • /usr/sbin/kamcmd：RPC 客户端，经 ctl 模块 unix socket 通信
    • /usr/sbin/kamdbctl：数据库初始化脚本（需先安装数据库模块子包，本文环境未启 DB，仅介绍用途）

二、工具概览

四个工具的分工与通信通道（选错通道是最常见的"命令没反应"根因）：

工具角色通信通道典型用途
kamailio主程序——启动进程、-c 语法检查、-V 版本
kamctl高层管理脚本jsonrpcs FIFO（/run/kamailio/）ul 位置表、stats、uptime、服务控制
kamcmdRPC 客户端ctl unix socketcfg 参数热改、core/模块级命令
kamdbctl数据库脚本直连数据库建 kamailio 库表、加 subscriber

💡 技术拓展：Kamailio 的管控通道不止 CLI 一种，按运维场景选——

通道形式适用
kamctl / kamcmd本地 CLI日常巡检、单机排障
JSONRPC-over-HTTPxhttp + event_route[xhttp:request]远程管控面板、Prometheus exporter 类集成
binrpc（ctl 模块 TCP）tcp:<ip>:<port>跨机 RPC
KEMI 脚本 APILua/Python 嵌入把管理逻辑写进路由脚本

本文覆盖前两类中最常用的 CLI 部分；JSONRPC-over-HTTP 需在 cfg 里 #!define WITH_JSONRPC 并放行 xhttp 事件路由。

三、前置条件

  1. Kamailio 正在运行（两个 CLI 都是与运行中进程对话的客户端）：验证 kamctl uptime 有正常回显。
  2. jsonrpcs.so 与 ctl.so 已加载（官方默认 cfg 已内置）：kamctl srv modules 可核对。
  3. FIFO/socket 目录 /run/kamailio/ 存在（systemd RuntimeDirectory=kamailio 自动维护）。

四、kamailio 主程序命令详解

4.1 查看版本与编译特性（-V）

kamailio -V

实测输出：

version: kamailio 6.1.5 (x86_64/Linux)
flags: USE_TCP, USE_TLS, USE_SCTP, TLS_HOOKS, USE_RAW_SOCKS, DISABLE_NAGLE, USE_MCAST, DNS_IP_HACK, SHM_MMAP, PKG_MALLOC, MEM_JOIN_FREE, Q_MALLOC, F_MALLOC, TLSF_MALLOC, DBG_SR_MEMORY, DBG_QM_MALLOC, DBG_F_MALLOC, DBG_TLSF_MALLOC, USE_FUTEX, USE_DNS_CACHE, USE_DNS_FAILOVER, USE_NAPTR, USE_DST_BLOCKLIST, HAVE_RESOLV_RES, TLS_PTHREAD_MUTEX_SHARED
MAX_RECV_BUFFER_SIZE 262144, MAX_SEND_BUFFER_SIZE 262144, MAX_URI_SIZE 1024, BUF_SIZE 65535, DEFAULT PKG_SIZE 8MB
poll method support: poll, epoll_lt, epoll_et, sigio_rt, select.
id: unknown
compiled with gcc 11.4.0

flags 行是编译特性清单：USE_TCP/TLS/SCTP 说明协议支持，*_MALLOC 系列是内存分配器。-I 输出更详细的内部编译选项。

4.2 配置语法检查（-c）

改配置后先检查再重启的标准动作：

kamailio -c -f /etc/kamailio/kamailio.cfg

实测输出（结尾）：

config file ok, exiting...

故意写坏配置（在 kamailio-local.cfg 追加一行非法 listen=broken）再检查：

failed to initialize list addresses
 0(4883) INFO: <core> [core/sctp_core.c:53]: sctp_core_destroy(): SCTP API not initialized

-c 不占端口、不启进程，坏配置被拦在重启之前，是零中断验证配置的标准手段。

4.3 启动参数速查（-h）

kamailio -h

实测输出（节选，参数均标注真实默认行为）：

Usage: kamailio [options]
Options:
    -a mode      Auto aliases mode: enable with yes or on, disable with no or off
    --alias=val  Add a domain alias, the value has to be '[proto:]hostname[:port]'
    -A define    Add config pre-processor define (e.g., -A WITH_AUTH, -A 'FLT_ACC=1')
    -b nr        Maximum OS UDP receive buffer size which will not be exceeded by
                 auto-probing-and-increase procedure even if OS allows
    -c           Check configuration file for syntax errors
    --cfg-print  Print configuration file evaluating includes and ifdefs
    -d           Debugging level control (multiple -d to increase the level from 0)
    --debug=val  Debugging level value
    -D           Control how daemonize is done:
                 -D..do not fork (almost) anyway;
                 -DD..do not daemonize creator;
                 -DDD..daemonize (default)
    -e           Log messages printed in terminal colors (requires -E)
    -E           Log to stderr
    -f file      Configuration file (default: /etc/kamailio/kamailio.cfg)
    -g gid       Change gid (group id)
    -h           This help message
    -K           Turn on "via:" host checking when forwarding replies
    -l address   Listen on the specified address/interface (multiple -l mean
                 listening on more addresses)

高频组合：kamailio -D -E -f /etc/kamailio/kamailio.cfg 前台运行直打 stderr，排障启动首选；--cfg-print 打开展开 include/ifdef 后的完整配置，看实际生效配置比读源文件准。

五、kamctl 管理命令详解

kamctl 的命令清单用 kamctl which（不带参数等价）查看，实测命令族如下：

kamctl which

实测输出（节选）：

/usr/sbin/kamctl 6.1.0

Existing commands:

 -- command 'start|stop|restart|trap'
 trap ............................... trap with gdb Kamailio processes using RPC
 restart ............................ restart Kamailio
 start .............................. start Kamailio
 stop ............................... stop Kamailio

 -- command 'srv' - server management commands
 srv sockets ................... show the list of listen sockets
 srv aliases ................... show the list of server aliases
 srv rpclist ................... show the list of server rpc commands
 srv modules ................... show the list of loaded modules
 srv version ................... show the server version

 -- command 'ul|alias' - manage user location or aliases
 ul show [<username>]................... show in-RAM online users
 ul show --brief........................ show in-RAM online users in short format
 ul rm <username> [<contact URI>]....... delete user's usrloc entries
 ul add <username> <uri> ............... introduce a permanent usrloc entry
 ul add <username> <uri> <expires> ..... introduce a temporary usrloc entry

 -- command 'ps' - print details about running processes
 -- command 'uptime' - print uptime details
 -- command 'stats' - print internal statistics
 -- command 'rpc' - send raw RPC commands

5.1 服务控制：start / stop / restart

kamctl restart

实测输出：

Killing Kamailio: (pid(s) 4153) ...
 * Restarting Kamailio SIP Server: kamailio
   ...done.

等价于 service kamailio restart（kamctl start/stop/restart 直接操作 init 脚本）。生产运行中慎用 stop——SIP 注册与对话会中断。

5.2 运行状态观测：uptime / ps / version

kamctl uptime

实测输出：

{
  "jsonrpc":  "2.0",
  "result": {
    "now":  "Wed Oct 21 17:17:23 2026",
    "up_since": "Wed Oct 21 11:51:17 2026",
    "uptime": 19566
  },
  "id": 4690
}

kamctl ps

实测输出（节选，与 ps aux | grep kamailio 的进程一一对应）：

{
  "jsonrpc":  "2.0",
  "result": [
    {
      "IDX":  0,
      "PID":  4153,
      "DSC":  "main process - attendant"
    },
    ...
  ]
}

kamctl version

实测回显：

/usr/sbin/kamctl 6.1.0

5.3 监听与模块核对：srv 子命令

kamctl srv sockets

实测输出（节选，核对 7.2 配置的 5070 监听是否生效）：

{
  "jsonrpc":  "2.0",
  "result": [
    {
      "af": "IPv4",
      "proto":  "udp",
      "name": "0.0.0.0",
      "port": "5070"
    }
  ]
}

kamctl srv modules

实测输出（节选）：

{
  "jsonrpc":  "2.0",
  "result": [
    "dlgs",
    "counters",
    "acc",
    "cfg_rpc",
    "ctl",
    "sanity"
  ]
}

5.4 位置表管理：ul 增查删闭环

usrloc（user location）表是注册服务器的核心数据。逐条实测完整闭环：

增——手工加一条永久 AOR：

kamctl ul add 1002@10.0.0.8 sip:1002@10.0.0.8:5060

实测输出（结尾，jsonrpc 成功回执）：

  "id": 5117
}

查——看指定 AOR：

kamctl ul show 1002@10.0.0.8

实测输出（节选）：

    "AoR":  "1002",
          "Address":  "sip:1002@10.0.0.8:5060",
          "Expires":  "permanent",

Expires: permanent 即手工条目不会自动过期。带第三个参数可加临时条目：kamctl ul add 1002@10.0.0.8 sip:1002@10.0.0.8:5060 600（600 秒后过期）。全表概览用短格式：

kamctl ul show --brief

实测输出（节选）：

{
  "jsonrpc":  "2.0",
  "result": {
    "Domains":  [
      {
        "Domain": {
          "Domain": "location",
          "Size": 1024
        }
      }
    ]
  }
}

删——移除条目并验证：

kamctl ul rm 1002@10.0.0.8

实测输出（节选）：

  "result": {
  },

再查已删 AOR，实测返回明确错误态：

{
  "jsonrpc":  "2.0",
  "error":  {
    "code": 500,
    "message":  "AOR not found in location table"
  }
}

⚠️ 排障实录：ul add / ul show 的用户名参数必须带域。实测漏写域直接报错：

** ERROR: domain unknown: use usernames with domain or set default domain in SIP_DOMAIN

两种解决：① 命令里写全 1002@10.0.0.8 形式（如上）；② 编辑 /etc/kamailio/kamctlrc 加一行 SIP_DOMAIN=10.0.0.8，此后 kamctl ul add 1002 ... 自动补域。

5.5 统计与原始 RPC：stats / rpc

kamctl stats

实测输出（节选，全量统计等价于 kamcmd 按组拉取）：

{
  "jsonrpc":  "2.0",
  "result": [
    "core:bad_URIs_rcvd = 0",
    "core:bad_msg_hdr = 0",
    "core:drop_replies = 0",
    "core:rcv_replies = 0"
  ]
}

kamctl 也能发任意 RPC 原始命令，等价于 kamcmd 的通道差异版：

kamctl rpc core.version

实测输出：

{
  "jsonrpc":  "2.0",
  "result": "kamailio 6.1.5 (x86_64/Linux) ",
  "id": 4818
}

六、kamcmd RPC 客户端详解

kamcmd 走 ctl 模块 unix socket（/run/kamailio/kamailio_ctl），输出比 kamctl 更紧凑（非 JSON）。命令组清单：

kamcmd help

实测输出（节选）：

cfg.add_group_inst
cfg.commit
cfg.del
cfg.del_group_inst
cfg.diff
cfg.get
cfg.help
...

6.1 核心信息：core.version / uptime / psx / shmmem

kamcmd core.version

实测回显：

kamailio 6.1.5 (x86_64/Linux)

kamcmd core.uptime

实测输出：

{
        now: Wed Oct 21 17:14:52 2026
        up_since: Wed Oct 21 11:51:17 2026
        uptime: 19415
}

kamcmd core.psx

实测输出（节选；children=8 对应 8 个 udp receiver child）：

{
        IDX: 0
        PID: 4153
        DSC: main process - attendant
}
{
        IDX: 1
        PID: 4154
        DSC: udp receiver child=0 sock=0.0.0.0:5070
}

kamcmd core.shmmem

实测输出（共享内存水位，64MB 分配对应 /etc/default/kamailio 的 SHM_MEMORY=64）：

{
        total: 67108864
        free: 64223392
        used: 2607008
        real_used: 2885472
        max_used: 2885472
        fragments: 1
}

6.2 cfg 参数热改：cfg.get / cfg.seti

kamcmd cfg.get core debug

实测回显：

2

kamcmd cfg.seti core debug 3
kamcmd cfg.get core debug
kamcmd cfg.seti core debug 2

实测回显：

3

（完整的热改闭环与"重启回退"注意事项见《Kamailio 6.1 配置参数详解》3.2 节。）

6.3 统计拉取：stats.get_statistics

支持按组、多组连查（组名后缀冒号）：

kamcmd stats.get_statistics core: sl: usrloc:

实测输出（节选；sl:200_replies/sl:403_replies 与实测 REGISTER 行为精确对应）：

core:rcv_requests = 5
sl:200_replies = 4
sl:403_replies = 1
usrloc:location-contacts = 1
usrloc:location-users = 1

6.4 套接字核对：core.sockets_list

kamcmd core.sockets_list

实测输出（节选）：

{
        socket: {
                af: IPv4
                proto: udp
                address: 0.0.0.0
                port: 5070
                mcast: no
                mhomed: no
                virtual: no
        }
}

七、kamdbctl 简介

kamdbctl 是数据库初始化脚本，负责创建 kamailio 库的全部表结构（subscriber、location、acc、dispatcher 等）。使用前置条件：安装对应数据库模块子包（如 apt-get install kamailio-mysql-modules）并在 /etc/kamailio/kamctlrc 配置 DBENGINE=MYSQL、数据库连接参数。常用命令：

kamdbctl create   # 创建 kamailio 库与全部标准表
kamdbctl reinit   # 重建（清空现有数据）
kamdbctl presence # 补建 presence 相关表

本文实测环境为纯内存 usrloc（未启用数据库），上述命令为 kamdbctl 6.1.0 的标准用法；启用 WITH_MYSQL + WITH_AUTH 后由 kamctl add <user> <password> 添加 SIP 用户。

八、注意事项

  1. 选对通道：kamctl 报 ERROR: doesn't support FIFO 类错误通常是 jsonrpcs 的 FIFO 未创建——核对 kamctlrc 中 RPC_FIFO 路径与进程 RuntimeDirectory 权限；kamcmd 连接拒绝则核对 ctl 模块 unix socket /run/kamailio/kamailio_ctl 是否存在。
  2. stop 是真停：kamctl stop / service kamailio stop 会中断全部注册与对话，高可用场景优先滚动重启。
  3. 热改不落盘：kamcmd cfg.seti 只改运行值，重启即回退（见《Kamailio 6.1 配置参数详解》Q1）。
  4. 语法检查前置于重启：任何 cfg 改动先 kamailio -c -f <文件>，实测坏配置会被 -c 拦下（4.2 节双态输出）。
  5. ul 操作用户名带域：否则报 domain unknown（5.4 排障实录），或 kamctlrc 落 SIP_DOMAIN。

九、常见问题（FAQ）

Q1：kamctl 命令卡住无输出？ kamctl 经 FIFO 与进程通信，若 Kamailio 实际没在运行，FIFO 不存在会等待超时。先 service kamailio status 确认进程态，再重试；FIFO 路径以 kamctlrc 的 RPC_FIFO（默认 /run/kamailio/kamailio_rpc.fifo）为准。

Q2：ul show 全表输出太长，怎么只看摘要？ kamctl ul show --brief 只列域与计数；单个用户用 kamctl ul show <user>@<domain> 精确查询；内存表规模看 kamcmd stats.get_statistics usrloc: 的 location-users/location-contacts 计数。

Q3：kamcmd 与 kamctl 同一命令结果格式不同？ 正常。kamctl 是脚本封装、输出 JSONRPC 原文；kamcmd 是二进制协议客户端、输出紧凑键值对。两者最终调的是同一套 RPC 命令，数值一致（实测 core.version 两通道同回 kamailio 6.1.5 (x86_64/Linux)）。

Q4：如何确认某个模块真的加载了？ kamctl srv modules 列出全部已加载模块名（5.3 节实测）；模块级命令是否存在可用 kamcmd help | grep <模块名> 过滤。

十、参考链接