Building a Custom CLI Management Tool for VoIP Servers

Shell Script Wrapper for Asterisk + ViciDial + MySQL

Introduction
Architecture Overview
Prerequisites
The Complete Script
Installation
Command Reference
Bash Completion
Usage Examples
Adding New Commands
Usage Logging & Audit Trail
Team Standardization
Adapting for Other PBX Systems
Security Considerations
Production Checklist

Introduction

The Problem

Managing a VoIP server means constantly switching between Asterisk CLI commands, MySQL queries, log files, system utilities, and service management tools. A typical troubleshooting session might look like this:

# Check if SIP trunks are up
asterisk -rx "sip show peers" | grep -E "(trunk|provider)"

# How many calls are active?
asterisk -rx "core show channels concise" | wc -l

# Which agents are logged in?
mysql -u cron -pSECRET asterisk -e "SELECT user, full_name FROM vicidial_live_agents;"

# Tail the Asterisk log for errors
tail -f /var/log/asterisk/messages | grep ERROR

# Check disk space
df -h

# Check mail spool size (Asterisk loves generating mail)
du -sh /var/mail/root

Every one of these commands requires you to remember exact syntax, table names, log paths, and credentials. Multiply this by four or five servers and a team of three admins, and you have a recipe for wasted time, inconsistent procedures, and avoidable mistakes.

The Solution

Build a single command-line tool -- a shell script wrapper -- that encapsulates every common operation behind short, memorable subcommands:

vinit sip              # SIP peer status
vinit calls            # Active call count + details
vinit agents           # Logged-in agents
vinit log              # Tail Asterisk log
vinit db               # MySQL console
vinit status           # System overview

One command. No credentials to remember. No syntax to look up. Consistent across every server in your fleet.

Why It Works

This is not a complex orchestration framework or a web dashboard. It is a 200-line Bash script that solves a real daily problem:

Speed. Typing vinit calls is faster than asterisk -rx "core show channels concise" | wc -l. Over hundreds of daily invocations, the time savings compound.
Accuracy. The MySQL queries are written once, tested once, and used forever. No more typos in table names or forgotten WHERE clauses.
Onboarding. A new admin can run vinit help and immediately see every available operation. No tribal knowledge required.
Consistency. Every team member runs the same commands and gets the same output format. Troubleshooting conversations become easier: "What does vinit agents show on Charlie?"
Safety. Dangerous operations (database writes, service restarts) are either omitted or gated behind confirmation prompts. Read-only queries are the default.

This tool has been running in production across a multi-server ViciDial deployment, used daily by admins managing SIP trunks, agents, campaigns, and call routing. It handles the 80% of operations that you perform repeatedly, and gets out of your way for the other 20%.

Architecture Overview

                    +------------------+
                    |   Admin types:   |
                    |   vinit <cmd>    |
                    +--------+---------+
                             |
                             v
                    +------------------+
                    |   /usr/local/bin |
                    |   /vinit         |
                    |   (Bash script)  |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
              v              v              v
      +-------+----+  +-----+------+  +----+-------+
      |  Asterisk  |  |   MySQL    |  |   System   |
      |  CLI (AMI) |  | (asterisk  |  | Utilities  |
      |            |  |  database) |  |            |
      +------------+  +------------+  +------------+
      - sip show       - vicidial_    - tail, df
        peers            live_agents  - du, uptime
      - core show      - vicidial_    - systemctl
        channels         users        - mailq
      - sip reload     - system_      - postfix
                         settings

The script acts as a thin dispatcher. Each subcommand maps to one or more underlying operations: an Asterisk CLI command via asterisk -rx, a MySQL query, a systemctl call, or a standard Unix utility. The script adds no abstraction layers, daemons, or dependencies beyond what is already on the server.

Prerequisites

Operating System: Any Linux distribution (CentOS, openSUSE/ViciBox, Debian, Ubuntu)
Asterisk: Version 11+ (tested through Asterisk 20)
ViciDial: Any version with standard database schema
MySQL/MariaDB: With a read-only or limited-privilege user for queries
Bash: Version 4+ (standard on all modern Linux)
Root access: The script runs Asterisk CLI commands that require root or the asterisk group

No additional packages, languages, or frameworks are needed.

The Complete Script

Save this as /usr/local/bin/vinit. The script is presented in full, ready to deploy. Every placeholder is marked clearly.

#!/bin/bash
#============================================================================
# vinit - VoIP Server Management CLI
#
# A single command-line tool that wraps common Asterisk, ViciDial, MySQL,
# and system management tasks into quick subcommands.
#
# Usage: vinit <command> [arguments]
# Help:  vinit help
#
# Installation:
#   cp vinit /usr/local/bin/vinit
#   chmod +x /usr/local/bin/vinit
#
# Author:  Your Name / Your Team
# Version: 1.0
# License: MIT
#============================================================================

VERSION="1.0"

#============================================================================
# CONFIGURATION
# Edit these variables to match your server environment.
#============================================================================

# MySQL credentials for read-only queries.
# Use a dedicated user with SELECT-only privileges.
DB_USER="your_db_user"
DB_PASS="your_db_password"
DB_NAME="asterisk"

# Log file paths (vary by distribution)
AST_LOG="/var/log/asterisk/messages"
AST_LOG_FULL="/var/log/asterisk/full"
VICI_LOG_DIR="/var/log/astguiclient"

# Mail spool path
MAIL_SPOOL="/var/mail/root"

# SmokePing data directory (if installed)
SMOKEPING_DATA="/opt/smokeping/data"

# Server IP (used in URL output). Replace with your server IP or hostname.
SERVER_IP="YOUR_SERVER_IP"

#============================================================================
# HELPER FUNCTIONS
#============================================================================

