howto-db/data/pages/yggdrasil/admin_api.txt

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