Описание

Данный сервис позволяет поддерживать удаленную книгу 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 необходимо указать следующие ответы:

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

Если на момент настройки сервиса пакет ecss-restfs уже был установлен, используйте команду переконфигурирования сервиса:

$ sudo dpkg-reconfigure ecss-restfs
CODE

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

Для проверки работоспособности сервиса необходимо обратиться к его 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>
CODE

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

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

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

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

$ sudo systemctl restart ecss-restfs
CODE

Однако настройки, выставленные в этом файле будут сброшены после обновления пакета 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
CODE

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

В директориях /usr/lib/ecss/ecss-restfs/template/(ssw|carddav) находятся служебные шаблоны. Изменение или удаление этих файлов  может повлечь за собой прекращение работы сервиса.

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

API сервиса

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

http://<IP>:9990/<service>?host=book&<Параметр_1>&<Параметр_2>' -v
CODE
  • <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
CODE
  • <IP> - ip адреса сервера, где установлен пакет ecss-restfs;
  • <service> -  сервис используемый для получения телефонной книги (mysql/yandex/ssw).

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

http://<IP>:9990/book/<service>?host=book&<Параметр_1>&<Параметр_2>' -v
CODE
  • <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>
XML

79хх

SIPDefault.cnf: 

directory_url: "http://<IP>:9990/<service>?host=book&user_agent=cisco"; URL for external Directory location
CODE
  • <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>
XML

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

Инструкция по синхронизации телефонной книги 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

    Сохраняем в 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

В примере не используется XCAP.

В данном примере схема не отличается от схемы, приведенной в примере 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

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

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

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

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

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

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

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

В примере не используется XCAP.

Для телефонов 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>
XML

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

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

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

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

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

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