Глава 2. Быстрый старт¶

2.1. Первая политика¶

Файл политики CPL состоит из двух основных частей: определений (define) и правил внутри слоёв. Простейшая политика может содержать всего один слой с одним правилом:

<Proxy>
    allow

Эта политика разрешает весь трафик. Более практичный пример — запрет доступа к определённым категориям сайтов:

; Определяем список запрещённых категорий
define category blocked_cats
    News
    "Entertainment and Videos"
    Gambling
end

; Основные правила фильтрации
<Proxy>
    category=blocked_cats deny
    allow

Правила обрабатываются сверху вниз. Первое совпавшее правило определяет результат. В этом примере запросы к сайтам из категорий News, Entertainment and Videos или Gambling будут заблокированы. Все остальные запросы — разрешены.

Пример с несколькими слоями:

; Определения
define subnet corporate_net
    10.0.0.0/8
    172.16.0.0/12
end

define condition work_hours
    weekday=(1,2,3,4,5) hour=9..18
end

; Блокировка нежелательных категорий только в рабочее время
<Proxy>
    client.address=!corporate_net deny
    condition=work_hours category=(Gambling, "Adult Content") deny
    allow

; SSL-инспекция с исключениями для банков
<SSL-Intercept>
    url.domain=bank.example.com ssl.forward_proxy(no)
    ssl.forward_proxy(yes)

; Маршрутизация через upstream прокси для внешних ресурсов
<Forward>
    url.host.is_private=yes direct
    forward(upstream-proxy.corp:3128)

2.2. Применение политики¶

Политика применяется немедленно и не требует перезапуска прокси-сервера. Существует четыре способа загрузки:

CLI (командная строка)¶

rproxy# show policy config
Policy Status:
  Version: 5
  Rules: 42
  Definitions: 10
  Source: /etc/rproxy/policy.cpl

rproxy# show policy source
; ... текст текущей политики ...

rproxy# policy reload
Reloading policy...
ok
  Version: 6
  Rules: 42
  Load time: 234 ms

Для редактирования файла политики прямо в терминале доступен TUI-редактор:

rproxy# cpl edit /etc/rproxy/policy.cpl

Для установки новой политики из произвольного файла:

rproxy# policy install /tmp/new_policy.cpl
Installing policy from /tmp/new_policy.cpl...
ok
  Version: 7
  Rules: 45
  Load time: 456 ms

REST API¶

Все операции с политикой доступны через REST API. Запросы требуют JWT-аутентификации.

Получить текущую политику:

curl -H "Authorization: Bearer $TOKEN" \
    http://proxy:9443/api/v1/policy/rules

Ответ:

{
    "data": {
        "name": "default",
        "version": "1.0",
        "cpl_source": "<Proxy>\n    allow\n",
        "total_rules": 1
    }
}

Валидация без применения:

curl -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"content": "<Proxy>\n    deny\n"}' \
    http://proxy:9443/api/v1/policy/validate

Ответ:

{
    "data": {
        "valid": true,
        "layers": 1,
        "rules": 1,
        "errors": null
    }
}

Установка новой политики:

curl -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"content": "<Proxy>\n    category=Malware deny\n    allow\n"}' \
    http://proxy:9443/api/v1/policy/install

Ответ:

{
    "data": {
        "version": 6,
        "duration_ms": 234,
        "rules_count": 2,
        "defines_count": 0,
        "changed": true
    }
}

Откат на предыдущую версию:

curl -X POST -H "Authorization: Bearer $TOKEN" \
    http://proxy:9443/api/v1/policy/rollback

Мониторинг через SSE:

curl -H "Authorization: Bearer $TOKEN" \
    "http://proxy:9443/api/v1/stats/stream?filter=policy"

При каждом изменении политики клиент получает событие:

{
    "type": "policy_reloaded",
    "version": 7,
    "rules_count": 45,
    "duration_ms": 123,
    "changed": true
}

Веб-интерфейс (WebGUI)¶

Redcoat предоставляет два редактора политик в веб-интерфейсе:

Текстовый редактор CPL (/configuration/policy/cpl-editor) — полнофункциональный редактор с синтаксической подсветкой, автодополнением и проверкой прямо в тексте. Позволяет редактировать файл политики как текст, валидировать и применять изменения.

Визуальный редактор VPM (/configuration/policy/vpm) — графический конструктор правил. Правила организованы в слои и подслои, каждое правило редактируется через диалог с вкладками Source / Destination / Service / Action. Поддерживает переупорядочивание перетаскиванием.

Библиотека объектов (/configuration/policy/objects) — управление определениями (define-блоками): подсети, списки доменов, условия, действия, категории. Объекты создаются один раз и используются в правилах по имени.

2.3. Проверка и отладка¶

Валидация перед применением¶

Перед применением политики рекомендуется проверить её синтаксис. Валидация проверяет:

Корректность синтаксиса CPL
Правильность имён условий и действий
Существование ссылок на определения (define)
Корректность regex-выражений

CLI:

rproxy# policy validate /tmp/new_policy.cpl
Validating policy file: /tmp/new_policy.cpl
ok - policy is valid
  Rules: 42
  Layers: 8

При наличии ошибок:

rproxy# policy validate /tmp/broken_policy.cpl
Validating policy file: /tmp/broken_policy.cpl
% Validation failed:
  - Line 15: Syntax error in rule definition
  - Line 28: Unknown action 'invalid_action'

REST API:

curl -X POST -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"content": "<Proxy>\n    invalid_condition deny\n"}' \
    http://proxy:9443/api/v1/policy/validate

Парсинг файла CPL¶

Команда cpl parse показывает структуру файла без применения:

rproxy# cpl parse /etc/rproxy/policy.cpl
Policy: default
Version: 1.0
Layers: 3
  <Proxy>: 12 rules
  <SSL-Intercept>: 5 rules
  <Forward>: 3 rules
Defines: 4
  subnet: corporate_net, guest_net
  category: blocked_cats
  condition: work_hours

Статус текущей политики¶

rproxy# policy status
Policy Status:
  Version: 5
  Rules: 42
  Definitions: 10
  Source: /etc/rproxy/policy.cpl
  Age: 2h 15m
  Has Previous: Yes

Поле Has Previous: Yes означает, что доступен откат на предыдущую версию командой policy rollback.

Откат при проблемах¶

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

rproxy# policy rollback
Rolling back to previous policy version...
ok
  Rolled back from version 6 to version 5

Откат выполняется мгновенно — предыдущая версия политики применяется без повторного парсинга.

Версионирование и ротация файлов¶

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

/etc/rproxy/
├── policy.cpl           ← текущая активная политика
└── policy.cpl.prev      ← предыдущая версия (для rollback)

При установке новой политики происходит ротация: 1. policy.cpl → policy.cpl.prev (текущая становится предыдущей) 2. Новое содержимое → policy.cpl (новая становится текущей)

При откате — обратная ротация.

Защита от ошибок¶

Защита	Описание
Валидация перед применением	Политика проверяется на корректность синтаксиса до применения
Таймаут парсера	Парсинг ограничен 30 секундами — защита от некорректного ввода
Автосохранение предыдущей версии	При установке предыдущая версия сохраняется в `policy.cpl.prev`
Мгновенный откат	Предыдущая версия доступна для отката командой `policy rollback`
Применение без перезапуска	Новая политика вступает в силу немедленно, без перезапуска сервиса