Skip to content

IPC ru RU

Jump to bottom
GitHub Action edited this page Jan 18, 2021 · 80 revisions

IPC

ASF включает в себя собственный, уникальный интерфейс IPC который может использоваться для дальнейшего взаимодействия с процессом. IPC это сокращение от "inter-process communication" - Межпроцессное взаимодействие, а проще говоря - это "веб-интерфейс ASF" на базе Kestrel HTTP server, который может использоваться для дальнейшей интеграции с процессом ASF, как в роли интерфейса для пользователя (ASF-ui), так и в роли сервера для сторонних приложений (ASF API).

IPC может использоваться для множества различных вещей, в зависимости от ваших нужд и способностей. Например, вы можете использовать его для получения статуса ASF и всех ботов, отправки команд ASF, получения и изменения конфигурационных файлов, добавления новых ботов, удаления существующих ботов, добавления ключей в BGR или для доступа к журналу ASF. Все эти действия доступны через наше API, а значит вы можете создавать собственные утилиты и скрипты, которые смогут взаимодействовать с ASF и влиять на него в процессе работы. В добавок к этому, часть действий (таких как отправка команд) также реализованы в нашем ASF-ui, который позволяет вам легко получить к ним доступ через дружественный веб-интерфейс.

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

Вы можете активировать наш интерфейс IPC включив параметр глобальной конфигурации IPC. ASF сообщит о запуске IPC в своём журнале, который вы можете проверить чтобы узнать что IPC интерфейс удачно запущен:

INFO|ASF|Start() Запуск IPC сервера...
INFO|ASF|Start() IPC сервер готов!

Http сервер ASF теперь ожидает входящих запросов на нескольких конечных точках. Если вы не создали пользовательский конфигурационный файл для IPC, это будут адрес формата IPv4 127.0.0.1 и адрес формата IPv6 [::1] с портом по умолчанию 1242. Вы можете получить доступ к интерфейсу IPC по ссылкам выше на той же машине, где запущен процесс ASF.

Есть три способа доступа к интерфейсу IPC ASF, вы можете выбрать один из них в зависимости от планируемого использования.

На самом нижнем уровне нахоится ASF API, это ядро нашего интерфейса IPC, и позволяет работать всему остальному. Именно API вам стоит использовать в ваших собственных инструментах, утилитах и проектах для связи с ASF.

Средним уровнем является документация Swagger , которая представляет из себя графический интерфейс для ASF API. Это полная документация ASF API, а также инструмент, позволяющий использовать их более удобно. Вам стоит познакомиться с этим инструментом если вы планируете создать свой инструмент, утилиту или другой проект который должен обмениваться данными с ASF посредством API.

Самый высокий уровень это ASF-ui, который основан на нашем ASF API и предоставляет дружественный к пользователю способ выполнять различные действия в ASF. Это интерфейс IPC используемый по умолчанию для конечных пользователей, и прекрасный пример того что вы можете создать на базе ASF API. Если захотите, вы можете использовать собственный веб-интерфейс для ASF, указав рабочую папку ASF с помощью аргумента командной строки --path с расположенной в нём папкой www.

ASF-ui

ASF-ui это проект сообщества, цель которого создать дружественный к пользователю графический веб-интерфейс для конечных пользователей. Он служит интерфейсом для наших ASF API, позволяющим с лёгкостью выполнять различные действия. Это интерфейс поставляемый с ASF по умолчанию.

Как сказано выше, ASF-ui это проект разрабатываемый нашим сообществом, и поэтому он не поддерживается основными разработчиками ASF. У него свой собственный путь развития в репозитории ASF-ui, и именно туда вам следует адресовать все вопросы, проблемы, сообщения об ошибках и предложения.

ASF-ui

ASF API

Наш ASF API представляет собой веб-API, построенный с учётом REST и основанный на JSON в качестве основного формата данных. Мы стараемся максимально точно описать ответ, используя как коды состояний HTTP (когда это применимо), так и ответ, который вы можете самостоятельно разобрать чтобы выяснить, окончился ли запрос успешно, и если нет - то почему.

Доступ к нашему ASF API может быть получен путём отправки соответствующих запросов на соответствующие конечные точки /Api. Вы можете использовать эти конечные точки API для создания своих вспомогательных скриптов, утилит, интерфейсов и тому подобного. Именно это делает ASF-ui "под капотом", и любая утилита может делать то же самое. ASF API официально поддерживается и обслуживается основной командой ASF.

Полную документацию по всем доступным конечным точкам, описаниям, запросам, ответам, кодам состояния http и всему остальному, что относится к ASF API, вы найдёте в нашей документации Swagger.

ASF API

