195 lines
9.2 KiB
Plaintext
195 lines
9.2 KiB
Plaintext
====== API для администрирования ======
|
||
|
||
Сокет администратора предоставляет интерфейс для запросов информации и настройки [[Yggdrasil:Yggdrasil|Yggdrasil]] во время выполнения. По умолчанию Yggdrasil прослушивает подключения администратора на localhost: 9001 (параметр AdminListen в [[yggdrasil:config_russian|конфигурационном файле]]).
|
||
|
||
===== Утилита для управления =====
|
||
|
||
Утилита yggdrasilctl предоставляет удобный интерфейс CLI для сокета администратора Yggdrasil. Она может подключаться как к локальным, так и к удаленным экземплярам Yggdrasil и принимать те же команды, что описаны ниже. Каждое поле задается в формате field=value.
|
||
|
||
Примеры использования:
|
||
|
||
<code>yggdrasilctl getDHT
|
||
yggdrasilctl getPeers</code>
|
||
|
||
Для получения списка поддерживаемых команд наберите:
|
||
|
||
<code>yggdrasilctl list</code>
|
||
|
||
Чтобы выполнить действие на удаленном узле Yggdrasil, укажите параметр -endpoint:
|
||
|
||
<code>yggdrasilctl -endpoint=tcp://10.0.0.1:9001 getPeers
|
||
yggdrasilctl -endpoint=unix:///var/run/yggdrasil.sock getDHT</code>
|
||
|
||
Чтобы получить ответ в формате JSON вместо "дружественного" вывода, укажите параметр -json:
|
||
|
||
<code>yggdrasilctl -json getPeers</code>
|
||
|
||
===== Сокет администратора =====
|
||
|
||
Сокет администратора Yggdrasil для запросов и ответов использует формат JSON.
|
||
|
||
Запрос должен быть:
|
||
|
||
* корректной строфой JSON
|
||
* должен завершаться символом новой строки (\n)
|
||
|
||
После получения запроса возвращается ответная строфа.
|
||
|
||
==== Запрос ====
|
||
|
||
Структура типичного запроса выглядит следующим образом:
|
||
|
||
<code json>{
|
||
"request": "XXX",
|
||
"arguments": {
|
||
"baz": "qux"
|
||
}
|
||
}</code>
|
||
|
||
Запрос:
|
||
|
||
* //должен// содержать поле "request" (string) - значение содержит команду запроса
|
||
* //может// иметь поле "keepalive" (bool) - значение true или false, указывающее, следует ли поддерживать соединение для дальнейших запросов (если не указано, Yggdrasil закроет соединение администратора после возврата ответа)
|
||
* //должен// содержать другие обязательные поля для конкретного запроса
|
||
* //может// содержать другие необязательные поля для запроса
|
||
|
||
===Пример выполнения запроса с помощью nc через unix-сокет===
|
||
|
||
<code>echo "{\"request\": \"debug_remotegetself\", \"arguments\": {\"key\": \"00000275cb3ab9ee8d285ecaef5a0d82fbd6d19edc5bc33617094232fd047964\"}}" | nc -U /var/run/yggdrasil.sock</code>
|
||
|
||
==== Ответ ====
|
||
|
||
Типичный ответ имеет такую структуру:
|
||
|
||
<code json>{
|
||
"request":
|
||
{
|
||
"request": "XXX",
|
||
"foo": "bar",
|
||
"baz": "qux"
|
||
},
|
||
|
||
"response":
|
||
{
|
||
},
|
||
|
||
"status": "success"
|
||
}</code>
|
||
|
||
Ответ:
|
||
|
||
* //всегда// содержит поле "request" (string), которое содержит тело исходного запроса
|
||
* //всегда// содержит поле "status" (string), которое может сожержать либо "success" (успех), либо "error" (ошибка)
|
||
* //дополнительно// может содержать секцию "response", который содержит данные ответа на запрос
|
||
* //дополнительно// может содержать поле "error" (string), содержащее текст ошибки
|
||
|
||
==== Типы запросов ====
|
||
|
||
Поле "request" содержит команду, предписывающую, какой запрос следует выполнить.
|
||
|
||
=== getDHT ===
|
||
|
||
Не содержит никаких дополнительных полей запроса.
|
||
|
||
Возвращает известные узлы в DHT.
|
||
|
||
* key (string) содержит PublicKey удаленного узла
|
||
* port (int) порт
|
||
* rest (int)
|
||
|
||
=== getPeers ===
|
||
|
||
Не содержит никаких дополнительных полей запроса.
|
||
|
||
Возвращает одну или несколько записей, содержащих информацию об активных одноранговых сеансах. Первая запись обычно относится к текущему узлу.
|
||
|
||
Для каждого IPv6-адреса:
|
||
|
||
* key (string) содержит PublicKey удаленного узла
|
||
* port (uint8) номер локального порта
|
||
* coords ([]int) содержит координаты узла в дереве
|
||
* remote (string) содержит URI удаленного узла
|
||
|
||
|
||
=== addPeer ===
|
||
|
||
Ожидает:
|
||
|
||
* uri (string) адрес добавляемого узла в стандартном формате URI, используемом в файле конфигурации, т. е. ''%%tcp://a.b.c.d:e%%''
|
||
|
||
Добавляет новый узел.
|
||
|
||
Возвращает:
|
||
* Ноль или более успешно добавленных строк URI в секции «added»
|
||
* Ноль или более неудачных URI в секции «not_added»
|
||
|
||
=== removePeer ===
|
||
|
||
Ожидает:
|
||
|
||
* port (uint8) порт удаляемого узла, его можно определить с помощью getPeers
|
||
|
||
Удаляет существующий узел.
|
||
|
||
Возвращает:
|
||
* Ноль или более строк с успешно удаленными портами в секции «removed»
|
||
* Ноль или более неудачных портов в секции «not_removed»
|
||
|
||
=== getSelf ===
|
||
|
||
Не ожидает никаких дополнительных полей запроса.
|
||
|
||
Возвращает одну запись, содержащую информацию о текущем узле Yggdrasil.
|
||
|
||
Для текущего адреса IPv6:
|
||
|
||
* key (string) содержит PublicKey текущего узла
|
||
* build_name (string) содержит имя сборки, если оно доступно (например, yggdrasil, yggdrasil-Development)
|
||
* build_version (string) содержит версию сборки, если она доступна (например, 0.3.0, 0.2.7-0091)
|
||
* coords ([]int) содержит координаты узла в дереве
|
||
* subnet (string) содержит маршрутизируемую подсеть IPv6 для данного хоста
|
||
|
||
=== getSessions ===
|
||
|
||
Не ожидает никаких дополнительных полей запроса.
|
||
|
||
Возвращает ноль или более записей, содержащих информацию об открытых сеансах между текущим узлом Yggdrasil и другими узлами. Открытые сеансы говорят о том, что недавно был обмен траффиком с удаленным узлом.
|
||
|
||
Для каждого IPv6-адреса:
|
||
|
||
* key (string) содержит PublicKey удаленного узла
|
||
|
||
=== getTunTap ===
|
||
|
||
Не ожидает никаких дополнительных полей запроса.
|
||
|
||
Возвращает одну запись, содержащую информацию об адаптере TUN/TAP текущего узла.
|
||
|
||
Для каждого адаптера:
|
||
|
||
* mtu (uint8) содержит MTU локального адаптера TUN/TAP
|
||
|
||
|
||
=== getMulticastInterfaces ===
|
||
|
||
Не ожидает никаких дополнительных полей запроса.
|
||
|
||
Возвращает ноль или более строк, содержащих включенные многоадресные интерфейсы.
|
||
|
||
Если возвращаются ноль строк, то подразумевается, что многоадресный пиринг не разрешен ни на одном интерфейсе.
|
||
|
||
=== getNodeInfo ===
|
||
|
||
Ожидает:
|
||
|
||
* key=строка, содержащая hex-кодированный открытый ключ удаленного узла, в том же формате, что и, например, подробный вывод ответа из getDHT
|
||
|
||
Просит удаленный узел ответить с его nodeinfo.
|
||
|
||
Возвращает секцию nodeinfo. Данные могут быть в любом формате, могут содержать любые ключи.
|
||
|
||
====== Ссылки ======
|
||
Admin API (EN): https://yggdrasil-network.github.io/admin.html
|
||
|
||
~~DISCUSSION~~
|