# Run a MySQL query and suppress the password warning.
# Usage: db_query "SELECT ..."
db_query() {
    mysql -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" -e "$1" 2>/dev/null
}

# Run a MySQL query, return raw value (no headers, no table formatting).
# Usage: db_value "SELECT COUNT(*) FROM ..."
db_value() {
    mysql -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" -N -e "$1" 2>/dev/null
}

# Run an Asterisk CLI command.
# Usage: ast_cmd "sip show peers"
ast_cmd() {
    asterisk -rx "$1"
}

# Print a section header.
header() {
    echo "=== $1 ==="
    echo ""
}

#============================================================================
# HELP
#============================================================================

show_help() {
    cat <<'HELPTEXT'
vinit - VoIP Server Management CLI (v1.0)
=============================================

Usage: vinit <command> [arguments]

SIP MANAGEMENT:
  sip                  Show all SIP peer status
  sip <peer>           Show detailed info for a specific SIP peer
  sip reload           Reload SIP configuration (no restart)

CALL MONITORING:
  calls                Show active calls with details
  calls count          Show only the active call count
  channels             Show active channels with codec/duration info

AGENT MANAGEMENT:
  agents               Show all logged-in agents
  agents <user>        Show detailed info for a specific agent

LOG ACCESS:
  log                  Tail Asterisk messages log (Ctrl+C to exit)
  log full             Tail Asterisk full log (Ctrl+C to exit)
  log grep <pattern>   Search Asterisk logs for a pattern

DATABASE:
  db                   Open interactive MySQL console (asterisk database)
  db query "<sql>"     Run a single SQL query and display results

MAIL MANAGEMENT:
  mail                 Show mail spool size and queue status
  mail clean           Truncate the mail spool to free disk space

SMOKEPING:
  smokeping status     Show SmokePing service status
  smokeping start      Start SmokePing service
  smokeping stop       Stop SmokePing service

SYSTEM:
  status               Show system overview (uptime, disk, memory, Asterisk)

GENERAL:
  help                 Show this help message
  version              Show version information

EXAMPLES:
  vinit sip                          Check all SIP trunk registrations
  vinit sip my_trunk                 Debug a specific SIP peer
  vinit calls                        See what is happening right now
  vinit agents                       Who is logged in?
  vinit agents 1001                  Details for agent 1001
  vinit log grep "INVITE"            Search logs for SIP INVITEs
  vinit db query "SELECT COUNT(*)    Quick database query
    FROM vicidial_log
    WHERE call_date > NOW() - INTERVAL 1 HOUR;"
  vinit status                       Quick server health check

HELPTEXT
}

#============================================================================
# COMMAND IMPLEMENTATIONS
#============================================================================

# --- SIP MANAGEMENT ---

cmd_sip() {
    case "${1:-}" in
        "")
            header "SIP Peers"
            ast_cmd "sip show peers"
            ;;
        reload)
            echo "Reloading SIP configuration..."
            ast_cmd "sip reload"
            echo "SIP config reloaded. Verify with: vinit sip"
            ;;
        *)
            header "SIP Peer: $1"
            ast_cmd "sip show peer $1"
            ;;
    esac
}

# --- CALL MONITORING ---

cmd_calls() {
    case "${1:-}" in
        count)
            local count
            count=$(ast_cmd "core show channels concise" | wc -l)
            echo "Active calls: $count"
            ;;
        "")
            local count
            count=$(ast_cmd "core show channels concise" | wc -l)
            echo "Active calls: $count"
            echo ""
            ast_cmd "core show channels verbose"
            ;;
        *)
            echo "Usage: vinit calls [count]"
            ;;
    esac
}

cmd_channels() {
    header "Active Channels"
    ast_cmd "core show channels"
}

# --- AGENT MANAGEMENT ---

cmd_agents() {
    case "${1:-}" in
        "")
            header "Logged-In Agents"
            db_query "
                SELECT
                    la.user,
                    vu.full_name,
                    la.status,
                    la.campaign_id,
                    la.calls_today,
                    la.last_call_time
                FROM vicidial_live_agents la
                JOIN vicidial_users vu ON la.user = vu.user
                ORDER BY la.campaign_id, la.user;
            "
            echo ""
            echo "Total: $(db_value "SELECT COUNT(*) FROM vicidial_live_agents;") agents logged in"
            ;;
        *)
            header "Agent Details: $1"
            db_query "
                SELECT
                    la.user,
                    vu.full_name,
                    la.status,
                    la.server_ip,
                    la.campaign_id,
                    la.closer_campaigns,
                    la.calls_today,
                    la.last_call_time,
                    la.last_call_finish,
                    la.lead_id,
                    la.callerid,
                    la.channel,
                    la.uniqueid,
                    la.pause_code
                FROM vicidial_live_agents la
                JOIN vicidial_users vu ON la.user = vu.user
                WHERE la.user = '$1';
            "
            if [ "$(db_value "SELECT COUNT(*) FROM vicidial_live_agents WHERE user='$1';")" -eq 0 ]; then
                echo "Agent '$1' is not currently logged in."
                echo ""
                echo "User record:"
                db_query "
                    SELECT user, full_name, user_level, user_group, active
                    FROM vicidial_users
                    WHERE user = '$1';
                "
            fi
            ;;
    esac
}

# --- LOG ACCESS ---