Аутентификация

Интерфейс IPC ASF по умолчанию не нуждается ни в какой аутентификации, поскольку IPCPassword установлено значение null. Однако, если вы активировали IPCPassword, указав ему не пустое значение, любой запрос к API ASF требует пароль, совпадающий с установленным в IPCPassword. Если вы пропустили аутентификацию или указали неверный пароль, вы получите ошибку 401 - Unauthorized. Если вы продолжите отправлять запросы без аутентификации, со временем вы получите временную блокировку с ошибкой 403 - Forbidden.

Аутентификация может быть выполнена двумя разными способами.

Заголовок Authentication

В основном вам следует использовать заголовки запроса HTTP, установив значение поля Authentication равным вашему паролю. Как этого добиться зависит от того, каким инструментом вы пользуетесь для доступа к интерфейсу IPC ASF, например если вы пользуетесь curl вам следует добавить в качестве аргумента -H 'Authentication: MyPassword'. Таким способом аутентификация передаётся в заголовках запроса, где и должна быть.

Параметр password в строке запроса

В качестве альтернативы вы можете добавить параметр password в конец URL, который хотите вызвать, например вызывая /Api/ASF?password=MyPassword вместо /Api/ASF. Этот подход достаточно хорош, но как видите он раскрывает пароль в открытом виде, что не всегда допустимо. В добавок это дополнительный параметр в строке запроса, что загромождает вид URL, и создаёт впечатление что он применим только к этому URL, хотя на самом деле пароль применяется ко всему обмену с ASF API.

Оба способа поддерживаются, и только вам решать каким из них пользоваться. Мы рекомендуем использовать заголовки HTTP везде где возможно, поскольку с точки зрения использования это более подходящий метод, чем строка запроса. Однако мы также поддерживаем строку запроса, в основном из-за различных ограничений, связанными с заголовками запроса. Хорошим примером этого служит отсутствие пользовательских заголовков при инициализации соединения websocket из javascript (хотя это совершенно корректно с точки зрения RFC). В этой ситуации строка запроса единственный способ аутентификации.

Документация Swagger

Наш интерфейс IPC, в дополнение к ASF API и ASF-ui также включает в себя документацию Swagger, которая доступна по адресу /swagger . Документация Swagger служит посредником между нашей реализацией API и другими инструментами, использующими их (например ASF-ui). Она содержит полную документацию и список всех доступных конечных точек API в спецификации OpenAPI, которая легко может быть использована в других проектах, позволяя вам легко писать и тестировать ASF API.

Помимо использования документации Swagger как полного описания ASF API, вы можете использовать её также как дружественный к пользователю способ вызывать различные конечные точки API, в основном те, которые не реализованы в ASF-ui. Поскольку наша документация Swagger генерируется автоматически из кода ASF, она гарантировано будет актуальной и будет включать в себя все конечные точки API, доступные в вашей версии ASF.

Документация Swagger

ЧАВО

Безопасно ли использовать интерфейс IPC в ASF?

ASF по умолчанию ожидает соединений только по адресам localhost, а значит доступ к IPC ASF невозможен с любой машины, кроме той где запущен ASF. Если вы не изменяли адрес конечных точек, атакующему понадобится доступ к вашей машине чтобы получить доступ к IPC ASF, а значит он настолько безопасен насколько это возможно, и никто не может получить к нему доступ, даже из вашей локальной сети.

Однако, если вы решите изменить установленные по умолчанию адреса привязки localhost на что-то другое, то вам следует установить соответствующие правила брандмауэра самостоятельно, чтобы разрешить только доверенным IP-адресам доступ к интерфейсу ASF. В дополнение к этому, мы настоятельно рекомендуем установить IPCPassword, что добавит ещё один дополнительный уровень безопасности. Возможно вы также захотите в этом случае использовать интерфейс IPC ASF за обратным прокси, что подробно описано ниже.

Могу ли я вызывать ASF API из своих утилит или скриптов?

Да, это именно то, для чего разрабатывался ASF API, вы можете вызывать их из любого инструмента способного отправлять HTTP запросы. Пользовательские скрипты в браузере следуют логике CORS, и поэтому мы разрешаем для них доступ из любых источников (*) при условии что установлен IPCPassword в качестве дополнительной меры безопасности. Это позволяет вам выполнять различные авторизованные запросы ASF API, при этом не позволяя вредоносным скриптам делать это автоматически (поскольку им для этого понадобиться знать ваш IPCPassword).

Могу я получить доступ к IPC ASF удалённо, например с другого компьютера?

