Описание

Данный сервис позволяет поддерживать удаленную книгу Yealink, GrandStream, которую возможно получать либо из базы абонентов SSW (по http), либо по протоколу ldap, либо с адресной книги ECSS-10 (используя mysql).
На текущий момент:

• Из базы абонентов ssw можно получить: имя и номер;
• По протоколу ldap можно получить: имя, номер, почту;
• Используя mysql: имя, номер, почту.

Конфигурация сервиса

Настройка сервиса

Заранее нужно определиться из какого источника будет осуществляться получение данных абонентов.

• Если данные будут получены по ldap, необходимо чтобы на момент настройки был доступ к развернутому ldap серверу (сторонний сервер).
• Если абонентские номера будут получены через mysql, то необходимо иметь доступ до сервера mysql, который используется ECSS-10 (по умолчанию при установке пакета ecss-mysql создается специальный пользователь address_book с доступом до таблицы address_book). При этом, если будет использован другой пользователь mysql, необходимо убедиться, что у него есть доступ до базы address_book.
• Если номера абонентов будут получены через ssw, необходимо иметь доступ до http терминала сервера. 

При установке пакета ecss-restfs необходимо указать следующие ответы:

• На вопрос "Необходимо ли настроить телефонную книгу?" ответить положительно ("Да");
• Далее в соответствии с сервисом/сервисами которые будут использоваться для формировании адресной книги заполнить параметры доступа;

$ sudo dpkg-reconfigure ecss-restfs

Проверка сервиса

Для проверки работоспособности сервиса необходимо обратиться к его api:

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги;
• <domain> - домен для пользователей которого запрашиваются номера.

$ curl 'http://<IP>:9990/<service>?host=book&domain=<domain>' -v
<Curl/7.58.0IPPhoneDirectory>
    <Title>Restfs address book</Title>
    <Prompt>Prompt text.</Prompt>
     <DirectoryEntry>
        <Name>User Test</Name>
        <Telephone>100</Telephone>
     </DirectoryEntry>
</Curl/7.58.0IPPhoneDirectory>

Если информация по запрашиваемому номеру существует, должен придти код 200, а в теле ответа должна быть телефонная книга.

Дополнительная настройка сервиса

Параметры сервиса

Сервис можно временно сконфигурировать через файл/usr/lib/ecss/ecss-restfs/conf/address-book/card-settings.json. Изменив параметры в файле необходимо перезагрузить сервис ecss-restfs.

$ sudo systemctl restart ecss-restfs

Однако настройки, выставленные в этом файле будут сброшены после обновления пакета ecss-restfs. Верная схема настройки сервиса через установку или реконфигурирование пакета ecss-restfs.

Шаблоны

Шаблоны находятся по пути /etc/ecss/ecss-restfs/template.

Каждый шаблон должен соответствовать следующему виду: -<tempate_name>.xml

• <tempate_name> - имя шаблона. 

Чтобы телефон мог воспользоваться заданным шаблоном, необходимо, чтобы запрос выглядел следующим образом: 

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw);
• <domain> - домен для пользователей которого запрашиваются номера;
• <tempate_name> - имя шаблона. 
• user_agent - аргумент, который позволяет переопределить используемый шаблон, по умолчанию используется первое слово заголовка http-запроса: user-agent.

$ curl 'http://<IP>:9990/<service>?host=book&domain=<domain>user_agent=<tempate_name>' -v

Если шаблон не обнаружен, то возвращается адресная книга по стандартному шаблону.

Использование сервиса

API сервиса

Запрос адресной книги

http://<IP>:9990/<service>?host=book&<Параметр_1>&<Параметр_2>' -v

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw);
• <Параметр> - дополнительные параметры запроса, порядок не имеет значения:

Параметры

• domain - имя домена для которого забирается адресная книга: str;
• name_len - максимальная длина имени: number > 0;
• skip_no_disp - пропускать записи без имени: true|false;
• translit - использовать транслит: true|false;
• user_agent - имя шаблона для адресной книги: str;
• limit - ограничение на количество записей: number > 0.

Сбросить кеш для сервиса телефонной книги

