Yggdrasil

End-to-end encrypted IPv6 networking to connect worlds

Home
About
Admin API
Blog
Configuration
FAQ
Platforms
Changelog

GitHub
CircleCI
Latest Builds
Public Peers
Public Services

Admin API

The admin socket provides an interface to query and configure Yggdrasil during runtime. By default, Yggdrasil listens for admin connections on localhost:9001.

Control Utility

The yggdrasilctl utility provides a human-friendly CLI interface to the Yggdrasil admin socket. It can connect to both local and remote Yggdrasil instances, and accepts the same verbs as below. Every field is specified in the field=value format.

Examples include:

yggdrasilctl getDHT
yggdrasilctl addPeer uri=tcp://a.b.c.d:e
yggdrasilctl getPeers
yggdrasilctl removePeer port=4
yggdrasilctl setTunTap name=auto mtu=65535 tap_mode=false

To get a list of supported commands:

yggdrasilctl list

To perform an action on a remote Yggdrasil node, specify the -endpoint parameter:

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

To get the JSON response body instead of a “friendly” output, specify the -json parameter:

yggdrasilctl -json getSwitchPeers

To draw a map of a node’s view of the network, install Graphviz onto your system and use dot:

yggdrasilctl dot | dot -Tpng -o map.png

Admin Socket

The Yggdrasil admin socket uses JSON for request and response formats.

A request must be:

Once a valid request is received, the response stanza is returned.

Request

The structure of a typical request is as below:

{
  "request": "XXX",
  "foo": "bar",
  "baz": "qux"
}

A request:

Response

A typical response is structured like this:

{
  "request":
  {
    "request": "XXX",
    "foo": "bar",
    "baz": "qux"
  },

  "response":
  {
  },

  "status": "success"
}

A response:

Request Types

The "request" field contains a verb that describes which request to perform.

getDHT

Expects no additional request fields.

Returns known nodes in the DHT.

getPeers

Expects no additional request fields.

Returns one or more records containing information about active peer sessions. The first record typically refers to the current node.

For each IPv6 address:

addPeer

Expects:

Adds a new peer.

Returns:

removePeer

Expects:

Removes an existing peer.

Returns:

getSwitchPeers

Expects no additional request fields.

Returns zero or more records containing information about switch peers.

For each port number:

getSelf

Expects no additional request fields.

Returns exactly one record containing information about the current Yggdrasil node.

For the current IPv6 address:

getSessions

Expects no additional request fields.

Returns zero or more records containing information about open sessions between the current Yggdrasil node and other nodes. Open sessions indicate that traffic has been exchanged with the remote node recently.

For each IPv6 address:

getTunTap

Expects no additional request fields.

Returns exactly one record containing information about the current node’s TUN/TAP adapter.

For each adapter:

getAllowedEncryptionPublicKeys

Expects no additional request fields.

Returns zero or more strings containing the allowed box public keys.

If zero strings are returned then it is implied that all connections are permitted.

addAllowedEncryptionPublicKey

Expects:

Adds a new allowed box pub key.

Returns:

removeAllowedEncryptionPublicKey

Expects:

Removes an existing box pub key.

Returns:

getMulticastInterfaces

Expects no additional request fields.

Returns zero or more strings containing the enabled multicast peering interfaces.

If zero strings are returned then it is implied that multicast peering is not allowed on any interface.

getRoutes

Expects no additional request fields.

Returns zero or more records where the subnet (string) is mapped to the public key (string).

addRoute

Expects:

Adds a new crypto-key route.

Returns:

removeRoute

Expects:

Removes an existing crypto-key route.

Returns:

getSourceSubnets

Expects no additional request fields.

Returns zero or more records for allowed crypto-key routing source subnets (string).

addSourceSubnet

Expects:

Adds a new crypto-key source subnet.

Returns:

removeSourceSubnet

Expects:

Removes an existing crypto-key source subnet.

Returns:

dhtPing

Expects:

Asks a remote node to respond with information from the DHT.

Returns a nodes section with information about each node included in the DHT lookup response, indexed by IPv6.

For each IPv6 address, this includes:

getNodeInfo

Expects:

Asks a remote node to respond with their nodeinfo.

Returns a nodeinfo section with the nodeinfo. This can be in any format, containing any keys.