Да, мы рекомендуем использовать для этого обратный прокси (подробности ниже). Таким образом вы сможете получить доступ к вашему веб-серверу как обычно, а он в свою очередь получит доступ к IPC ASF на той же машине. В качестве альтернативы, если вы не хотите использовать обратный прокси, вы можете использовать для этого пользовательскую конфигурацию с соответствующим URL. Например, если ваша машина находится в вашем личном VPN с адресом 10.8.0.1, то вы можете установить для ожидания запросов адрес http://10.8.0.1:1242 в конфигурации IPC, что позволит доступ к IPC из вашего личного VPN, но ниоткуда больше.

Можно ли использовать IPC ASF за обратным прокси, таким как Apache или Nginx?

Да, наш IPC полностью совместим с такой конфигурацией, так что вы можете использовать также с другими утилитами для дополнительной безопасности или совместимости, если хотите. В целом, используемый в ASF Kestrel http server достаточно безопасен и не представляет риска при прямом подключении из интернета, но если вы поставите его позади обратного прокси, такого как Apache или Nginx, вы можете получить дополнительный функционал, недоступный в ином случае, такой как например защита интерфейса ASF с помощью Basic authentication.

Пример конфигурации Nginx вы можете найти ниже. We've included full server block, although you're interested mainly in location ones. Дальнейшую информацию вы можете найти в документации nginx.

