kamcli

KAMCLI

Kamailio Command Line Interface Control Tool.

Kamailio is an open source SIP (RFC3261) server available at:

• https://www.kamailio.org

kamcli is aiming at being a modern and extensible alternative to the shell script kamctl.

It requires that jsonrpcs module of Kamailio is loaded and configured to listen on a Unix domain socket or FIFO file. The way to interact with Kamailio has to be set inside kamcli config file (kamcli.ini).

Important Note

The master branch of kamcli is under ongoing work to upgrade the code to work with Python3. Migration to Python3 is required because Python2 has been deprecated and it is going to be removed from major Linux distributions.

Therefore, for the moment, not all commands may work with Python3, if you find any problem, file a report on Issue Tracker.

To run kamcli with Python2.x, use the git branch v1.2-python2. The branch will be kept for a while, but likely there will be no new features added to it.

Features

The prototype of using kamcli is:

kamcli [options] command [arguments]

New commands for kamcli can be implemented as plugins, each command being implemented in a file located in kamcli/commands/.

Among implemented commands:

• address - manage permissions address records
• aliasdb - manage database aliases
• config - manage configuration file for kamcli
• db - manage kamailio database content
• dialog - manage active calls (dialog)
• dialplan - manage dialplan records
• dispatcher - manage load balancer (dispatcher)
• domain - manage domain records
• group - manage group membership records (acl)
• moni - continuous refresh of the values for a list of statistics
• mtree - manage memory trees (mtree)
• ps - print the details for kamailio running processes
• rpc - interact with kamailio via jsonrpc control commands (alias of jsonrpc)
• rpcmethods - return the list of available RPC methods (commands)
• rtpengine - manage RTPEngine records and instances
• speeddial - manage speed dial records
• srv - server management commands (sockets, aliases, ...)
• stats - get kamailio internal statistics
• subscriber - manage SIP subscribers
• tcp - management commands for TCP connections
• tls - management commands for TLS profiles and connections
• uacreg - manage uac remote registration records
• ul - manage user location records
• uptime - print the uptime for kamailio instance

Each kamcli command can offer many subcommands. The help for each command can be seen with:

kamcli command --help

The help for each subcommand can be seen with:

kamcli command subcommand --help

Installation

Requirements

OS Packages (install via apt, yum, ...):

• python3 (python version 3.x)
• python3-pip
• python3-dev (optional - needed to install mysqlclient via pip)
• python3-venv (optional - needed to install virtual environment)

PIP Packages (install via pip3):

• extra packages requied by kamcli (part of OS or virtual environment)
  • click
  • sqlalchemy
  • mysql-python (optional - needed if you want to connect to MySQL database)
  • tabulate (optional - needed if you want to have table-formatted output for various commands)
  • pyaml (optional - needed if you want to print json result as yaml (more compact))

Install Virtual Environment

It is recommended to install in a virtual environment at least for development. Some useful details about installing Click in virtual environament are available at:

• http://click.pocoo.org/4/quickstart/#virtualenv

For example, create the virtual environemnt in the folder venv:

  $ apt install python3-venv
  $ mkdir kamclienv
  $ cd kamclienv
  $ python3 -m venv venv

To activate the virtual environment:

  $ . venv/bin/activate

Clone kamcli and install it. The commands can be done inside the virtual environment if activate to be available only there or without virtual environment to be installed in the system.

  $ git clone https://github.com/kamailio/kamcli.git
  $ cd kamcli
  $ pip3 install --editable .

The pip3 install command installs the dependencies appart of the database connector module needed on top of sqlalchemy. You need to install your wanted database module -- e.g., for MySQL use pip3 to install mysqlclient.

To deactivate the virtual environment, run:

  $ deactivate

Install on Debian

Should work on: Ubuntu or Mint

Note: you may have to replace python with python3 and pip with pip3 in package names, installation and execution commands.

To get kamcli completely installed on Debian with MySQL support, run following commands:

apt-get install python3 python3-pip python3-venv python3-dev
mkdir kamclienv
cd kamclienv
python3 -m venv venv
. venv/bin/activate
pip3 install click
pip3 install sqlalchemy
pip3 install mysqlclient
pip3 install tabulate
pip3 install pyaml
git clone https://github.com/kamailio/kamcli.git
cd kamcli
pip3 install --editable .

