Описание

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

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

Установка

При установке restfs у пользователя спрашиваются следующие вопросы:

1. Необходимо ли настроить телефонную книгу?
   1. Да - Далее задаются вопросы по каждому сервису телефонной книги;
   2. Нет - используются параметры по умолчанию для работы с локальными сервисами.
2. Настроить LDAP-книгу?
   1. Да - задаются вопросы по необходимым полям;
   2. Нет - по умолчанию.
3. LDAP_BN - логин в формате LDAP для подключения к серверу с LDAP (например, "cn=admin,dc=eltex,dc=com", если сервер находится по доменному имени eltex.com, а "admin" - это пользователь. Примечание: вводить без ковычек);
4. LDAP_PASS - пароль для пользователя LDAP_BN;
5. LDAP_DOMAIN - домен, в котором находятся записи о пользователях (например, "ou=users,dc=eltex,dc=com", найти всех пользователей в группе users. Вводить без ковычек);
6. LDAP_SERVER - адрес сервера;
7. LDAP_ATTR - запрашиваемые атрибуты (например, чтобы получить телефон, почту и выводимое имя: '"mail", "telephoneNumber", "displayName"'. Вводить без одинарных ковычек, но каждый артибут в ковычках).
8. Настроить SSW-книгу?
   1. Да - задаются вопросы по необходимым полям;
   2. Нет - используются настройки по умолчанию для работы с локальным SSW.
9. SSW_PROTO - протокол передачи (http, https);
10. SSW_SERVER - адрес сервера SSW;
11. SSW_LOGIN - логин;
12. SSW_PASS - пароль;
13. SSW_DOMAIN - домен, из которого необходимо получить контакты;
14. SSW_LIMIT - число контактов, запрашиваемых по умолчанию;
15. Настроить MYSQL-книгу
    1. Да - задаются вопросы по необходимым полям;
    2. Нет - используются параметры по умолчанию для работы с локальной базой данных.
16. MYSQL_SERVER - адрес базы данных;
17. MYSQL_PORT - порт, на котором работает база данных;
18. MYSQL_LOGIN - логин;
19. MYSQL_PASS - пароль;
20. MYSQL_DB - название базы данных;
21. MYSQL_LIMIT - количество контактов, запрашиваемых по умолчаниию.

Настройка

Для того, чтобы настроить необходимый сервис нужно сконфигурировать /etc/ecss/ecss-restfs/card-settings.json. Настройка каждого сервиса находится в соответствующей секции.

SSW

"ssw": {
        "protocol": "%%SSW_PROTO%%", // протокол http или https
        "server": "%%SSW_SERVER%%", // адрес сервера
        "user": "%%SSW_LOGIN%%", // логин
        "password": "%%SSW_PASS%%", // пароль
        "domain": "%%SSW_DOMAIN%%", // домен, из которого необходимо получить данные
        "limit": "%%SSW_LIMIT%%" // максимальное количество контактов, которое нужно получить
}

Необходимо указывать параметры в кавычках!!!

Также возможно изменять данные настройки в запросе, например: http://restfs:9995/ssw?user=admin&password=superpass&domain=example.eltex.local

LDAP

"ldap": {
        "base_name": "%%LDAP_BN%%", // имя в формате ldap для логина
        "password": "%%LDAP_PASS%%", // пароль
        "domain": "%%LDAP_DOMAIN%%", // домен в формате ldap
        "server": "%%LDAP_SERVER%%", // адрес сервера с ldap
        "attrs": ["%%LDAP_ATTR%%"], // запрашиваемые атрибуты (имя, почта, номер)
        "scope": "subtree" // способ обхода при запросе
}

Для уточнения параметров, например, scope, смотрите документацию по ldap, также формат bn, domain в документации по ldap.

Также можно переопределять параметры при запросе
http://restfs:9995/ldap?attrs=mail,displayName&base_name=cn=user,dc=eltex,dc=local

MYSQL

"mysql": {
        "server": "%%MYSQL_SERVER%%", // сервер mysql, где лежит база данных с контактами
        "port": "%%MYSQL_PORT%%", // порт
        "user": "%%MYSQL_LOGIN%%", // пользователь, под которым необходимо войти
        "password": "%%MYSQL_PASS%%", // пароль
        "db": "%%MYSQL_DB%%", // база данных, удовлетворяющая следующей структуре 
        "procedure": "getContactBook",
        "limit": "%%MYSQL_LIMIT%%",
        "offset": "0" // смещение от начала в отсортированной базе данных по contact.id
}

