HLS-pull

Описание

При данном способе публикации потока контент загружается в кэш сервера раздачи с сервера-источника при первом запросе пользователя и используется при обслуживании последующих запросов. Объекты хранятся в кэше в течение определенного периода времени.

Способ может быть использован, если существует готовый поток следующих протоколов:

• Adobe HDS;
• Apple HLS;
• Microsoft Smooth Streaming (MSS).

При данном способе, трансформация потоков в другой формат не производится.

Инструкция по настройке

Источник данных

Для корректной работы CDN важно правильно настроить источник данных. В дальнейшем сеть CDN будет обращаться к указанному источнику, для кэширования контента:

В качестве источника могут выступать:

• Домен, например: www.example.ru
• IP-адрес, например: 86.86.87.88
  
  

При создании источника данных с S3-доменом будет необходимо указать разрешенный бакет, для этого появится соответсвующее поле.

Вы можете использовать AWS авторизацию при запросе к источникам. Для этого вам необходимо выбрать соответствующую опцию и ввести два ключа: ключ доступа (access key) и секретный ключ (secret key).

Если Вы используете хостинг на таких сервисах как: Wix, Amazon S3, Selectel и т.д., обратите, пожалуйста, особое внимание на следующий раздел "Hostname".

Hostname

У многих виртуальных хостингов (таких как Amazon S3) есть практика обслуживания нескольких сайтов с одного веб-сервера. Чтобы узлы сети CDN могли достучаться до вашего контента, Вам нужно указать корректный Hostname.

Если Вы не знаете свой Hostname или не знаете где его найти, попробуйте воспользоваться этим сервисом. Укажите домен своего сайта и на вкладке "Информация" посмотрите поле "Имя ресурса".

Порядок действий, если Вы не знаете свой Hostname:

1. Зайдите на свой сайт и скопируйте ссылку на любую картинку, кликнув по ней правой кнопкой.
2. Вставьте ссылку в новом окне браузера. Полученный домен и будет являться Источником контента для вашего сайта. Например, если у Вас сайт размещён на Wix, источником контента будет выступать домен static.wixstatic.com
3. Зайдите на ресурс https://check-host.net и укажите домен вашего сайта (не источника контента).
4. На вкладке "Информация" посмотрите на "Имя ресурса" — это и есть ваш Hostname. Например, если у Вас хостинг на Amazon, то Hostname может иметь вид: ec7-54-151-126-156.eu-west-1.compute.amazonaws.com
5. Укажите полученный Hostname в личном кабинете.

Ссылка на HLS-поток

Для загрузки контента с сервера-источника в кэш сервера раздачи необходимо предоставить URL потока.

Введите путь до потока. Доменное имя подставляется автоматически из "Источника данных".

Нажмите на кнопку "СОЗДАТЬ РЕСУРС".

Ресурс создан! Вы перенаправлены на вкладку "Инструкция по настройке + Плеер".

Проверка трансляции

После создания и настройки ресурса мы рекомендуем проверить трансляцию на корректность работы.

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

В дополнительных настройках Вы можете добавить свой SSL-сертификат, настроить CNAME, а также изменить имя ресурса.

По умолчанию, после сохранения настроек, ваш контент будет доступен по HTTPS и будет иметь следующий вид https://example.a.trbcdn.net.

SSL-сертификат

Для начала работы необходимо загрузить ваш сертификат или сгенерировать новый сертификат. Для этого в правом верхнем углу выберите "ДОБАВИТЬ СЕРТИФИКАТ".

Выберите сертификат, который Вы планируете использовать:

Желаемый CNAME

CNAME-запись позволяет присваивать хосту псевдоним. Этот псевдоним обычно связывает с хостом какую-нибудь функцию, либо просто сокращает его имя.

По умолчанию ваш контент будет доступен по example.a.trbcdn.net/images/1.jpg, но Вы можете настроить доступ к своему контенту по адресу cdn.example.ru/images/1.jpg. Для этого нужно создать CNAME-запись по приведенной ниже инструкции. Запись следует создать на тех серверах, на которые делегирован ваш домен.

1. Откройте страницу управления DNS на сайте компании, предоставляющей Вам услуги DNS-хостинга.

2. Создайте CNAME-запись со следующими значениями полей (в разных панелях управления названия полей могут отличаться):

   • Имя (Хост) — "cdn".

     В некоторых панелях управления в качестве имени записи требуется указывать полное имя поддомена, например, cdn.example.ru.

   • Значение — example.a.trbcdn.net..

