CIPS

Cisco IP Phone System for Issabel / Asterisk

Run Cisco 8841 phones on Issabel/Asterisk without CUCM — with a web admin panel for call recordings and customer management. Built for remote branches behind L2TP/NAT.

English · فارسی

---

CIPS — راه‌اندازی گوشی‌های Cisco 8841 روی Issabel / Asterisk

راهکاری کامل برای راه‌اندازی گوشی‌های Cisco IP Phone 8841 (حالت USECALLMANAGER) روی مرکز تلفن Issabel / Asterisk، بدون نیاز به Cisco CallManager (CUCM) — همراه با پنل مدیریت وب، دفترچه‌ی مشتریان، و دسترسی به تماس‌های ضبط‌شده.

این راهکار مخصوص سناریوی کلاینت‌های راه‌دور پشت L2TP/NAT طراحی و آزمایش شده است.

---

فهرست

• ویژگی‌ها
• معماری
• پیش‌نیازها
• نصب سریع
• افزودن گوشی جدید
• پنل مدیریت وب
• تنظیمات MikroTik (شعبه راه‌دور)
• ساختار مخزن
• عیب‌یابی
• مجوز

---

ویژگی‌ها

• ✅ رجیستر گوشی‌های Cisco 8841 روی chan_sip در حالت USECALLMANAGER
• ✅ کارکرد پایدار از پشت NAT/Tunnel با ترکیب NAT + UDP + فایل‌های امنیتی خالی
• ✅ اسکریپت تک‌دستوری افزودن گوشی (add_phone.sh)
• ✅ سرویس‌های روی گوشی: تاریخچه تماس، دفترچه‌ی داخلی‌ها، دفترچه‌ی مشتریان
• ✅ پنل مدیریت وب با ورود کاربران Issabel:
  • مدیریت تماس‌های ضبط‌شده (پخش، دانلود، فیلتر، نمایش نام مشتری)
  • مدیریت شماره مشتریان (افزودن/ویرایش/حذف)
  • انتخاب مشتری ← نمایش تماس‌های ضبط‌شده‌ی همان شماره
• ✅ پشتیبانی از چند شعبه از طریق TFTP محلی

---

معماری

┌──────────────┐        L2TP / Tunnel        ┌──────────────────┐
│  گوشی‌های     │  ── NAT (MikroTik) ──►      │  سرور Asterisk    │
│  Cisco 8841  │                              │  (Issabel 5)      │
│ 172.10.10.x  │  ◄── SIP/RTP/TFTP ──         │  SERVER_IP    │
└──────────────┘                              └──────────────────┘

سه عامل کلیدی که کارکرد از پشت NAT را ممکن می‌کنند:

1. NAT (masquerade) روی MikroTik برای ترافیک گوشی → سرور
2. ترنسپورت UDP در کانفیگ گوشی (transportLayerProtocol = 2)
3. فایل‌های امنیتی خالی مخصوص هر گوشی (CTLSEP<MAC>.tlv و ITLSEP<MAC>.tlv)

جزئیات کامل فنی و مسیر عیب‌یابی در docs/technical-documentation.html

---

پیش‌نیازها

• Issabel 5 (یا مشابه مبتنی بر Asterisk + FreePBX)
• Asterisk کامپایل‌شده با وصله‌ی cisco-usecallmanager (برای chan_sip)
• گوشی Cisco 8841 با فریمویر SIP (مثلاً sip88xx.11-7-1-17)
• سرویس TFTP فعال روی سرور (/var/lib/tftpboot)
• برای شعبه‌های راه‌دور: روتر MikroTik با دسترسی مدیریتی
• اکستنشن‌های PHP: mysqli, sqlite3, mbstring, session

فهرست کامل پکیج‌ها و لایبرری‌ها: docs/REQUIREMENTS.md

---

نصب سریع

# ۱) کلون کردن مخزن روی سرور Issabel 5
git clone https://github.com/<USER>/cips.git
cd cips

# ۲) اجرای نصاب خودکار — همه‌چیز را نصب و تنظیم می‌کند
sudo bash setup.sh

# ۳) تنها مرحله‌ی باقی‌مانده: ویرایش کانفیگ مرکزی
sudo nano /opt/cips/public/services/config.php

نصاب خودکار (setup.sh) به‌طور خودکار: محیط را بررسی می‌کند، اکستنشن‌های PHP و ابزارها را نصب می‌کند، TFTP را فعال می‌کند، سرویس‌ها و پنل را مستقر می‌کند، Alias های /cips و /manage را می‌سازد، config.php و فایل‌های کمکی TFTP را می‌سازد، و دسترسی‌ها (شامل نوشتن SQLite) را تنظیم می‌کند.

برای نصب دستی گام‌به‌گام (به‌جای نصاب خودکار)، به docs/INSTALL.md مراجعه کنید.

پس از نصب:

• پنل مدیریت: http://<SERVER_IP>/manage
• سرویس‌های گوشی: http://<SERVER_IP>/cips/services/

لوگو: فایل لوگوی خود را با نام logo.png در /opt/cips/public/services/ قرار دهید.

---

افزودن گوشی جدید

گام ۱ — در پنل Issabel: یک داخلی از نوع Generic SIP (chan_sip) بسازید:

• secret = رمز دلخواه
• Transport = all
• NAT Mode = Yes (برای عبور صدا از NAT — مهم!)

گام ۲ — روی سرور، یک دستور:

sudo ./scripts/add_phone.sh <MAC> <EXTEN> <PASSWORD>
# مثال:
sudo ./scripts/add_phone.sh CC:8E:71:49:F6:8B 302 MySecret