http://<IP>:9990/update/<service>?host=book' -v

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw).

Запрос по протоколу CardDAV

http://<IP>:9990/book/<service>?host=book&<Параметр_1>&<Параметр_2>' -v

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw);
• <Параметр> - дополнительные параметры запроса, порядок не имеет значения:

Параметры

• domain - имя домена для которого забирается адресная книга: str;
• skip_no_disp - пропускать записи без имени: true|false;
• translit - использовать транслит: true|false;

Пример настройки для телефона Cisco 88XX/79XX

Для настройки удаленной книги cisco нужно в конфигурацию (SEPxxxxxxxxxx.cnf.xml или XMLDefault.xnf.xml) автопровижена добавить следующее:

88хх

<phoneServices>
  ...
  <phoneService type="1" category="0">
    <name>Офис</name>
    <url>http://<IP>:9990/<service>?host=book&user_agent=cisco</url>
    <vendor></vendor>
    <version></version>
  </phoneService>
</phoneServices>

79хх

SIPDefault.cnf: 

directory_url: "http://<IP>:9990/<service>?host=book&user_agent=cisco"; URL for external Directory location

• <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
• <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw).

Формат шаблона телефонной книги в restfs, c названием файла cisco.xml:

<CiscoIPPhoneDirectory>
    <Title>Restfs address book</Title>
    <Prompt>Prompt text.</Prompt>
{% for id, person in ipairs(context) do %}
     <DirectoryEntry>
        <Name>{{person.name}}</Name>
    {% for tag, val in pairs(person.phone) do %}
        <Telephone>{{val}}</Telephone>
    {% end %}
     </DirectoryEntry>
{% end %}
</CiscoIPPhoneDirectory>

После чего в контактах телефона появится записная книга со всеми контактами содержащимися в базе указанного сервиса.

Инструкция по синхронизации телефонной книги SIP-телефонов

Общая информация по автоконфигурированию (Autoprovisioning) SIP-телефонов с помощью XML телефонной книги и конфигурационных файлов.

• Конфигурационные файлы и телефонные книги создаются для каждого телефона в отдельности, каждый производитель имеет собственный формат данных.
• В телефонах необходимо включить функции автонастройки и получения телефонной книги XML. Указываются ссылки на соответствующие директории с XML-файлами на сервере или телефоне.
• Можно настроить получение ссылки на конфигурационные файлы через DHCP. На телефонах необходимо разрешить опции "Allow DHCP Option43", "Option 66" и настроить их на DHCP-сервере. В опции 66 необходимо указать адрес директории с конфигурационными файлами (в данной методике не рассматривается).

Пример настройки телефона snom

1. Исходные данные: имя и телефон (или несколько телефонов), которые добавляются на сервер, чтобы телефоны могли получить данную информацию по сети. Это могут быть конфигурации, но в данной инструкции не рассматриваются.

   Необходимо реализовать схему, которая приведена на рисунке 1.
   Аппаратная часть – сервер (ECSS-10, Softswith), SIP-телефон (snom320) и TFTP-сервер, на котором хранятся телефонные номера. 
   Также базу телефонной книги можно хранить на сервере Softswith.

   

   Рисунок 1 - Схема стенда

   Содержимое телефонной книги

   • Home - 528002;
   • Friend – 534303;
   • Russian President – 8-913-1234567.

2. Телефон snom320 может получать настройки и телефонную книгу по протоколу XCAP (XML Configuration Access Protocol).

   Алгоритм работы: когда пользователь подключает телефон к сети, устройство передает мультиадресный запрос SUBSCRIBE с событием event=ua-profile на адрес 224.0.1.75.
   SSW проверяет, есть ли запрашивающее устройство в базе (по производителю, модели, версии, MAC-адресу).
   Если устройство найдено, то шлет ответ 200, и затем запрос NOTIFY с адресом сервера и путем к файлу конфигурации, рисунок 2.

   

   Рисунок 2 - Алгоритм работы