3. Подождите, пока изменения в DNS вступят в силу. Этот процесс может длиться до 72 часов.

Если при настройке Live-ресурса был указан желаемый CNAME - в вкладке "Инструкция по настройке + Плеер" будет описана настройка CNAME на вашем DNS-сервере и представлена дополнительная CDN-ссылка на плейлист.

Авторизация $

Включение дополнительной авторизации для всего ресурса HLS-pull невозможно.

Вы можете настроить дополнительную авторизацию для определенного пути во вкладке Правила на странице редактирования ресурса.

DVR

Необходимо активировать эту опцию, если Вам нужно использовать функцию навигации по эфиру (DVR).

Перед включением опции с Вами свяжется менеджер.

Запись потока

Активируйте эту функцию, если Вам нужно сохранить запись потока.

Перед включением опции с Вами свяжется менеджер.

Название ресурса

Для изменения названия ресурса введите в поле новое название ресурса и нажмите кнопку "СОХРАНИТЬ".

Правила

Данный раздел предназначен для более тонкой настройки работы CDN-сети. После создания ресурса на странице его редактирования появится вкладка "Правила". В данной вкладке можно редактировать базовое правило (которое распространяется на весь ресурс), либо создавать индивидуальные правила для какого-либо раздела/пути. Правила позволяют управлять заголовками, кэшированием, CORS и авторизацией.

Основное

Укажите путь до директории или к конкретному файлу, к которому нужно применить данное правило.

Заголовки

В этом разделе Вы можете указать специальные заголовки, которые требуется добавить при обращении к источнику данных (вид "to origin"), либо при раздаче контента конечным пользователям (вид "to customer").

Таймауты

В этом разделе Вы можете указать допустимые таймауты при обращении узлов CDN к вашему ориджину. В случае, если фактические значения начнут превышать допустимые — произойдёт переключение на другой источник контента, указанный в разделе Источник данных.

Кэширование

В этом разделе Вы можете указать время кэширования в зависимости от кода ответа (2xx, 3xx, 4xx, 5xx), установить игнорирование заголовков управления кэшированием ("Expires" и "Cache-Control"), а также включить учет query string при кэшировании.

CORS

Описание

В определённых случаях обращение к контенту, размещённому в сети CDN, расценивается браузером как кросс-доменный запрос и блокируется. В первую очередь это касается шрифтов. Проблема решается выставлением заголовков CORS (Cross-Origin Resource Sharing) для кэшируемых объектов.

Вариантов два:

1. Вы сами выставляете заголовки CORS на сервере-источнике и отключаете их проверку в нашей сети.
2. Вы настраиваете проверку CORS через наш личный кабинет.

Настройка через личный кабинет

Механизм проверки CORS, предоставляемый для конфигурации, основывается на работе нашего собственного модуля. Его функциональность базируется на рекомендациях W3C.

Основные принципы работы модуля:

1. При включенном CORS заголовки Access-Control-* от ориджина не учитываются ни при каких условиях и удаляются из ответа.

2. Запрос без заголовка Origin не является кросс-ресурсным и заголовки Access-Control-* клиенту не передаются.

3. Заголовки Access-Control-Request-* не добавляются нашим модулем ни при каких условиях, т.к. это входящие заголовки запроса, формируемые браузером, как и Origin.

4. При наличии заголовка Origin его содержимое проверяется на соответствие с заданным пользователем. В случае отсутствия ограничений заголовок Access-Control-Allow-Origin ответа будет содержать "*", в случае наличия ограничений и попадания Origin в список разрешенных ACAO будет содержать http(s?)://${http_origin}, в любом другом случае ответ заголовков Access-Control-* содержать не будет.

5. Заголовок Access-Control-Expose-Headers добавляется в том случае, если такие заголовки заданы пользователем. По умолчанию мы проставляем разрешение на доступ к Content-Range для работы range-запросов (для плееров на JS).

6. Заголовок Access-Control-Allow-Credentials (ACAC) выставляется в соответствии с заданным пользователем.

7. Заголовки Access-Control-Allow-Methods, Access-Control-Allow-Headers и Access-Control-Max-Age проставляются только в ответе на запрос с методом OPTIONS, который обрабатывается локально и на ориджин не передается.

8. Заголовок Access-Control-Allow-Methods выставляется равным содержимому заголовка Access-Control-Request-Method в случае его наличия и попадания его содержимого в список простых запросов (GET, HEAD, POST), либо в список, заданный пользователем. Если метод не попадает в список разрешенных - ответ заголовков Access-Control-* содержать не будет. В случае отсутствия в запросе Access-Control-Request-Method Access-Control-Allow-Methods не выставляется.