To see if all was installed properly, run:

kamcli --help

Configuration File

Kamcli uses a configuration file with INI format. The name is kamcli.ini and it looks for it in:

• /etc/kamcli/kamcli.ini
• ~/.kamcli/kamcli.ini
• the value of --config command line parameter

The installation process doesn't deploy the configuration file yet.

A sample kamailio.ini is available in sources, at kamcli/kamcli.ini.

Note: not all configuration file options in kamcli.ini are used at this moment, some values are hardcoded, being planned to be replaced with the configuration options.

Usage

Read the help messages:

  $ kamcli --help
  $ kamcli <command> --help
  $ kamcli <command> <subcommand> --help

Examples of Commands

Sample commands to understand quicker the capabilities and how to use it:

kamcli -d --config=kamcli/kamcli.ini --help

kamcli --config=kamcli/kamcli.ini subscriber show
kamcli --config=kamcli/kamcli.ini subscriber add test test00
kamcli --config=kamcli/kamcli.ini subscriber show test
kamcli --config=kamcli/kamcli.ini subscriber show --help
kamcli -d --config=kamcli/kamcli.ini subscriber passwd test01 test10
kamcli -d --config=kamcli/kamcli.ini subscriber add -t no test02 test02
kamcli -d --config=kamcli/kamcli.ini subscriber setattrs test01 rpid +123
kamcli -d --config=kamcli/kamcli.ini subscriber setattrnull test01 rpid

kamcli -d --config=kamcli/kamcli.ini jsonrpc --help
kamcli -d --config=kamcli/kamcli.ini jsonrpc core.psx
kamcli -d --config=kamcli/kamcli.ini jsonrpc system.listMethods
kamcli -d --config=kamcli/kamcli.ini jsonrpc stats.get_statistics
kamcli -d --config=kamcli/kamcli.ini jsonrpc stats.get_statistics all
kamcli -d --config=kamcli/kamcli.ini jsonrpc stats.get_statistics shmem:
kamcli -d --config=kamcli/kamcli.ini jsonrpc --dry-run system.listMethods

kamcli -d --config=kamcli/kamcli.ini config raw
kamcli -d --config=kamcli/kamcli.ini config show main db
kamcli -d --config=kamcli/kamcli.ini --no-default-configs config show main db

kamcli -d --config=kamcli/kamcli.ini db connect
kamcli -d --config=kamcli/kamcli.ini db show -F table version
kamcli -d --config=kamcli/kamcli.ini db show -F json subscriber
kamcli -d --config=kamcli/kamcli.ini db showcreate version
kamcli -d --config=kamcli/kamcli.ini db showcreate -F table version
kamcli -d --config=kamcli/kamcli.ini db showcreate -F table -S html version
kamcli -d --config=kamcli/kamcli.ini db clirun "describe version"
kamcli -d --config=kamcli/kamcli.ini db clishow version
kamcli -d --config=kamcli/kamcli.ini db clishowg subscriber


kamcli -d --config=kamcli/kamcli.ini ul showdb
kamcli -d --config=kamcli/kamcli.ini ul show
kamcli -d --config=kamcli/kamcli.ini ul rm test
kamcli -d --config=kamcli/kamcli.ini ul add test sip:[email protected]

kamcli -d --config=kamcli/kamcli.ini stats
kamcli -d --config=kamcli/kamcli.ini stats usrloc
kamcli -d --config=kamcli/kamcli.ini stats -s registered_users
kamcli -d --config=kamcli/kamcli.ini stats usrloc:registered_users

Kamailio Configuration

It requires to load the jsnorpcs module in kamalilio.cfg and enable the FIFO or UnixSocket transports (they should be enabled by default).

loadmodule "jsonrpcs.so"

# ----- jsonrpcs params -----
# - explicit enable of fifo and unixsocket transports
modparam("jsonrpcs", "transport", 6)
# - pretty format for output
modparam("jsonrpcs", "pretty_format", 1)

License

GPLv2

Copyright: asipto.com