این اسکریپت به‌صورت خودکار:

• فایل SEP<MAC>.cnf.xml را با ترنسپورت UDP می‌سازد
• فایل‌های امنیتی خالی CTL/ITL را می‌سازد
• تنظیم usecallmanager را به Asterisk اضافه و sip reload می‌کند

گام ۳ — اگر شعبه TFTP محلی دارد، سه فایل ساخته‌شده را به آن هم منتقل کنید، سپس گوشی را خاموش/روشن کنید.

بررسی وضعیت:

asterisk -rx "sip show peer 302" | grep -iE "Status|Reg. Contact"
# انتظار: Status: OK ...  transport=udp

---

پنل مدیریت وب

آدرس: http://<SERVER_IP>/manage

• ورود: با کاربران Issabel (جدول ampusers با SHA1، و acl.db بخش System/Users با MD5)
• تب تماس‌های ضبط‌شده: جزئیات کامل، پخش درجا، دانلود، فیلتر تاریخ/جستجو، نمایش خودکار نام مشتری به‌جای شماره، و تاریخ شمسی
• تب مدیریت مشتریان: افزودن/ویرایش/حذف، جستجو، و دکمه‌ی مشاهده‌ی تماس‌های هر مشتری

فعال‌سازی ضبط تماس: در پنل Issabel، بخش PBX ← Extensions، گزینه‌های Recording (Inbound/Outbound) را روی Always بگذارید.

---

تنظیمات MikroTik (شعبه راه‌دور)

فایل mikrotik/setup.rsc را مطابق شبکه‌ی خود ویرایش و اجرا کنید.

نکته‌ی کلیدی — DHCP Option 150: آدرس TFTP باید به صورت هگز تنظیم شود. راهنمای تبدیل در mikrotik/ip-to-hex.md:

ip="172.10.12.82"
printf '0x%02X%02X%02X%02X\n' $(echo "$ip" | tr '.' ' ')   # → 0xAC0A0C52

---

ساختار مخزن

cips/
├── README.md
├── LICENSE
├── .gitignore
├── setup.sh                   # ⭐ نصاب خودکار (یک اجرا، همه‌چیز)
├── scripts/
│   ├── add_phone.sh           # افزودن گوشی (تک‌دستوری، UDP + فایل امنیتی)
│   ├── remove_phone.sh        # حذف تمیز گوشی و فایل‌هایش
│   ├── install.sh             # نصب اولیه محیط
│   ├── make_tftp_helpers.sh   # ساخت فایل‌های کمکی TFTP
│   └── backup.sh              # پشتیبان‌گیری از وضعیت سالم
├── web/
│   ├── config.example.php     # کانفیگ مرکزی (نمونه) — کپی به config.php
│   ├── panel/
│   │   └── manage.php         # پنل مدیریت یکپارچه (لاگین + دو تب)
│   └── services/
│       ├── cips_config.php    # لودر کانفیگ مرکزی (مشترک)
│       ├── allcalls.php       # تاریخچه تماس روی گوشی
│       ├── directory.php      # دفترچه داخلی‌ها
│       ├── contacts.php       # دفترچه مشتریان
│       └── contactsmenu.php   # منوی مخاطبین
├── configs/
│   ├── config.example.sh      # تنظیمات مرکزی (نمونه)
│   └── tftp-templates/        # قالب‌های فایل TFTP
├── mikrotik/
│   ├── setup.rsc              # NAT + DHCP option 150
│   └── ip-to-hex.md           # راهنمای تبدیل IP به هگز
└── docs/
    ├── REQUIREMENTS.md                 # پیش‌نیازها و لایبرری‌ها
    ├── INSTALL.md                      # راهنمای نصب گام‌به‌گام
    ├── DEVELOPERS.md                   # راهنمای توسعه و افزودن قابلیت
    ├── technical-documentation.html    # سند فنی کامل
    └── work-report.html                # گزارش کارها

---

عیب‌یابی

مشکل	علت محتمل	راه‌حل
گوشی رجیستر نمی‌شود، در حلقه TFTP گیر می‌کند	نبود فایل امنیتی، یا TFTP از پشت NAT	فایل‌های خالی CTL/ITL بسازید؛ از TFTP محلی استفاده کنید
گوشی رجیستر می‌شود ولی صدا یک‌طرفه است	NAT Mode داخلی روی No است	در پنل، NAT Mode = Yes (force_rport,comedia)
صدا فقط با گوشی راه‌دور مشکل دارد	Symmetric RTP خاموش	همان NAT Mode = Yes
تماس‌های خروجی در History نمی‌آید	src در CDR شماره‌ی بیرونی است	allcalls.php این نسخه از channel هم می‌خواند
ورود به پنل نمی‌شود	کاربر در جدول اشتباه است	ampusers (SHA1) یا acl.db (MD5)
پنل مشتری ذخیره نمی‌کند	دسترسی نوشتن SQLite	دسترسی نوشتن روی فایل و پوشه /var/www/db

---

مشارکت (Contributing)

از مشارکت شما استقبال می‌شود — سرویس گوشی جدید، قابلیت پنل، رفع باگ، مستندات، یا ترجمه.

• راهنمای مشارکت: CONTRIBUTING.md
• معماری و راهنمای توسعه: docs/DEVELOPERS.md

قانون مهم: هیچ رمز، IP یا داده‌ی واقعی مشتری را commit نکنید؛ از placeholder مثل SERVER_IP و CHANGE_ME با یک کامنت کوتاه استفاده کنید.

مجوز

این پروژه تحت مجوز MIT منتشر شده است.