9. Access-Control-Allow-Headers выставляется равным содержимому заголовка Access-Control-Request-Headers в случае его наличия, наличия заголовка запроса Access-Control-Request-Method и попадания всех заголовков в список простых (Accept, Accept-Language, Content-Type, Content-Language) либо в список, заданный пользователем. Если хотя бы один заголовок не попадает в список разрешенных - ответ заголовков Access-Control-* содержать не будет. В случае отсутствия в запросе Access-Control-Request-Method и Access-Control-Request-Headers Access-Control-Allow-Headers не выставляется.

10. Заголовок Access-Control-Max-Age выставляется в соответствии с заданным пользователем, по умолчанию не выставляется.

11. Дополнительные заголовки ответа, определяемые клиентом, добавляются/переопределяются после отработки модуля CORS и, например, Access-Control-Alow-Origin: * в секции заголовков будет добавлен вне зависимости от результатов работы модуля CORS.

Процесс конфигурации модуля

По умолчанию проверка CORS активна. В случае отключения CORS авторизации все preflight запросы будут перенаправляться на ваш ориджин. Заголовки, описанные выше и выставленные на ориджине, не будут затронуты и передадутся конечным пользователям без изменений.

Вы можете внести корректировки в работу модуля, задав следующие параметры:

Разрешенные домены (по умолчанию не проверяется, все домены разрешены)

Значение можно задавать одним из следующих способов:

1. example.com - точное соответствие
2. *.example.com - все поддомены example.com, не включая example.com
3. .example.com - все домены 3го уровня, включая example.com
4. ~a\d+\.example.com - регулярное выражение

Безопасные заголовки запроса

По умолчанию разрешены Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma. Вы можете дополнить этот список своими заголовками.

Заголовки, доступные API верхнего уровня (Expose Headers)

По умолчанию разрешены Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma. Вы можете дополнить этот список своими заголовками.

Безопасные методы

По умолчанию разрешены GET, HEAD, POST. Вы можете дополнить этот список своими методами.

Заголовок Access-Control-Allow-Credentials

Cookies, сессионность, авторизация несовместимы с кеширующими сервисами ввиду логики своей работы. Однако, если у Вас возникает необходимость выставить заголовок Access-Control-Allow-Credentials, Вы можете сделать это.

Время жизни ответа Preflight запроса

Время, в течение которого результат ответа Preflight запроса считается актуальным.

Авторизация $

В этом разделе Вы можете настроить локальную (на основе подписи), либо внешнюю авторизацию для ограничения доступа к вашему контенту.

Локальная авторизация $

Описание логики работы:

Авторизация запросов пользователей выполняется исключительно в сети CDN, внешние ресурсы не используются. Решение о доступе к потоку принимается средствами нашей сети на основе критериев, обозначенных владельцем контента:

1. Секретный ключ. Проверяется, что ссылка сформирована именно владельцем контента.
2. URI запрашиваемого потока. Проверяется, что ссылка была сформирована именно для этого потока.
3. IP-адрес пользователя (опционально). Проверяется, что поток запрошен именно с того IP-адреса, для которого была сформирована ссылка. Вы можете отключить проверку, выбрав опцию "Не учитывать IP адрес".
4. Время окончания действия ссылки (опционально). Вы можете отключить проверку, выбрав опцию "Не ограничивать по времени".

В момент обращения пользователя к защищённому потоку владельцу контента необходимо сформировать специальную ссылку.

Пример ссылки с локальной авторизацией:

http://example.a.trbcdn.net/md5(HucJ8tJFjy97yuox2OycOQ,1704067200)/path/to/stream/playlist.m3u8

Ссылка содержит авторизационный параметр md5(<md5 hash>[,<expires>]) в пути:

• <md5 hash> — хэш MD5 в формате Base64 for URL, сгенерированный на основе секретного ключа, URI запрошенного потока, IP-адреса пользователя (опционально) и времени жизни ссылки (опционально);
• <expires> — время окончания действия ссылки в формате POSIX time (необязательный параметр).

При обращении к контенту с использованием сгенерированной ссылки, CDN вычисляет значение MD5 и сравнивает его с полученным. Если значение MD5 не совпадает, то пользователю возвращается ответ с кодом 403 Forbidden (запрет на воспроизведение).

