More doc

en/conf.py

@@ -317,3 +317,5 @@
 googleanalytics_id = "G-1YGEQV43K8"
 
 mermaid_version = "11.4.1"
+
+exclude_patterns = [ 'course/*' ]

en/course/sip.rst

@@ -0,0 +1,290 @@
+============
+Протокол SIP
+============
+
+Sessions Initiation Protocol - один із сигнальних протоколів для управління сесіями у IP мережах. До задач протоколу SIP входять
+
+ - Встановлення сессій
+ - Модифікація параметрів сессії
+ - Розрив сессій
+ - Передача інформації для динамічного пошуку адрес
+
+Не зважаючі на те що у SIP може використовуватися для реалізації різних сервісів у цьому документі ми будемо фокусуватися на задачах телефонії.
+
+Протокол SIP є протоколом application рівня у моделі TCP/IP і може інкапсулюватися у різні транспортні протоколи - UDP, TCP, SCTP. Також може використовуватися TLS, а також Websocket поверх TCP.
+
+.. mermaid::
+
+    block-beta
+        columns 2
+        block:app:2
+            columns 1
+            sip["SIP"]
+        end
+        block:transport:2
+            columns 1
+            T["Transport Layer"]
+        end
+        block:ip:2
+            columns 1
+            IP["IP Layer"]
+        end
+        block:datalink:2
+            columns 1
+            DatalinkLayer["Datalink Layer"]
+        end
+
+SIP - це сигнальний протокол і не розрахований на передачу медіа даних (аудіо/відео) дзвінка. Тому для передачі медіа даних зазвичай використовується інший протокол - RTP(Real-time Transport Protocol), однак SIP використовується для узгодження параметрів роботи протоколу RTP шляхом передачі пейлоаду SDP(session description protocol) у запитах і відповідях SIP.
+
+https://datatracker.ietf.org/doc/html/rfc3264
+
+
+.. mermaid::
+
+    block-beta
+        columns 2
+        block:app:2
+            columns 2
+            sip["SIP"]
+            rtp["RTP"]
+        end
+        block:transport:2
+            columns 1
+            T["Transport Layer"]
+        end
+        block:ip:2
+            columns 1
+            IP["IP Layer"]
+        end
+        block:datalink:2
+            columns 1
+            DatalinkLayer["Datalink Layer"]
+        end
+
+RTP може використовувати різні транспортні протоколи, однак найбільш вживаним і технічно підходящим є UDP. RTP також має безпекові механізми - SRTP(Secure RTP) котрі дозволяють шифрувати дані.
+
+
+https://datatracker.ietf.org/doc/html/rfc3261 - базовий RFC про SIP
+
+https://datatracker.ietf.org/doc/html/rfc3261#section-18 - Транспортні механізми SIP
+
+https://datatracker.ietf.org/doc/html/rfc2327 - Session Description Protocol
+
+https://datatracker.ietf.org/doc/html/rfc3264 - An Offer/Answer Model with the Session Description Protocol (SDP)
+
+
+Мережеві елементи
+=================
+
+User Agent(далі UA) - кінцевий елемент протоколу SIP. User Agent ініціює і завершує діалоги. Це може бути фізичний SIP телефон, програмний SIP softphone а також серверне ПЗ таке як Asterisk, Freeswitch, SEMS, Yate.
+
+.. mermaid::
+
+    graph LR
+        ua1[User Agent 1]
+        ua2[User Agent 2]
+
+        ua1 <-->|SIP Dialog A| ua2
+
+
+SIP Proxy - елемент котрий не ініціює діалогів, але може приймати участь у маршрутизації запитів між User Agents. Приклади реалізацій - Kamailio, OpenSIPS.
+
+.. mermaid::
+
+    graph LR
+        ua1[User Agent 1]
+        ua2[User Agent 2]
+        proxy[SIP Proxy]
+
+        ua1 <-->|SIP Dialog A| proxy
+        proxy <-->|SIP Dialog A| ua2
+
+Для маршрутизації запитів і відповідей SIP Proxy зазвичай модифікує їх так щоб змінити поведінку UA і забезпечити прохождення наступних запитів і відповідей через себе
+
+Back to back User Agent(B2BUA) - компонент котрий містить в собі два пов'язаних UA.
+
+.. mermaid::
+
+    graph LR
+        ua1[User Agent 1]
+        ua2[User Agent 2]
+        proxy[SIP Proxy]
+        subgraph b2bua
+            bua1
+            bua2
+        end
+
+        bua1 <-->|Internal Events| bua2
+
+        ua1 <-->|SIP Dialog A| proxy
+        proxy <-->|SIP Dialog A| bua1
+        bua2 <-->|SIP Dialog B| ua2
+
+Головною особливістю b2bua є те що діалоги на різних його сторонах не пов'язані і є незалежними з точки зору протоколу SIP. Водночас обидва діалоги керуються бізнес логікою b2bua.
+
+Запит і відповідь
+=================
+
+Protocol data unit(PDU) у SIP називається повідомлення. Існує два типи повідомлень - запит і відповідь.
+
+Серіалізація протокола SIP дуже проста для читання людиною - це текстовий протокол. Лінії розділяються **\\r\\n** (0x0d 0x0a), перша лінія містить метод і R-URI у випадку запита або Code і Reason у випадку відповіді. Наступні лінії - це хідери. Після хідерів після можете передаватися опціональний пейлоад, котрий відділений пустою лінією(тобто **\\r\\n\\r\\n** після останнього хідера).
+
+SIP запит містить таку інформацію:
+
+  - Метод - описує тип запиту. Зазвичай метод запиту також описує назву транзакції - наприклад "INVITE транзакція", "BYE транзакція"
+  - Request URI(R-URI) - адресна інформація
+  - Headers
+  - Payload
+
+SIP відповіь містить:
+
+  - Код відповіді і причина
+  - Headers
+  - Payload
+
+
+Таким чином запити і відповіді мають схожий формат.
+
+Приклад запиту:
+
+.. code-block::
+   :emphasize-lines: 1,13-34
+
+    INVITE sip:[email protected]:5060 SIP/2.0
+    Via: SIP/2.0/UDP 5.6.7.8;branch=z9hG4bKZJKZ8a9Q;rport
+    From: "John Doe" <sip:[email protected]>;tag=1-2A5FC317-67D07F3A000CB929-F41E36C0
+    To: <sip:[email protected]:5060>
+    CSeq: 10 INVITE
+    Call-ID: 1-26D889D4-67D07F3A000CB92C-F41E36C0
+    Max-Forwards: 70
+    User-Agent: yeti-switch 1.13.80core142
+    Content-Type: application/sdp
+    Contact: <sip:5.6.7.8;transport=udp>
+    Content-Length: 533
+
+    v=0
+    o=yeti-switch 1347 1348 IN IP4 5.6.7.8
+    s=yeti-switch
+    c=IN IP4 5.6.7.8
+    t=0 0
+    m=audio 16260 RTP/AVP 8 0 96 97 3 98 99 18 101 100 102 2 103
+    c=IN IP4 45.228.211.228
+    a=rtpmap:8 PCMA/8000
+    a=rtpmap:0 PCMU/8000
+    a=rtpmap:96 G726-32/8000
+    a=rtpmap:97 opus/48000/2
+    a=rtpmap:3 GSM/8000
+    a=rtpmap:98 iLBC/8000
+    a=rtpmap:99 G726-16/8000
+    a=rtpmap:18 G729/8000
+    a=rtpmap:101 telephone-event/8000
+    a=rtpmap:100 G726-40/8000
+    a=rtpmap:102 G726-24/8000
+    a=rtpmap:2 G721/8000
+    a=rtpmap:103 L16/8000
+    a=ptime:20
+    a=sendrecv
+
+Приклад відповіді:
+
+.. code-block::
+   :emphasize-lines: 1
+
+    SIP/2.0 480 Temporarily Unavailable
+    CSeq: 10 INVITE
+    Via: SIP/2.0/UDP 5.6.7.8;received=5.6.7.8;branch=z9hG4bKZJKZ8a9Q;rport=5060
+    From: "John Doe" <sip:[email protected]>;tag=1-2A5FC317-67D07F3A000CB929-F41E36C0
+    Call-ID: 1-26D889D4-67D07F3A000CB92C-F41E36C0
+    To: <sip:[email protected]:5060>;tag=151907697425609
+    Content-Length: 0
+
+Відповідь у SIP завжди ассоційована з запитом. На один запит може буде декілька відповідей.
+
+.. warning:: У виключних ситуаціях можливі запити, на котрі не потрібно відповідати - на **ACK** запит не потрібно слати відповідь.
+
+В залежності від Коду відповідь може бути **фінальною**, або не фінальною.
+
+Коди не фінальних відповідей - **1xx**, коди фінальних відповідей: **2xx, 3xx, 4xx, 5xx, 6xx**
+
+
+Транзакція
+==========
+
+Запит і усі відповіді на нього формують транзакцію. У деяких випадках у транзакції може другий додатковий запит - **ACK**, на котрий не відсилається відповідь.
+Також у деяких випадках запит **ACK** відсилається у окремій транзакцій.
+
+Зазвичай транзакція називається згідно методу запита.
+
+Транзакція - це взаємодія User Agents під час якої User Agent Client(UAC) відсилає запит до User Agent Server(UAS), а UAS - відповідає. У межах транзакції може буде як одна так і декілька відповідей на один запит. Остання відповідь називаються **фінальною**
+
+User Agent котрий ініціює транзакцію шляхом відсилки запита називається UAC - User Agent Client у межах цієї транзакції. User Agent котрий оброблює запит і відповідає кліенту називається UAS - User Agent Server. **Ця термінологія дісна у межах однієї транзакції** - інша транзакція у тому самому діалозі може буде ініційована іншою стороною і таким чином UAC і UAS поміняються місцями.
+
+В залежності від методу, транзакції можуть створювати діалог, завершувати діалог, модифікувати діалог. Також існують транзакції котрі не модифікують стан діалогу - вони називаються **Out of Dialog** транзакціями.
+
+Приклад INVITE транзакції:
+
+.. mermaid::
+
+    sequenceDiagram
+        UAC->>UAS: INVITE request
+        UAS->>UAC: 100 Trying response
+        UAS->>UAC: 180 Ringing response
+        UAS->>UAC: 200 OK response
+
+
+Діалог
+======
+
+Сесія у термінах протокола SIP має назву **діалог**. Діалог це сукупність станів **UA** з обох сторін. Для створення, модифікації і завершення діалогу використовуються **транзакції**.
+
+.. mermaid::
+
+    sequenceDiagram
+        DeviceA->>DeviceB: INVITE request
+        DeviceB->>DeviceA: 100 Trying
+        DeviceB->>DeviceA: 180 Ringing
+        DeviceB->>DeviceA: 200 OK
+        DeviceA->>DeviceB: ACK request
+        DeviceB->>DeviceA: BYE request
+        DeviceA->>DeviceB: 200 OK
+
+У цьому прикладі діалог встановлюється і завершується за допомогою трьох транзакцій - INVITE транзакція починає діалог, ACK - підтверджує отримання 200OK відповіді про успішне встановлення сессії, BYE транзакція - завершує діалог.
+
+Усі запити і відповіді що належать одному діалогу мають однакові значення хідера **Call-ID**, і парамерів **from-tag**, **to-tag**.
+Запит і усі відповіді що належать до однієї транзакції мають однакові значення хідерів
+
+
+Важливі хідери і параметри
+==========================
+
+"Важливі хідери" - термін придуманий автором для опису хідерів котрі безпосередньо забезпечують цілісність протокола і використовуються сервером і кліентом для асоціації запитів і відповідей з транзакціями і транзакцій з діалогами
+
+
+Cseq
+    Command Sequence. При відсилці запиту що починає діалог UAC генерує випадкове початкове значення і інкрементує його для наступних запитів. Усі відповіді від UAS повинні мати значення Сseq таке як і запит до якого ці відповіді відносяться.
+
+Via
+    Хідери Via описують шлях запиту. Між UAC і UAS можуть знаходитися також SIP Proxy. При проходженні запита крізь SIP Proxy, адреса проксі буде додана у верхній Via хідер. Сервер відсилає відповідь на адресу з верхнього Via хідера, таким чином забезпечуючи симетричну маршрутизацію відповіді(Через той самий шлях котрим пройшов запит)
+
+Contact
+    Містить адресу UA котрий відсилає запит чи відповідь. Contact дозволяє інформувати віддалену сторону на яку адресу(IP адресу або FQDN) треба надсилати подальщі запити.
+
+
+From tag
+    Параметр tag хідеру From є ідентифікатором діалогу на стороні UAC котрий ініціює діалог
+
+
+To tag
+    Параметр tag хідеру To є ідентифікатором діалогу на стороні серверу
+
+
+Маршрутизація запитів і відповідей
+==================================
+
+На відміну від багатьох інших протоколів SIP не покладається на просту логіку коли запит і відповідь на нього передаються симметрично(коли відповідь відправляється на ту ж саму мережеву адресу або те саме TCP/SCTP з'єднання з котрої прийшов запит). Натомість SIP має внутрішні механізми для опису яким чином повинна відправлятися відповідь, а також механізми для зміни адреси отримувача майбутніх запитів. Ці механізми базуються на використання хідерів **Via**, **Contact**, **Route** і **Record-Route**.
+
+
+Хідери Via використоваються за збережння шляху проходження запиту. Кожен SIP Proxy котрий приймає участь у передачі запиту додає Via хідер зі своєю адресою вище ніж вже існуючі Via.
+
+
+

en/installation/installation-1.13/sems.rst

@@ -195,15 +195,15 @@ Replace <SIGNALLING_IP>, <MEDIA_IP> with correct values for your server :
                 function = writecdr
                 master {
                     host = 127.0.0.1
-                    port = 5433
+                    port = 5432
                     name = cdr
                     user = cdr
                     pass = somepassword
                 }
                 failover_to_slave = false
                 slave {
                     host = 127.0.0.1
-                    port = 5433
+                    port = 5432
                     name = cdr
                     user = cdr
                     pass = somepassword
@@ -286,7 +286,7 @@ Check logs using for possible errors:
 
 .. code-block:: console
 
-    # journalctls -u sems
+    # journalctl -u sems
 
 
 

en/installation/installation-1.13/web.rst

@@ -43,7 +43,7 @@ To configure databases connection parameters create /opt/yeti-web/config/databas
         adapter: postgresql
         encoding: unicode
         database: cdr
-        username: yeti
+        username: cdr
         password: somepassword
         host: 127.0.0.1
         port: 5432

en/web-interface/billing/accounts.rst

@@ -12,11 +12,16 @@ For each call:
 account balance will be **decreased** on call cost if it uses account for **origination** (customer)
 and **increased** if it uses account for **termination** (vendor).
 
-
 .. _account_id:
 
 Id
-    Unique account id.
+    Auto-generated unique account id.
+
+UUID
+    Auto-generated unique account UUID. UUID used as identifier for :ref:`Customer API <customer_api>`
+
+EXTERNAL
+    **external_id** account attribute value. **external_id** stores ID from external system when data provisioned via :ref:`Admin API <admin_api>`
 
 .. _account_name:
 
@@ -41,15 +46,15 @@ Min balance
 Max balance
     If account balance become greater than this limit, then routes, which are belongs to this account, will not be used for calls termination.
 
-.. _account_balance_low_threshold:
+VAT
+    Account VAT value. Affects calculation of customer_price in CDR.
 
-Balance low threshold
-    If account balance become less than this limit, notification will be send by email.
+Destination rate limit
+    Maximum per-minute price
 
-.. _account_balance_high_threshold:
+Max call duration
+    Maximum calls duration originated by account or terminated to account in seconds
 
-Balance high threshold
-    If account balance become greater than this limit, notification will be send by email.
 
 Origination capacity
     Maximum capacity which can be originated for this account.
@@ -73,10 +78,24 @@ Invoice period
 Invoice template
     Template for generation of PDF invoice documents. (Templates can be configured at *Billing->Invoice templates*)
 
-Sent invoices to
+Send invoices to
     Contacts list to send invoices that were generated.
 
+Invoice Ref template
+    Invoice reference generation template. Use **$id** as unique value per account.
+
 Timezone
     Timezone which will be used for invoices generation and statistics for this account.
 
 
+.. _account_balance_low_threshold:
+
+Balance low threshold
+    If account balance become less than this limit, notification will be send by email.
+
+.. _account_balance_high_threshold:
+
+Balance high threshold
+    If account balance become greater than this limit, notification will be send by email.
+
+