cmd_log() {
    case "${1:-}" in
        "")
            echo "Tailing $AST_LOG (Ctrl+C to exit)..."
            tail -f "$AST_LOG"
            ;;
        full)
            if [ -f "$AST_LOG_FULL" ]; then
                echo "Tailing $AST_LOG_FULL (Ctrl+C to exit)..."
                tail -f "$AST_LOG_FULL"
            else
                echo "Full log not found at $AST_LOG_FULL"
                echo "Falling back to messages log..."
                tail -f "$AST_LOG"
            fi
            ;;
        grep)
            if [ -z "${2:-}" ]; then
                echo "Usage: vinit log grep <pattern>"
                echo "Example: vinit log grep INVITE"
                exit 1
            fi
            header "Log Search: $2"
            grep -i "$2" "$AST_LOG" | tail -100
            echo ""
            echo "(Showing last 100 matches from $AST_LOG)"
            ;;
        *)
            echo "Usage: vinit log [full|grep <pattern>]"
            ;;
    esac
}

# --- DATABASE ---

cmd_db() {
    case "${1:-}" in
        "")
            echo "Connecting to MySQL (database: $DB_NAME)..."
            mysql -u "$DB_USER" -p"$DB_PASS" "$DB_NAME"
            ;;
        query)
            if [ -z "${2:-}" ]; then
                echo "Usage: vinit db query \"SELECT ...\""
                exit 1
            fi
            db_query "$2"
            ;;
        *)
            echo "Usage: vinit db [query \"<sql>\"]"
            ;;
    esac
}

# --- MAIL MANAGEMENT ---

cmd_mail() {
    case "${1:-}" in
        "")
            header "Mail Status"
            echo "Mail spool:"
            if [ -f "$MAIL_SPOOL" ]; then
                echo "  Size: $(du -sh "$MAIL_SPOOL" 2>/dev/null | cut -f1)"
                echo "  Lines: $(wc -l < "$MAIL_SPOOL" 2>/dev/null)"
            else
                echo "  (empty or not found)"
            fi
            echo ""
            echo "Mail queue:"
            mailq 2>/dev/null | tail -5
            ;;
        clean)
            if [ -f "$MAIL_SPOOL" ]; then
                local size
                size=$(du -sh "$MAIL_SPOOL" 2>/dev/null | cut -f1)
                echo "Current spool size: $size"
                echo -n "Truncating $MAIL_SPOOL... "
                : > "$MAIL_SPOOL"
                echo "done."
                echo "Freed: $size"
            else
                echo "Mail spool not found at $MAIL_SPOOL"
            fi
            ;;
        *)
            echo "Usage: vinit mail [clean]"
            ;;
    esac
}

# --- SMOKEPING ---

cmd_smokeping() {
    case "${1:-}" in
        status)
            header "SmokePing Status"
            systemctl status smokeping --no-pager 2>&1 | head -10
            echo ""
            if [ -d "$SMOKEPING_DATA" ]; then
                local targets
                targets=$(find "$SMOKEPING_DATA" -name "*.rrd" 2>/dev/null | wc -l)
                echo "Monitoring targets: $targets"
            fi
            echo "Web UI: http://$SERVER_IP/smokeping/"
            ;;
        start)
            echo "Starting SmokePing..."
            systemctl start smokeping
            systemctl status smokeping --no-pager | head -5
            ;;
        stop)
            echo "Stopping SmokePing..."
            systemctl stop smokeping
            echo "SmokePing stopped."
            ;;
        *)
            echo "Usage: vinit smokeping [status|start|stop]"
            ;;
    esac
}

# --- SYSTEM OVERVIEW ---

cmd_status() {
    header "System Overview"

    echo "Hostname:  $(hostname)"
    echo "Uptime:    $(uptime -p 2>/dev/null || uptime)"
    echo "Load:      $(cat /proc/loadavg | cut -d' ' -f1-3)"
    echo ""

    echo "Memory:"
    free -h | grep -E "^(Mem|Swap):" | while read -r line; do
        echo "  $line"
    done
    echo ""

    echo "Disk:"
    df -h / | tail -1 | awk '{printf "  Root: %s used of %s (%s)\n", $3, $2, $5}'
    echo ""

    echo "Asterisk:"
    if pgrep -x asterisk > /dev/null; then
        local ast_ver
        ast_ver=$(ast_cmd "core show version" | head -1)
        echo "  Status:  RUNNING"
        echo "  Version: $ast_ver"
        echo "  Calls:   $(ast_cmd "core show channels concise" | wc -l) active"
        echo "  Peers:   $(ast_cmd "sip show peers" | tail -1)"
    else
        echo "  Status:  NOT RUNNING"
    fi
    echo ""

    echo "ViciDial:"
    local agent_count
    agent_count=$(db_value "SELECT COUNT(*) FROM vicidial_live_agents;" 2>/dev/null)
    if [ -n "$agent_count" ]; then
        echo "  Agents:  $agent_count logged in"
        echo "  Schema:  $(db_value "SELECT db_schema_version FROM system_settings LIMIT 1;" 2>/dev/null)"
    else
        echo "  Database: connection failed"
    fi
    echo ""

    echo "Mail spool: $(du -sh "$MAIL_SPOOL" 2>/dev/null | cut -f1 || echo 'empty')"
}

#============================================================================
# MAIN DISPATCHER
#============================================================================

case "${1:-help}" in
    sip)              shift; cmd_sip "$@" ;;
    calls)            shift; cmd_calls "$@" ;;
    channels)         cmd_channels ;;
    agents)           shift; cmd_agents "$@" ;;
    log)              shift; cmd_log "$@" ;;
    db)               shift; cmd_db "$@" ;;
    mail)             shift; cmd_mail "$@" ;;
    smokeping)        shift; cmd_smokeping "$@" ;;
    status)           cmd_status ;;
    help|--help|-h)   show_help ;;
    version|-v|--version)
        echo "vinit - VoIP Server Management CLI v$VERSION"
        ;;
    *)
        echo "Unknown command: $1"
        echo "Run 'vinit help' for usage information."
        exit 1
        ;;
esac

Installation

Step 1: Create the Script