Если текущее время превышает значение <expires>, то пользователю возвращается ответ с кодом 410 Gone (целевой ресурс больше недоступен).

Алгоритм генерации MD5-хэша (<md5_hash>) для подписи ссылок:

• Формируем строку для подписи <secret_word><path_to_stream><ip><expire_time>. Элементы <ip> и/или <expire_time> не добавляются в строку для подписи, если в настройках локальной авторизации указано Не учитывать IP адрес и/или Не ограничивать по времени.
• Генерируем base64_url через base64_url(md5(<строка для подписи>)).
• Формируем подпись <md5 hash>, выполняя следующие замены в base64_url:
  • символ = заменяем на пустую строку ''
  • символ + заменяем на -
  • символ / заменяем на _
• Формируем ссылку, используя полученную подпись <md5 hash>.

Пример генерации ссылки:

1. Есть следующие входные данные:

   • Секретный ключ: zah5Mey9Quu8Ea1k
   • IP-адрес пользователя: 1.2.3.4
   • URI потока: http://example.a.trbcdn.net/path/to/stream/playlist.m3u8
   • Время окончания действия ссылки: 1704067200

2. Формируем строку для подписи <secret_word><path_to_stream><ip><expire_time>. Допустим, что мы учитываем и IP адрес, и время окончания действия ссылки.

   Тогда строка для подписи выглядит так: zah5Mey9Quu8Ea1k/path/to/stream1.2.3.41704067200

3. Формируем подпись <md5 hash>:

   Пример на PHP:

   $ php -r 'print str_replace("=", "",strtr(base64_encode(md5("zah5Mey9Quu8Ea1k/path/to/stream1.2.3.41704067200", TRUE)), "+/", "-_")) . "\n";'
   HucJ8tJFjy97yuox2OycOQ
   

   
   

   Пример на Python:

   #!/usr/bin/python3
   import base64
   import hashlib
   
   secret_word = 'zah5Mey9Quu8Ea1k'
   path = '/path/to/stream'
   ip_address = '1.2.3.4'
   expiration_timestamp = 1704067200
   
   def generate_local_signature(secret_word, path, ip_address=None, timestamp=None):
       string_to_sign = f'{secret_word}{path}'
       if ip_address is not None:
           string_to_sign = f'{string_to_sign}{ip_address}'
       if timestamp is not None:
           string_to_sign = f'{string_to_sign}{timestamp}'
   
       hashed_string = hashlib.md5(string_to_sign.encode()).digest()
       decoded_base64_string = base64.b64encode(hashed_string).decode()
       local_signature = decoded_base64_string.replace('+', '-').replace('/', '_').replace('=', '')
       return local_signature
   
   print(generate_local_signature(secret_word, path, ip_address, expiration_timestamp))
   # HucJ8tJFjy97yuox2OycOQ
   

   
   

4. Итоговая ссылка:

   http://example.a.trbcdn.net/md5(HucJ8tJFjy97yuox2OycOQ,1704067200)/path/to/stream/playlist.m3u8

Внешняя авторизация $

Внешняя авторизации предназначена для возможности ограничения доступа к потоку с произвольной логикой, описанной в вашем скрипте авторизации.

Решение о доступе к потоку принимается на основе ответа вашего скрипта, ссылку на который Вы указываете в личном кабинете при создании/редактировании ресурса.

Если от скрипта авторизации пришел ответ со статусом 200, то доступ к потоку разрешен. В противном случае - доступ запрещен.

Авторизационному скрипту передаются следующие заголовки:

• Host: содержит имя домена, для которого предназначен запрос;
• X-Request-URI: содержит URI запрашиваемого потока;
• X-Forwarded-For: содержит реальный IP-адрес пользователя, который запрашивает поток;
• X-Remote-Addr: содержит IP-адрес пользователя, который запрашивает поток, или прокси-сервера.

Ограничения раздачи $

Описание

В этом разделе Вы можете установить ограничения раздачи контента в зависимости от страны и региона, IP адреса, referer или User-Agent

Процесс конфигурации модуля

1. Активируйте нужный Вам вид ограничения и выберите правило по умолчанию (запрещено или разрешено).
2. Добавьте исключения из правила по умолчанию. Для гео ограничений также выберите правило для самого исключения. Таким образом Вы можете, например, запретить трафик для всей страны, при этом разрешить для отдельного региона.
3. При необходимости задайте интервалы времени действия правила. Интервалы не должны пересекаться.
4. Возможно добавить несколько различных правил каждого вида, при условии что их временные интервалы не пересекаются.