3. Создание файла телефонной книги.

   У каждого телефона свой формат данных телефонной книги и прочих конфигураций. Для каждого производителя (модели устройства) нужно создать свой файл, который находится на сайте производителя телефона. Например, для телефонов snom 320 XML-файл называется phonebook.xml и имеет следующую структуру (исходя из нашего примера):

   <?xml version="1.0" encoding="utf-8"?> <tbook e="2"> <item context="" type="" fav="false" mod="true" index="0"> <number>528002</number> <number_type>sip</number_type> <first_name>home</first_name> </item> <item context="" type="" fav="false" mod="true" index="1"> <number>534303</number> <number_type>sip</number_type> <first_name>friend</first_name> </item> <item context="active" type="" fav="false" mod="true" index="2"> <number>87771234567</number> <number_type>sip</number_type> <first_name>russian president</first_name> </item> </tbook>

   Сохраняем в XML, размещаем на TFTP-сервере.

4. Настройка на SSW.

   1. Добавляем SIP-телефон в базу ECSS-10 с помощью команды add:

      domain/<DOMAIN>/sip/ua-profile/<TYPE>/add <VENDOR> <MODEL> <VERSION> <MAC>

      где:
      <TYPE> - тип профиля: device, user, local-network;
      <VENDOR> - производитель;
      <MODEL> - модель (опциональный параметр);
      <VERSION> - версия (опциональный параметр);
      <MAC> - MAC-адрес определенного устройства (опциональный параметр).

      Любой параметр, кроме VENDOR, может заменить символ "*". Можно, например, прописать конфигурацию по версиям без указания определенной модели или MAC-адреса и т.п.
      Если введены не все параметры, то значение "*" будет присвоено всем оставшимся параметрам.
      При попытке добавления уже существующего описания будет выдана соответствующая ошибка: "This definitions is exists".

      Пример:

      Определяем MAC-адрес устройства и прописываем его на сервере (ECSS-10):

      domain/test.domain/sip/ua-profile/device/add snom * * 000413316E5C

      
      

   2. Указываются ссылки на соответствующие директории с XML-файлами на сервере (ECSS-10) c помощью команды set:

      domain/<DOMAIN>/sip/ua-profile/<TYPE>/set <VENDOR> <MODEL> <VERSION> <MAC> [--path <PATH>] [--effective-by <EFFECTIVE-BY>]

      где: 
      <TYPE>, <VENDOR>, <MODEL>, <VERSION>, <MAC> - описание приведено выше;
      <PATH> - адрес расположения файла конфигурации или телефонной книги (для SNOM файл должен называться phonebook.xml). Значение по умолчанию: "/TYPE/VENDOR".
      <EFFECTIVE-BY> - тайм-аут применения изменений устройством (0 - применить сразу). Значение по умолчанию 0.

      Пример:

      domain/test.domain/sip/ua-profile/device/set snom * * 000413316E5C --path tftp://192.168.18.16/phonebook.xml

      
      

   3. Для удаления записи используется команда del:

      domain/<DOMAIN>/sip/ua-profile/<TYPE>/del <VENDOR> <MODEL> <VERSION> <MAC> [--force]

      где:

      <TYPE>, <VENDOR>, <MODEL>, <VERSION>, <MAC> - описание приведено выше.
      --force - не спрашивать подтверждение.
      Удаление "*" - это удаление записей со значением параметра "*".
      Если нужно удалить всю группу - параметр не должен быть указан. Например, для удаления всех версий определенной модели ввод команды заканчивается указанием модели.

5. Проверка параметров на сервере (ECSS-10) с помощью команды info.

   Проверка параметров выполняется следующей командой CLI:

   domain/<DOMAIN>/sip/ua-profile/<TYPE>/info <VENDOR> <MODEL> <VERSION> <MAC>

   где:

   <TYPE>, <VENDOR>, <MODEL>, <VERSION>, <MAC> - описание параметров приведено выше. Все параметры опциональны, можно ограничить вывод на любом уровне.

   Пример:

   elena@[ds1@ecss1]:/$ domain/test.domain/sip/ua-profile/device/info Executed on the sip1@ecss1 --------------------------------------------------------------------------------------------------- | Type | Vendor | Model | Version | MAC addr | Path | Effective-By | |------+--------+-------+---------+-------------+----------------------------------+--------------| |device| snom | * | * |000413316e5c |tftp://192.168.18.16/phonebook.xml|0 | --------------------------------------------------------------------------------------------------- [exec at: 31.03.2015 15:23:16, exec time: 145ms, nodes: sip1@ecss1]

   
   