# Copy the script to the system binary path
sudo cp vinit /usr/local/bin/vinit

# Make it executable
sudo chmod +x /usr/local/bin/vinit

# Verify it is in PATH
which vinit
# Expected output: /usr/local/bin/vinit

Step 2: Configure Credentials

Open the script and edit the configuration block at the top:

sudo nano /usr/local/bin/vinit

Update these variables:

DB_USER="your_db_user"       # MySQL user with SELECT privileges
DB_PASS="your_db_password"   # Password for that user
DB_NAME="asterisk"           # Database name (usually "asterisk")
SERVER_IP="YOUR_SERVER_IP"   # This server's IP address

Step 3: Create a Dedicated MySQL User

Never use the root MySQL user in the script. Create a read-only user with only the permissions needed:

-- Connect to MySQL as root
mysql -u root -p

-- Create dedicated user for the CLI tool
CREATE USER 'vinit_ro'@'localhost' IDENTIFIED BY 'GENERATE_A_STRONG_PASSWORD';

-- Grant read-only access to the ViciDial database
GRANT SELECT ON asterisk.* TO 'vinit_ro'@'localhost';

-- Apply changes
FLUSH PRIVILEGES;

Step 4: Test

# Should display help text
vinit help

# Should show SIP peers (requires Asterisk running)
vinit sip

# Should show system overview
vinit status

Step 5: Deploy to Multiple Servers

For a fleet of servers, use a simple deploy script:

#!/bin/bash
# deploy-vinit.sh - Push vinit to all servers

SERVERS="alpha bravo charlie delta"

for server in $SERVERS; do
    echo "Deploying to $server..."
    scp /usr/local/bin/vinit "$server":/usr/local/bin/vinit
    ssh "$server" "chmod +x /usr/local/bin/vinit"
    echo "  Done."
done

echo "Deployed to all servers."
echo "NOTE: Edit DB_USER/DB_PASS/SERVER_IP on each server."

After deploying, SSH into each server and update the configuration variables. Each server will have its own IP and potentially different database credentials.

Command Reference

SIP Management

vinit sip -- Show all SIP peer status.

Runs sip show peers on the Asterisk CLI. Shows every registered SIP device, trunk, and softphone with its IP address, port, and status (OK, UNREACHABLE, LAGGED, UNKNOWN).

$ vinit sip
=== SIP Peers ===

Name/username     Host            Dyn Forcerport Comedia  ACL Port  Status
protech/protech   10.20.30.40      D  Auto (No)  No       A  5060  OK (24 ms)
agent_1001/1001   192.168.1.50     D  Auto (Yes) Yes      A  5060  OK (32 ms)
agent_1002/1002   192.168.1.51     D  Auto (Yes) Yes      A  5060  OK (28 ms)
zoiper_ext/301    (Unspecified)     D  Auto (No)  No       A  0     UNKNOWN
4 sip peers [Monitored: 3 online, 1 offline  Unmonitored: 0 online, 0 offline]

vinit sip <peer> -- Show detailed information for a specific SIP peer.

Runs sip show peer <name>. Shows the full configuration: codecs, NAT settings, registration status, qualify time, ACLs, and more. Essential for debugging registration or audio issues.

$ vinit sip protech
=== SIP Peer: protech ===

  * Name       : protech
  Secret       : <Set>
  Context      : trunkinbound
  Subscr.Cont. : <Not set>
  Callerid     : "" <>
  Codecs       : (alaw|ulaw)
  Status       : OK (24 ms)
  Useragent    : Odin/1.0
  Reg. Contact : sip:protech@10.20.30.40:5060
  ...

vinit sip reload -- Reload the SIP configuration without restarting Asterisk.

Runs sip reload. This re-reads sip.conf and sip-vicidial.conf without dropping active calls. Use this after adding or modifying SIP peers.

$ vinit sip reload
Reloading SIP configuration...
Peer 'protech' is now Reachable. (24ms / 2000ms)
SIP config reloaded. Verify with: vinit sip

Call Monitoring

vinit calls -- Show active calls with full details.

Displays the total call count, then runs core show channels verbose for detailed channel information including caller ID, connected line, duration, and application.

$ vinit calls
Active calls: 12

Channel              Location       State   Application(Data)
SIP/protech-00001a   s@from-trunk   Up      Dial(SIP/1001,30,trM)
SIP/1001-00001b      1001@agents    Up      MeetMe(8600101)
...
12 active channels

vinit calls count -- Show only the call count.

A quick one-liner for dashboards, scripts, or Prometheus exporters. Returns just the number.

$ vinit calls count
Active calls: 12

vinit channels -- Show active channels with codec and duration details.

Runs core show channels. Similar to vinit calls but with a slightly different output format showing channel technology, context, and duration.

Agent Management

vinit agents -- Show all currently logged-in agents.

Queries the vicidial_live_agents table joined with vicidial_users for human-readable names. Shows status, campaign, call count, and last call time.

$ vinit agents
=== Logged-In Agents ===

+------+--------------+-------+-------------+-------------+---------------------+
| user | full_name    | status| campaign_id | calls_today | last_call_time      |
+------+--------------+-------+-------------+-------------+---------------------+
| 1001 | John Smith   | INCALL| SALES       |          14 | 2026-03-12 10:23:45 |
| 1002 | Jane Doe     | READY | SALES       |          11 | 2026-03-12 10:21:30 |
| 1003 | Bob Wilson   | PAUSED| SUPPORT     |           8 | 2026-03-12 10:15:22 |
+------+--------------+-------+-------------+-------------+---------------------+

Total: 3 agents logged in

vinit agents <user> -- Show detailed information for a specific agent.

Displays every field from vicidial_live_agents for the given user: current channel, unique ID, lead ID, pause code, closer campaigns, and more. If the agent is not logged in, falls back to showing their vicidial_users record.