Аналогично можно переопределять в аргументах url необходимые поля.

Шаблоны

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

Каждый шаблон должен соответствовать следующему виду: address-book-<ID>.xml
Где <ID> - по умолчанию служит для определение вендора, например, "address-book-yealink.xml". При создании собственных шаблонов, можно указывать некий идентификатор, который позже будет передан в аргументах запроса.

Допустим, есть следующий файл: /etc/ecss/ecss-restfs/template/address-book-123321.xml
Чтобы телефон мог воспользоваться заданным шаблоном, необходимо, чтобы запрос выглядел следующим образом: http://address:9995/service?user_agent=123321.
user_agent - аргумент, который позволяет переопределить используемый шаблон, по умолчанию используется первое слово заголовка http-запроса: user-agent.

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

Параметры

Выгрузка из ssw|mysql|ldap в форматах template или carddav.

URL

• http://book.restfs.ecss:9990 - получить телефонную книгу, по умолчанию сервис книги берётся из конфигураций.
• http://book.restfs.ecss:9990/book - carddav, сервис по умолчанию берётся из конфигураций.
• http://book.restfs.ecss:9990/book/(ssw|ldap|mysql) - carddav с использованием определенного сервиса.
• http://system.restfs.ecss:9990/(ssw|ldap|mysql)?host=book - получить телефонную книгу из определенного сервиса.

Параметры

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

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

• Для того, чтобы получить книгу, нужно указать следующий url: "http://<ADDRESS>[:<PORT]/<NAME_SERVICE>[?<NAME_ARG>[&NAME_ARG2]...]"
  • <ADDRESS> - адрес restfs;
  • <PORT> - опционально, должен быть 9995;
  • <NAME_SERVICE> - имя сервиса (mysql, ssw, ldap);
  • <NAME_ARG> - аргументы для запроса, соответствует полю из конфига(например, "...?base_name=cn=example,dc=com&attrs=mail,displayName")
• При не настроенном сервисе - код возврата 502

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

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

88хх

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

79хх

SIPDefault.cnf: 

directory_url: "http://10.10.0.56:9995/ssw?user_agent=cisco"; URL for external Directory location

Где:

restfs_address - адрес сервера, где расположен restfs;
service - используемая база (mysql|ssw|ldap).

Формат шаблона телефонной книги в restfs:

<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>

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

Использование ecss-10 в качестве CardDAV сервера

Шаблоны

Шаблоны находятся в /etc/ecss/ecss-restfs/template/address-book 

• common - определяет общий шаблон, который поддерживают Htek, cisco и yealink
• Остальные шаблоны содержат в себе имя агента, который запрашивает данные. Так как возможны пересылки, то лучше указывать данный параметр в url аргументах. Например:  http://restfs:9995/ssw?user_agent=cisco

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

Управление

В сервисе реализовано удаление/добавление/обновление пользователей, посредством http-запросов.

• http://restfs:9995/auth/plogin/ppas - общий вид запроса, необходима basic авторизация (Необходимо указать логин и пароль, сконфигурированный при установке. Значение по умолчанию - eltex:eltex)
  • GET - plogin - узнать существует ли такой пользователь: 200 - существует, 404 - нет
  • POST - plogin и ppas - добавить/обновить пользователя plogin и установить ему пароль ppas, 201 - создан, 400 - нет(возможно не указан пароль)
  • DELETE - plogin - удаляемый пользователь - 200 - удалён, иначе ошибка сервера(баг)
  • PUT - создать пользователя с логином и паролем plogin:ppas, если такого не существует, 201 - создан, 400 - нет(возможно не указан пароль или такой пользователь есть)

Для управления кешем реализовано API.

Общий вид запроса имеет вид: http://restfs:9995/update/service

Добавлено api для управления кешем через http://restfs:9995/update/service - требуется аутентификация для выполнения данного действия

Например:

Для сбросить кеш ssw можно с помощью curl:

http://localhost:9995/update/ssw --basic -ussw