Encryption in manager api customer

Manager API

The manager api is used by the GUI for requesting files, giving listing of active sessions (CALLs/REGISTERs) or other stats. Since version of a sniffer 2024.02.2 and GUI 26.20, the voipmonitor introduces encryption for xchanges between manager and the GUI. The encryption is enabled by default.

Configuration

By default you don't need to configure anything, generating the key and use it by the GUI and sniffer is fully automated.

manager api bind options

configuration in voipmonitor.conf - by default the voipmonitor sniffer binds on 127.0.0.1:5029

managerip=127.0.0.1
managerport=5029

manager's encryption options

socketfile

The volunary option for openning the socketfile used for unencrypted requests/responses of the manager api at a time of start the sniffer service.

managersocket = /tmp/vm_manager_socket

the key options

By default the voipmonitor's sniffer and GUI loads the key from voipmonitor GUI's db. You can override this by define the keys options in /etc/voipmonitor.conf it accepts the base64 form of a key - you can generate by the GUI (Read bellow)

manager_aes_key
manager_aes_iv

and In the GUI's configuration.php

VPMANAGER_AES_KEY
VPMANAGER_AES_IV

How to use the API - examples

In following examples will be introduced various ways on how to send manager command listcalls and receive the answer

id_sensor based request

php php/run.php send_manager_cmd -s 2 -c listcalls

-s id_sensor: 2
-c command: listcalls

IP:port based request

php php/run.php send_manager_cmd -h s4.voipmonitor.org -p 5029 -a -c listcalls
-h host: 10.0.0.1
-p port: 5029
-a enables encryption
-c command: listcalls

Example with filter used

php php/run.php send_manager_cmd -s 1 -c 'listcalls {"zip":"no","limit":30,"sensor_map":"yes","ip_map":"yes","filter":[{"caller":"%706123%","callerd_type":"0","callid":"706123","caller_domain":"706123","callerd_domain_type":"0","caller_agent":"706123","callerd_agent_type":"0","OR":"1","custom_header_1_7":"706123"}]}'

using sniffers socketfile

You can use unencrypted request by sending to a socket file

define socketfile in voipmonitor.conf

Define the option in /etc/voipmonitor.conf, the socket file will be created at a time of the service start, when undefined you can ask new socketfile with a manager request.

managersocket = /tmp/vm_manager_socket

enable socketfile in a runtime

Send request to an api to open manager_socket file:

echo 'manager_file start /tmp/vm_manager_socket' | nc 127.0.0.1 5029

use the socket file

You can use the socketfile this way

echo listcalls | nc -U /tmp/vm_manager_socket

the socket file remove

You can ask kmanager api for remove of the file (the removing has not real usecase)

echo 'manager_file stop' | nc 127.0.0.1 5029

use the SSH for accesing the socketfile from other host

ssh myGUIhost 'echo listcalls | nc -U /tmp/vm_manager_socket'

Hints

nc command not supports -U

In debian 10 and 12 you need to use netcat-openbsd package for installing nc binary that supports -U socketfile

How to force use of same key in two GUI/DB hosts

For HA configuration type where there are two sniffer hosts storing CDRs to same db and data from one db gets migrated to another db, you need to use same key in both DB hosts - following command will read key from HOST1 and will write it to HOST2:

key=$(echo "select content from \`system\` where type = 'manager_key'" | mysql -h HOST1 -u root -pPASS1 -D DBname1 2>/dev/null | grep key) && echo "update \`system\` set content = '$key' where type = 'manager_key'" | mysql -h HOST2 -u root -pPASS2 -D DBname2 2>/dev/null

How to disable the encryption

disables the encryption completely (not recmmended for production - use for testing/debuging)

manager_enable_unencrypted = yes

Use of the api when encryption is disabled

echo listcalls | nc 127.0.0.1 5029

.