$ vinit agents 1001
=== Agent Details: 1001 ===

+------+--------------+--------+-----------+-------+----------+
| user | full_name    | status | server_ip | calls | campaign |
+------+--------------+--------+-----------+-------+----------+
| 1001 | John Smith   | INCALL | 10.0.0.1  |    14 | SALES    |
+------+--------------+--------+-----------+-------+----------+

Channel:  SIP/1001-00002f
UniqueID: 1741234567.12345
Lead ID:  98765

Log Access

vinit log -- Tail the Asterisk messages log in real time.

Opens a tail -f on /var/log/asterisk/messages. Press Ctrl+C to exit. This is the primary log for SIP registrations, call routing, warnings, and errors.

vinit log full -- Tail the Asterisk full log.

The full log includes verbose output and debug information. If the full log does not exist on your server (not all distributions enable it), the command falls back to the messages log automatically.

vinit log grep <pattern> -- Search logs for a specific pattern.

Runs a case-insensitive search and displays the last 100 matching lines. Useful for finding specific SIP peers, error messages, or call IDs.

$ vinit log grep "INVITE"
[2026-03-12 10:15:33] VERBOSE: -- Got SIP response 200 "OK" back from 10.20.30.40:5060
[2026-03-12 10:15:33] VERBOSE: -- SIP/protech-00001a is making progress passing it to SIP/1001-00001b
...

(Showing last 100 matches from /var/log/asterisk/messages)

Database

vinit db -- Open an interactive MySQL console.

Connects directly to the ViciDial database with the configured credentials. You land in a full MySQL shell where you can run any query. Exit with \q or Ctrl+D.

$ vinit db
Connecting to MySQL (database: asterisk)...
MariaDB [asterisk]>

vinit db query "<sql>" -- Run a single SQL query.

For quick one-off queries without entering the interactive console. The output is formatted as a standard MySQL table.

$ vinit db query "SELECT COUNT(*) AS total_calls FROM vicidial_log WHERE call_date > NOW() - INTERVAL 1 HOUR;"
+-------------+
| total_calls |
+-------------+
|         247 |
+-------------+

Note the SQL statement must be enclosed in quotes. For queries containing quotes themselves, use single quotes inside double quotes or escape them.

Mail Management

vinit mail -- Check mail spool size and queue status.

Asterisk and ViciDial cron jobs generate large volumes of email (error reports, cron output, system notifications). On servers without a properly configured mail relay, these accumulate in /var/mail/root and can consume gigabytes of disk space over months.

$ vinit mail
=== Mail Status ===

Mail spool:
  Size: 3.2G
  Lines: 4521893

Mail queue:
-- 0 Kbytes in 0 Requests.

vinit mail clean -- Truncate the mail spool.

Empties /var/mail/root by truncating it to zero bytes. This is a safe operation -- these are system notification emails, not customer data.

$ vinit mail clean
Current spool size: 3.2G
Truncating /var/mail/root... done.
Freed: 3.2G

SmokePing

vinit smokeping status -- Show SmokePing service status and target count.

$ vinit smokeping status
=== SmokePing Status ===

  smokeping.service - SmokePing Network Monitoring
     Loaded: loaded (/etc/systemd/system/smokeping.service; enabled)
     Active: active (running) since Mon 2026-03-10 08:00:00 CET

Monitoring targets: 15
Web UI: http://YOUR_SERVER_IP/smokeping/

vinit smokeping start and vinit smokeping stop -- Start or stop the SmokePing service via systemd.

System Overview

vinit status -- Quick system health check.

A single command that shows everything you need to know at a glance: hostname, uptime, load, memory, disk, Asterisk status, ViciDial agent count, and mail spool size.

$ vinit status
=== System Overview ===

Hostname:  voip-server-01
Uptime:    up 47 days, 3 hours, 12 minutes
Load:      0.42 0.38 0.35

Memory:
  Mem:   62Gi   12Gi   45Gi   1.2Gi   4.8Gi   48Gi
  Swap:  4.0Gi  0.0Gi  4.0Gi

Disk:
  Root: 45G used of 234G (20%)

Asterisk:
  Status:  RUNNING
  Version: Asterisk 20.18.2
  Calls:   12 active
  Peers:   45 sip peers [Monitored: 38 online, 7 offline]

ViciDial:
  Agents:  14 logged in
  Schema:  1706

Mail spool: 128K

This is the command you run first thing in the morning or when SSH-ing into a server to check on it.

Bash Completion

Tab completion transforms the tool from useful to effortless. With completion enabled, typing vinit s<TAB> expands to show sip, smokeping, and status. Typing vinit sip <TAB> shows reload as a valid option.

The Completion Script

Save this as /etc/bash_completion.d/vinit:

#!/bin/bash
#============================================================================
# Bash completion for vinit - VoIP Server Management CLI
#
# Installation:
#   sudo cp vinit-completion.bash /etc/bash_completion.d/vinit
#   source /etc/bash_completion.d/vinit   (or open a new shell)
#============================================================================

_vinit_completions() {
    local cur prev commands
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    # Top-level commands
    commands="sip calls channels agents log db mail smokeping status help version"

    case "$prev" in
        vinit)
            COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
            return 0
            ;;
        sip)
            # "reload" is a subcommand; any other argument is a peer name
            COMPREPLY=( $(compgen -W "reload" -- "$cur") )
            return 0
            ;;
        calls)
            COMPREPLY=( $(compgen -W "count" -- "$cur") )
            return 0
            ;;
        log)
            COMPREPLY=( $(compgen -W "full grep" -- "$cur") )
            return 0
            ;;
        db)
            COMPREPLY=( $(compgen -W "query" -- "$cur") )
            return 0
            ;;
        mail)
            COMPREPLY=( $(compgen -W "clean" -- "$cur") )
            return 0
            ;;
        smokeping)
            COMPREPLY=( $(compgen -W "status start stop" -- "$cur") )
            return 0
            ;;
    esac

    return 0
}