server {
    listen *:443 ssl;
    server_name asf.mydomain.com;
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/certificate.key;

    location ~* /Api/NLog {
        proxy_pass http://127.0.0.1:1242;

        # Только если вам надо переназначить хост по умолчанию
#       proxy_set_header Host 127.0.0.1;

        # X-headers должны быть указаны для случая, когда nginx на той же машине, что и ASF
        # Они критичны для правильного использования обратного прокси, позволяя ASF, например, банить атакующих а не ваш сервер nginx
        # Их указание позволит ASF правильно определять IP-адреса пользователей, отправлявших запросы - позволяя nginx работать как обратный прокси
        # Если их не указать это приведёт к тому, что ASF будет считать nginx клиентом, и nginx в таком случае будет работать как обычный прокси
        # Если вы не можете запустить службу host на той же машине, что и ASF (например, она в другом контейнере docker), вам нужно закомментировать эти строки
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Real-IP $remote_addr;

        # Мы добавляем эти 3 дополнительный настройки для передачи по websocket, подробнее см. https://nginx.org/ru/docs/http/websocket.html
        proxy_http_version 1.1;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Upgrade $http_upgrade;
    }

    location / {
        proxy_pass http://127.0.0.1:1242;

        # Только если вам надо переназначить хост по умолчанию
#       proxy_set_header Host 127.0.0.1;

        # X-headers должны быть указаны для случая, когда nginx на той же машине, что и ASF
        # Они критичны для правильного использования обратного прокси, позволяя ASF, например, банить атакующих а не ваш сервер nginx
        # Их указание позволит ASF правильно определять IP-адреса пользователей, отправлявших запросы - позволяя nginx работать как обратный прокси
        # Если их не указать это приведёт к тому, что ASF будет считать nginx клиентом, и nginx в таком случае будет работать как обычный прокси
        # Если вы не можете запустить службу host на той же машине, что и ASF (например, она в другом контейнере docker), вам нужно закомментировать эти строки
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Пример конфигурации Apache вы можете найти ниже. Дальнейшую информацию вы можете найти в документации apache.

<IfModule mod_ssl.c>
    <VirtualHost *:443>
        ServerName asf.mydomain.com

        SSLEngine On
        SSLCertificateFile /path/to/your/fullchain.pem
        SSLCertificateKeyFile /path/to/your/privkey.pem

        # TODO: Apache не может производить регистронезависимое сравнение, поэтому мы задали два наиболее используемых формата
        ProxyPass "/api/nlog" "ws://127.0.0.1:1242/api/nlog"
        ProxyPass "/Api/NLog" "ws://127.0.0.1:1242/Api/NLog"

        ProxyPass "/" "http://127.0.0.1:1242/"
    </VirtualHost>
</IfModule>

Могу ли я получить доступ к IPC через протокол HTTPS?

Да, вы можете сделать это двумя разными способами. Рекомендуемый способ это использовать для этого обратный прокси (как описано выше), в этом случае вы можете получить доступ к своему веб-серверу по https как обычно, а затем подключить его к интерфейсу IPC ASF на той же машине. Таким образом ваш трафик полностью зашифрован и вам не нужно вносить никаких изменений в настройки IPC для поддержки такой конфигурации.

Второй способ подразумевает задание пользовательской конфигурации для интерфейса IPC ASF, в которой вы можете активировать конечные точки https и задать соответствующие сертификаты https для использования в Kestrel http server. Этот способ рекомендуется только если у вас нет дргугого веб-сервера и вы не хотите добавлять его только ради ASF. В остальных случаях гораздо проще получить удовлетворительную конфигурацию используя механизм обратного прокси.

Пользовательская конфигурация

Наш интерфейс IPC поддерживает дополнительный файл конфигурации, IPC.config, который следует расположить в стандартной папке config вашего ASF.

При наличии, этот файл задаёт расширенную настройку используемого в ASF Kestrel http server, а также другие, связанные с IPC, настройки. Если у вас нет какой-то конкретной необходимости, вам нет смысла использовать этот файл, поскольку ASF уже использует разумные значения по умолчанию.

Конфигурационный файл основан на следующей структуре JSON:

{
    "Kestrel": {
        "Endpoints": {
            "example-http4": {
                "Url": "http://127.0.0.1:1242"
            },
            "example-http6": {
                "Url": "http://[::1]:1242"
            },
            "example-https4": {
                "Url": "https://127.0.0.1:1242",
                "Certificate": {
                    "Path": "/path/to/certificate.pfx",
                    "Password": "passwordToPfxFileAbove"
                }
            },
            "example-https6": {
                "Url": "https://[::1]:1242",
                "Certificate": {
                    "Path": "/path/to/certificate.pfx",
                    "Password": "passwordToPfxFileAbove"
                }
            }
        },
        "KnownNetworks": [
            "10.0.0.0/8",
            "172.16.0.0/12",
            "192.168.0.0/16"
        ],
        "PathBase": "/"
    }
}

Endpoints - это массив конечных точек, каждая из которых имеет уникальное имя (такое как example-http4) и свойство Url, задающее адрес для ожидания запросов в формате Protocol://Host:Port. По умолчанию, ASF ожидает запросов по адресам http IPv4 и IPv6, но мы добавили примеры настроек для https, которые вы можете при необходимости использовать. Вам следует объявлять только те конечные точки, которые вам нужны, мы включили 4 в пример выше только чтобы вам было удобнее их редактировать.

Host может принимать различные значение, включая значение * которое соединяет http сервер ASF со всеми доступными интерфейсами. Будьте предельно осторожны при использовании значений Host, позволяющих удалённый доступ. Это позволит доступ к интерфейсу IPC ASF с других машин, что может представлять собой угрозу безопасности. Мы настоятельно рекомендуем в данном случае использовать как минимум IPCPassword (и желательно также ваш собственный брандмауэр).

KnownNetworks - Эта переменная задаёт особые сетевые адреса, которые мы считаем доверенными. Этот параметр особенно важен в сочетании с размещением обратного прокси для ASF не на той же машине, что и само ASF - в этом случае вы должны указать IP этой машины здесь, чтобы ASF обрабатывал заголовки прокси и принимал запросы. Указание этой переменной не обязательно, если вы не планируете использовать какой-либо обратный прокси в сочетании с ASF, а также если обратный прокси размещён на той же машине, что и ASF (и поэтому соединяется с IPC ASF используя адрес 127.0.0.1). Будьте предельно осторожны, указывая тут сети, поскольку это позволяет произвести атаку подмены IP адреса в случае, если доверенная машина скомпрометирована или неправильно настроена.

PathBase - Это базовый путь, который будет использоваться интерфейсом IPC. Этот параметр необязательный, по умолчанию имеет значение / и для большинства случаев его изменение не требуется. Изменив этот параметр вы разместите весь интерфейс IPC по заданному префиксу, например по адресу http://localhost:1242/MyPrefix вместо http://localhost:1242. Использование пользовательского PathBase может быть желательным в комбинации с обратным прокси, если вы хотите проксировать только отдельный URL, например mydomain.com/ASF вместо всего домена mydomain.com целиком. Обычно для этого требуется создать правило rewrite для вашего веб-сервера, которое будет перенаправлять mydomain.com/ASF/Api/X -> localhost:1242/Api/X, но вместо этого вы можете задать пользовательский PathBase равным /ASF и получить более простую настройку mydomain.com/ASF/Api/X -> localhost:1242/ASF/Api/X.

Если у вас нет насущной необходимости задать пользовательский базовый путь, лучше оставить ему значение по умолчанию.

Пример конфигурации

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

{
    "Kestrel": {
        "Endpoints": {
            "HTTP": {
                "Url": "http://*:1242"
            }
        }
    }
}

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

en-US de-DE es-ES lol-US
pt-BR ru-RU zh-CN zh-TW

👨‍🏫 Основное

👨‍🎓 Главная

🧙 Дополнительно

👷 Для разработчиков

Clone this wiki locally