6. Проверка работы.

   Телефонная книга отображается в меню аппарата или в WEB-интерфейсе телефона во вкладке Operation=>Directory, рисунок 3.

   

   Рисунок 3 – Переданная телефонная книга на SIP-телефоне фирмы snom

Пример настройки телефона GRANDSTREAM GXP2000

В данном примере схема не отличается от схемы, приведенной в примере 1, кроме того, что производитель SIP-телефона GRANDSTREAM GXP2000.

Настройка аналогична, но есть некоторые отличия. Аппарат не поддерживает протокол XCAP, но реализована возможность синхронизации телефонной книги XML напрямую c TFTP/HTTP-сервера.

Пример:

• RUSSIAN Home - 528002;
• UKRAINE Friend – 534303.

1. Создание телефонной книги.

   Для Grandstream файл называется gs_phonebook.xml. 
   Формат данных XML-файла имеет следующую структуру:

   <?xml version="1.0" encoding="UTF-8"?> <AddressBook> <Contact> <LastName>RUSSIAN</LastName> <FirstName>Home</FirstName> <Phone> <phonenumber>528002</phonenumber> <accountindex>0</accountindex> </Phone> </Contact> <Contact> <LastName>UKRAINE</LastName> <FirstName>Friend</FirstName> <Phone> <phonenumber>534303</phonenumber> <accountindex>1</accountindex> </Phone> </Contact> </AddressBook>

   Сохраняем в XML, размещаем его на TFTP-сервере.

2. Включение и настройка функции получения телефонной книги.

   В телефоне необходимо включить и настроить функции получения телефонной книги.
   Для телефона GRANDSTREAM нужно зайти во вкладку ADVANCED SETTINGS=> Phonebook XML Download:, рисунок 4.

   

   Рисунок 4 – Настройка функции получения телефонной книги на телефоне GRANDSTREAM

   В настройках телефона доступно выставить интервал обновления телефонной книги.
   Подключаем телефон к сети, проверяем загрузку телефонной книги, рисунок 5.

   

   Рисунок 5 – Меню загруженной телефонной книги SIP-телефона фирмы GRANDSTREAM

Пример настройки телефонов Yealink (T22P)

Для телефонов Yealink (T22P) есть функция «Удаленная записная книга». При этом XML-файл телефонной книги считывается с HTTP/TFTP-сервера не загружая телефонную книгу на локальную директорию телефона.
Нужно только настроить путь к серверу и подготовить XML-файл, разместив этот файл на сервере.

Структура XML-файла телефонной книги (по примеру 1):

<xxxIPPhoneDirectory>
    <DirectoryEntry>
        <Name>Home</Name>
        <Telephone>528002</Telephone>
    </DirectoryEntry>
        <DirectoryEntry>
        <Name>Friend</Name>
        <Telephone>534303</Telephone>
    </DirectoryEntry>
        <DirectoryEntry>
        <Name>Russian PRESIDENT</Name>
        <Telephone>891912345678</Telephone>
    </DirectoryEntry>
    <SoftKeyItem>
        <Name>0</Name>
        <URL> tftp://192.168.18.16/1.xml </URL>
    </SoftKeyItem>
</xxxIPPhoneDirectory>

Настройка удаленной телефонной книги на телефоне Yealink приведена на рисунке 6.

Рисунок 6 – Настройка удаленной телефонной книги на телефоне Yealink

Можно выставить интервал обновления телефонной книги, а также входящий/исходящий поиск.

Удаленная телефонная книга будет доступна в меню телефона DIR => Remote Phone Book.
Есть возможность выбирать разные телефонные книги, выбор осуществляется по названию книги, которое задается в колонке (Display Name), рисунок 6.

На рисунке 7 изображено меню переданной телефонной книги SIP-телефона фирмы Yealink.

Рисунок 7 – Меню переданной телефонной книги SIP-телефона фирмы Yealink