Сокет администратора предоставляет интерфейс для запросов информации и настройки Yggdrasil во время выполнения. По умолчанию Yggdrasil прослушивает подключения администратора на localhost: 9001 (параметр AdminListen в конфигурационном файле).

Утилита yggdrasilctl предоставляет удобный интерфейс CLI для сокета администратора Yggdrasil. Она может подключаться как к локальным, так и к удаленным экземплярам Yggdrasil и принимать те же команды, что описаны ниже. Каждое поле задается в формате field=value.

Примеры использования:

yggdrasilctl getDHT
yggdrasilctl getPeers

Для получения списка поддерживаемых команд наберите:

yggdrasilctl list

Чтобы выполнить действие на удаленном узле Yggdrasil, укажите параметр -endpoint:

yggdrasilctl -endpoint=tcp://10.0.0.1:9001 getPeers
yggdrasilctl -endpoint=unix:///var/run/yggdrasil.sock getDHT

Чтобы получить ответ в формате JSON вместо «дружественного» вывода, укажите параметр -json:

yggdrasilctl -json getPeers

Сокет администратора Yggdrasil для запросов и ответов использует формат JSON.

Запрос должен быть:

• корректной строфой JSON
• должен завершаться символом новой строки (\n)

После получения запроса возвращается ответная строфа.

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

{
  "request": "XXX",
  "arguments": {
      "baz": "qux"
  }
}

Запрос:

• должен содержать поле «request» (string) - значение содержит команду запроса
• может иметь поле «keepalive» (bool) - значение true или false, указывающее, следует ли поддерживать соединение для дальнейших запросов (если не указано, Yggdrasil закроет соединение администратора после возврата ответа)
• должен содержать другие обязательные поля для конкретного запроса
• может содержать другие необязательные поля для запроса

echo "{\"request\": \"debug_remotegetself\", \"arguments\": {\"key\": \"00000275cb3ab9ee8d285ecaef5a0d82fbd6d19edc5bc33617094232fd047964\"}}" | nc -U /var/run/yggdrasil.sock

Типичный ответ имеет такую структуру:

{
  "request":
  {
    "request": "XXX",
    "foo": "bar",
    "baz": "qux"
  },
 
  "response":
  {
  },
 
  "status": "success"
}

Ответ:

• всегда содержит поле «request» (string), которое содержит тело исходного запроса
• всегда содержит поле «status» (string), которое может сожержать либо «success» (успех), либо «error» (ошибка)
• дополнительно может содержать секцию «response», который содержит данные ответа на запрос
• дополнительно может содержать поле «error» (string), содержащее текст ошибки

Поле «request» содержит команду, предписывающую, какой запрос следует выполнить.

Не содержит никаких дополнительных полей запроса.

Возвращает известные узлы в DHT.

• key (string) содержит PublicKey удаленного узла
• port (int) порт
• rest (int)

Не содержит никаких дополнительных полей запроса.

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

Для каждого IPv6-адреса:

• key (string) содержит PublicKey удаленного узла
• port (uint8) номер локального порта
• coords ([]int) содержит координаты узла в дереве
• remote (string) содержит URI удаленного узла

Ожидает:

• uri (string) адрес добавляемого узла в стандартном формате URI, используемом в файле конфигурации, т. е. tcp://a.b.c.d:e

Добавляет новый узел.

Возвращает:

• Ноль или более успешно добавленных строк URI в секции «added»
• Ноль или более неудачных URI в секции «not_added»

Ожидает:

• port (uint8) порт удаляемого узла, его можно определить с помощью getPeers

Удаляет существующий узел.

Возвращает:

• Ноль или более строк с успешно удаленными портами в секции «removed»
• Ноль или более неудачных портов в секции «not_removed»

Не ожидает никаких дополнительных полей запроса.

Возвращает одну запись, содержащую информацию о текущем узле 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 для данного хоста

Не ожидает никаких дополнительных полей запроса.

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

Для каждого IPv6-адреса:

• key (string) содержит PublicKey удаленного узла

Не ожидает никаких дополнительных полей запроса.

Возвращает одну запись, содержащую информацию об адаптере TUN/TAP текущего узла.

Для каждого адаптера:

• mtu (uint8) содержит MTU локального адаптера TUN/TAP

Не ожидает никаких дополнительных полей запроса.

Возвращает ноль или более строк, содержащих включенные многоадресные интерфейсы.

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

Ожидает:

• key=строка, содержащая hex-кодированный открытый ключ удаленного узла, в том же формате, что и, например, подробный вывод ответа из getDHT

Просит удаленный узел ответить с его nodeinfo.

Возвращает секцию nodeinfo. Данные могут быть в любом формате, могут содержать любые ключи.

Admin API (EN): https://yggdrasil-network.github.io/admin.html