complete -F _vinit_completions vinit

Installation

# Copy the completion script
sudo cp vinit-completion.bash /etc/bash_completion.d/vinit

# Load it in the current shell
source /etc/bash_completion.d/vinit

# Verify: type "vinit " and press TAB
vinit <TAB>
# Output: agents  calls  channels  db  help  log  mail  sip  smokeping  status  version

The completion file is loaded automatically for all new shell sessions. No .bashrc modification needed -- /etc/bash_completion.d/ is sourced by the system bash completion framework.

Dynamic Peer Completion (Advanced)

For an advanced setup, you can make vinit sip <TAB> complete with actual SIP peer names from Asterisk:

        sip)
            # Offer "reload" plus actual SIP peer names from Asterisk
            local peers
            peers=$(asterisk -rx "sip show peers" 2>/dev/null \
                    | awk 'NR>1 && !/^[0-9]+ sip peers/' \
                    | awk -F'/' '{print $1}')
            COMPREPLY=( $(compgen -W "reload $peers" -- "$cur") )
            return 0
            ;;

This adds a slight delay on TAB (50-100ms to query Asterisk), but provides real peer names. Whether the tradeoff is worth it depends on how many peers you have and how often you use this subcommand.

Usage Examples

Morning Server Check

# Quick health check on every server
for server in alpha bravo charlie delta; do
    echo "--- $server ---"
    ssh $server "vinit status"
    echo ""
done

Troubleshoot a SIP Trunk

# Is the trunk registered?
vinit sip | grep my_trunk

# Get full details
vinit sip my_trunk

# Check for related log entries
vinit log grep "my_trunk"

# Are calls flowing through it?
vinit calls | grep my_trunk

Find Why an Agent Cannot Log In

# Is the agent currently logged in somewhere else?
vinit agents 1001

# Check the SIP registration for their phone
vinit sip 1001

# Look for errors in the log
vinit log grep "1001"

Quick Call Count for Monitoring

# One-liner for a Prometheus textfile collector
echo "vicidial_active_calls $(vinit calls count | awk '{print $NF}')" \
    > /var/lib/prometheus/node-exporter/calls.prom

Free Disk Space in an Emergency

# Check what is eating disk
vinit status

# If mail spool is large
vinit mail
vinit mail clean

# Verify
vinit status

Run a Report Query Without Leaving the Shell

# Calls per campaign in the last hour
vinit db query "
    SELECT campaign_id, COUNT(*) as calls, AVG(length_in_sec) as avg_duration
    FROM vicidial_log
    WHERE call_date > NOW() - INTERVAL 1 HOUR
    GROUP BY campaign_id
    ORDER BY calls DESC;
"

Adding New Commands

The script's architecture makes adding new commands straightforward. Every command follows the same pattern:

Pattern

Write a function named cmd_yourcommand.
Add a case in the main dispatcher.
Update the help text.
Add tab completion.

Example: Adding a `vinit trunks` Command

This command shows only SIP trunks (filtering out agent phones):

Step 1: Write the function (add above the dispatcher section):

# --- TRUNK STATUS ---

cmd_trunks() {
    header "SIP Trunks"
    # Filter peers: trunks typically have context "trunkinbound" or similar
    ast_cmd "sip show peers" | grep -E "(Name|trunk)" | head -30
    echo ""
    echo "Registrations:"
    ast_cmd "sip show registry"
}

Step 2: Add to the dispatcher:

case "${1:-help}" in
    # ... existing commands ...
    trunks)           cmd_trunks ;;
    # ... rest of dispatcher ...
esac

Step 3: Update the help text:

SIP MANAGEMENT:
  sip                  Show all SIP peer status
  sip <peer>           Show detailed info for a specific SIP peer
  sip reload           Reload SIP configuration (no restart)
  trunks               Show SIP trunk status and registrations    # <-- new

Step 4: Update bash completion:

commands="sip calls channels agents log db mail smokeping status trunks help version"
#                                                          ^^^^^^ added

Example: Adding a `vinit recording <uniqueid>` Command

Play or locate a call recording by its unique ID:

cmd_recording() {
    local uid="${1:-}"
    if [ -z "$uid" ]; then
        echo "Usage: vinit recording <uniqueid>"
        exit 1
    fi

    header "Recording: $uid"
    local rec_path
    rec_path=$(db_value "
        SELECT location
        FROM recording_log
        WHERE vicidial_id = '$uid'
        ORDER BY start_time DESC
        LIMIT 1;
    ")

    if [ -n "$rec_path" ]; then
        echo "File: $rec_path"
        if [ -f "$rec_path" ]; then
            echo "Size: $(du -sh "$rec_path" | cut -f1)"
            echo "Duration: $(soxi -D "$rec_path" 2>/dev/null || echo 'unknown') seconds"
        else
            echo "WARNING: File not found on disk (may be archived)"
        fi
    else
        echo "No recording found for uniqueid: $uid"
    fi
}

Usage Logging & Audit Trail

On a shared server, knowing who ran what and when is valuable. Add logging to the script so every invocation is recorded.

Adding a Log Line

Insert this near the top of the script, after the configuration block:

#============================================================================
# USAGE LOGGING
# Every invocation is logged for audit purposes.
#============================================================================

LOG_FILE="/var/log/vinit.log"

log_usage() {
    local timestamp
    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
    local user
    user=$(whoami)
    echo "$timestamp | $user | vinit $*" >> "$LOG_FILE" 2>/dev/null
}

# Log this invocation
log_usage "$@"

Log Output

2026-03-12 10:15:33 | root | vinit sip
2026-03-12 10:15:45 | root | vinit agents
2026-03-12 10:16:02 | admin | vinit db query "SELECT COUNT(*) FROM vicidial_log;"
2026-03-12 10:20:11 | root | vinit mail clean

Logrotate Configuration

Create /etc/logrotate.d/vinit:

/var/log/vinit.log {
    weekly
    rotate 12
    compress
    delaycompress
    missingok
    notifempty
    create 644 root root
}

This keeps 12 weeks of history (3 months) with compression, which is more than enough for audit purposes.

Team Standardization

When multiple admins manage the same servers, the tool becomes a shared language. Here is how to maximize that benefit.

Version Control the Script

Store vinit in a Git repository. Every change is reviewed, tested, and deployed consistently.

mkdir -p /opt/vinit && cd /opt/vinit
git init
cp /usr/local/bin/vinit .
cp /etc/bash_completion.d/vinit vinit-completion.bash
git add -A && git commit -m "Initial vinit script"

Per-Server Configuration

Instead of editing the script on each server, source a local configuration file:

# Add near the top of the vinit script, after the defaults:

CONFIG_FILE="/etc/vinit.conf"
if [ -f "$CONFIG_FILE" ]; then
    # shellcheck source=/dev/null
    source "$CONFIG_FILE"
fi

Then on each server, create /etc/vinit.conf:

# /etc/vinit.conf - Server-specific configuration
DB_USER="vinit_ro"
DB_PASS="this_servers_password"
SERVER_IP="10.0.0.1"
AST_LOG="/var/log/asterisk/messages"

Now the script itself is identical across all servers and can be deployed with a simple scp without worrying about overwriting credentials.

Standard Operating Procedures

Document which vinit commands correspond to each operational procedure:

Situation	Commands to Run
Server health check	`vinit status`
SIP trunk down	`vinit sip`, `vinit sip <trunk>`, `vinit log grep <trunk>`
Agent cannot log in	`vinit agents <user>`, `vinit sip <phone>`, `vinit log grep <user>`
High disk usage	`vinit status`, `vinit mail`, `vinit mail clean`
After config change	`vinit sip reload`, `vinit sip`
Call quality issue	`vinit calls`, `vinit sip <trunk>`, `vinit log grep WARNING`

Alias Across Servers

If you manage multiple servers via SSH, add aliases in your local ~/.bash_aliases:

# Run vinit on remote servers from your workstation
alias vinit-alpha='ssh alpha vinit'
alias vinit-bravo='ssh bravo vinit'
alias vinit-charlie='ssh charlie vinit'

# Usage: vinit-alpha calls
# Usage: vinit-bravo agents

Adapting for Other PBX Systems

The vinit pattern is not ViciDial-specific. The dispatcher-and-functions architecture works with any PBX that has a CLI and a database.

FreePBX / Asterisk (without ViciDial)

FreePBX uses Asterisk under the hood, so all Asterisk CLI commands work identically. The differences are in the database and configuration management:

# FreePBX uses its own database and fwconsole CLI
DB_NAME="asteriskcdrdb"

cmd_agents() {
    # FreePBX does not have vicidial_live_agents.
    # Show registered extensions instead.
    header "Registered Extensions"
    ast_cmd "sip show peers" | grep -v "^$" | grep -v "^Name"
}

cmd_reload() {
    # FreePBX has its own reload mechanism
    echo "Applying FreePBX configuration..."
    fwconsole reload
}

cmd_modules() {
    # List installed FreePBX modules
    fwconsole ma list
}

FusionPBX / FreeSWITCH

FusionPBX uses FreeSWITCH instead of Asterisk. The CLI commands are completely different, but the wrapper pattern is the same:

# FreeSWITCH uses fs_cli instead of asterisk -rx
ast_cmd() {
    fs_cli -x "$1"
}

cmd_sip() {
    case "${1:-}" in
        "")
            header "SIP Registrations"
            fs_cli -x "sofia status"
            ;;
        *)
            header "SIP Profile: $1"
            fs_cli -x "sofia status profile $1"
            ;;
    esac
}

cmd_calls() {
    case "${1:-}" in
        count)
            fs_cli -x "show calls count"
            ;;
        "")
            header "Active Calls"
            fs_cli -x "show calls"
            ;;
    esac
}

cmd_channels() {
    header "Active Channels"
    fs_cli -x "show channels"
}

FusionPBX also uses PostgreSQL instead of MySQL:

# PostgreSQL query helper
db_query() {
    sudo -u postgres psql -d fusionpbx -c "$1"
}

db_value() {
    sudo -u postgres psql -d fusionpbx -t -A -c "$1"
}

Kamailio / OpenSIPS (SIP Proxy)

For SIP proxies without a media server, the focus shifts to registrations, dialogs, and routing:

cmd_sip() {
    header "Registered Users"
    kamctl ul show
}

cmd_calls() {
    header "Active Dialogs"
    kamctl dialog list
}

cmd_stats() {
    header "Kamailio Statistics"
    kamctl stats
}

The Common Pattern

Regardless of the PBX system, the structure is always the same:

A configuration block at the top with credentials and paths.
Helper functions that abstract CLI and database access.
Command functions that implement each subcommand.
A case dispatcher that routes the first argument to the right function.
A help function that documents everything.
A bash completion script for tab completion.

Change the helpers and command implementations; keep the architecture.

Security Considerations

Credential Storage

The script stores database credentials in plaintext. This is acceptable because:

The script runs as root on the server where the database is local.
The file permissions should restrict access to root only.
The MySQL user has SELECT-only privileges.

Harden the file permissions:

# Only root can read or execute the script
sudo chmod 700 /usr/local/bin/vinit
sudo chown root:root /usr/local/bin/vinit

# If using a separate config file
sudo chmod 600 /etc/vinit.conf
sudo chown root:root /etc/vinit.conf

If you need non-root users to run the tool, use a MySQL option file instead of embedding credentials:

# Create /root/.vinit.cnf
[client]
user=vinit_ro
password=STRONG_PASSWORD_HERE

# Update the helper functions to use the option file
db_query() {
    mysql --defaults-file=/root/.vinit.cnf "$DB_NAME" -e "$1" 2>/dev/null
}

SQL Injection

The vinit agents <user> and vinit db query commands pass user input into SQL queries. In this context (root access on a local server), SQL injection is not a meaningful attack vector -- the user already has full database access. However, if you extend the tool for use by non-root operators:

Use parameterized queries (not possible in raw mysql -e)
Validate input with pattern matching before query construction
Restrict the db query subcommand to specific users

# Input validation example
cmd_agents() {
    local user="$1"
    # Allow only alphanumeric usernames
    if [[ ! "$user" =~ ^[a-zA-Z0-9_]+$ ]]; then
        echo "Invalid username format."
        exit 1
    fi
    # ... query ...
}

Principle of Least Privilege

The MySQL user should have only SELECT privileges. Never use the ViciDial cron user or the MySQL root user in the script. If you add write operations in the future (e.g., a command to pause an agent), create a second MySQL user with narrow INSERT/UPDATE grants on specific tables only.

Production Checklist

Before deploying vinit to a production server, verify each item:

Script

[ ] Credentials are configured (DB_USER, DB_PASS, SERVER_IP)
[ ] MySQL user exists with SELECT-only privileges
[ ] Script is executable: chmod +x /usr/local/bin/vinit
[ ] Script is owned by root: chown root:root /usr/local/bin/vinit
[ ] File permissions are restrictive: chmod 700 /usr/local/bin/vinit
[ ] vinit help displays correctly
[ ] vinit status runs without errors

Functionality

[ ] vinit sip shows SIP peers
[ ] vinit calls shows active calls
[ ] vinit agents queries the database successfully
[ ] vinit log tails the correct log file
[ ] vinit db opens a MySQL console
[ ] vinit mail reports spool size

Completion

[ ] Completion script installed in /etc/bash_completion.d/vinit
[ ] vinit <TAB> lists all commands
[ ] vinit sip <TAB> shows reload

Operations

[ ] Usage logging is enabled (optional)
[ ] Logrotate is configured for /var/log/vinit.log (if logging)
[ ] Configuration file /etc/vinit.conf is used (if multi-server)
[ ] Team members know the tool exists and have run vinit help

Multi-Server

[ ] Script deployed to all servers
[ ] Credentials configured per-server
[ ] Bash completion installed on all servers
[ ] Deploy script (deploy-vinit.sh) is saved for future updates

Summary

vinit is not a framework, a platform, or a product. It is a 200-line Bash script that saves you from typing the same long commands hundreds of times a week. It wraps Asterisk CLI, MySQL queries, log access, and system utilities behind short, memorable subcommands with tab completion.

The value is in the pattern, not the specific commands. Your VoIP environment has its own quirks, its own tables, its own log paths. Fork the script, add your commands, remove what you do not need. The architecture -- configuration block, helper functions, command functions, case dispatcher, help text, bash completion -- stays the same regardless of whether you run ViciDial, FreePBX, FusionPBX, or bare Asterisk.

Start with the commands you type most often. Deploy to one server. Use it for a week. Then deploy to the rest.

Building a Custom CLI Management Tool for VoIP Servers

Building a Custom CLI Management Tool for VoIP Servers

Table of Contents

Introduction

The Problem

The Solution

Why It Works

Architecture Overview

Prerequisites

The Complete Script

Installation

Step 1: Create the Script

Step 2: Configure Credentials

Step 3: Create a Dedicated MySQL User

Step 4: Test

Step 5: Deploy to Multiple Servers

Command Reference

SIP Management

Call Monitoring

Agent Management

Log Access

Database

Mail Management

SmokePing

System Overview

Bash Completion

The Completion Script

Installation

Dynamic Peer Completion (Advanced)

Usage Examples

Morning Server Check

Troubleshoot a SIP Trunk

Find Why an Agent Cannot Log In

Quick Call Count for Monitoring

Free Disk Space in an Emergency

Run a Report Query Without Leaving the Shell

Adding New Commands

Pattern

Example: Adding a vinit trunks Command

Example: Adding a vinit recording <uniqueid> Command

Usage Logging & Audit Trail

Adding a Log Line

Log Output

Logrotate Configuration

Team Standardization

Version Control the Script

Per-Server Configuration

Standard Operating Procedures

Alias Across Servers

Adapting for Other PBX Systems

FreePBX / Asterisk (without ViciDial)

FusionPBX / FreeSWITCH

Kamailio / OpenSIPS (SIP Proxy)

The Common Pattern

Security Considerations

Credential Storage

SQL Injection

Principle of Least Privilege

Production Checklist

Script

Functionality

Completion

Operations

Multi-Server

Summary

Tags

Author

Stats

Published

You Might Also Like

Too cheap to be good? Think again.

The Stale Feature Flag We Deleted That Turned a Feature Back On

Some friends wanted to see how I use DigitalOcean. So I built them the smallest real app I could.

Trust Isn't a Scalar: Typed Provenance for Agent Chains

I Made Claude Code Think Before It Codes. Then I Gave It a Team.

How to Backup and Restore Coolify in 12 Minutes (Before Your Server Dies on a Friday Night)

Example: Adding a `vinit trunks` Command

Example: Adding a `vinit recording <uniqueid>` Command