End-to-end encrypted IPv6 networking to connect worlds
Home
About
Admin API
Blog
Configuration
FAQ
Installation
Platform Notes
Changelog
The admin socket provides an interface to query and configure Yggdrasil during runtime. By default, Yggdrasil listens for admin connections on localhost:9001
.
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
The Yggdrasil admin socket uses JSON for request and response formats.
A request must be:
\n
characterOnce a valid request is received, the response stanza is returned.
The structure of a typical request is as below:
{
"request": "XXX",
"foo": "bar",
"baz": "qux"
}
A request:
"request"
(string
) field - a value containing the verb of the request"keepalive"
(bool
) field - a true
or false
value stating whether the connection should be kept alive for further requests (if not specified, Yggdrasil will close the admin connection after returning a response)A typical response is structured like this:
{
"request":
{
"request": "XXX",
"foo": "bar",
"baz": "qux"
},
"response":
{
},
"status": "success"
}
A response:
"request"
(string
) field, which contains the body of the original request"status"
(string
) field, which is either "success"
or "error"
"response"
section, which contains the response data from the request"error"
(string
) field, which contains error textThe "request"
field contains a verb that describes which request to perform.
getDHT
Expects no additional request fields.
Returns known nodes in the DHT.
box_pub_key
(string
) contains the EncryptionPublicKey
of the remote nodecoords
(string
) contains the coordinates of the node on the spanning treelast_seen
(uint32
) contains the number of seconds since the DHT record was last updatedgetPeers
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:
box_pub_key
(string
) contains the EncryptionPublicKey
of the remote nodebytes_sent
(uint64
) contains the number of bytes sent to that peerbytes_recvd
(uint64
) contains the number of bytes received from that peerendpoint
(string
) contains the connected IPv4/IPv6 address and port of the peeringport
(uint8
) contains the local switch port number for that peeruptime
(float64
) contains the number of seconds since the peer connection was establishedaddPeer
Expects:
uri
(string
) for the peer to added, in standard URI format as used in the configuration file, i.e. tcp://a.b.c.d:e
Adds a new peer.
Returns:
string
peer URIs in the "added"
sectionstring
peer URIs in the "not_added"
sectionremovePeer
Expects:
port
(uint8
) for the port of the peer to remove, this can be looked up using getPeers
or getSwitchPorts
Removes an existing peer.
Returns:
string
ports in the "removed"
sectionstring
ports in the "not_removed"
sectiongetSwitchPeers
Expects no additional request fields.
Returns zero or more records containing information about switch peers.
For each port number:
box_pub_key
(string
) contains the EncryptionPublicKey
of the remote nodebytes_sent
(uint64
) contains the number of bytes sent to the remote nodebytes_recvd
(uint64
) contains the number of bytes received from the remote nodecoords
(string
) contains the coordinates of the node on the spanning treeendpoint
(string
) contains the connected IPv4/IPv6 address and port of the peeringip
(string
) contains the IPv6 address of the remote nodegetSelf
Expects no additional request fields.
Returns exactly one record containing information about the current Yggdrasil node.
For the current IPv6 address:
box_pub_key
(string
) contains the EncryptionPublicKey
of the current nodebuild_name
(string
) contains the build name, if available (e.g. yggdrasil
, yggdrasil-develop
)build_version
(string
) contains the build version, if available (e.g. 0.3.0
, 0.2.7-0091
)coords
(string
) contains the coordinates of the node on the spanning treesubnet
(string
) contains the routed IPv6 subnet for this hostgetSessions
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:
box_pub_key
(string
) contains the EncryptionPublicKey
of the remote nodebytes_sent
(uint64
) contains the number of bytes sent across that sessionbytes_recvd
(uint64
) contains the number of bytes received across that sessioncoords
(string
) contains the coordinates of the remote node on the spanning treemtu
(uint8
) contains the negotiated session MTU between the local end and the remote end of the sessionwas_mtu_fixed
(bool
) shows whether or not the MTU has been adjusted since the session was opened to compensate for read errorsgetTunTap
Expects no additional request fields.
Returns exactly one record containing information about the current node’s TUN/TAP adapter.
For each adapter:
tap_mode
(bool
) shows whether or not the interface is in TAP mode (if false
then TUN mode is implied)mtu
(uint8
) contains the MTU of the local TUN/TAP adaptergetAllowedEncryptionPublicKeys
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:
box_pub_key=
string
for the public key to addAdds a new allowed box pub key.
Returns:
string
box pub keys in the "added"
sectionstring
box pub keys in the "not_added"
sectionremoveAllowedEncryptionPublicKey
Expects:
box_pub_key=
string
for the public key to removeRemoves an existing box pub key.
Returns:
string
box pub keys in the "removed"
sectionstring
box pub keys in the "not_removed"
sectiongetMulticastInterfaces
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:
subnet=
string
for the subnet to routebox_pub_key=
string
for the public key to route toAdds a new crypto-key route.
Returns:
string
routes in the "added"
sectionstring
routes in the "not_added"
sectionremoveRoute
Expects:
subnet=
string
for the subnet to remove the route forbox_pub_key=
string
for the public key that is routed toRemoves an existing crypto-key route.
Returns:
string
routes in the "removed"
sectionstring
routes in the "not_removed"
sectiongetSourceSubnets
Expects no additional request fields.
Returns zero or more records for allowed crypto-key routing source subnets (string
).
addSourceSubnet
Expects:
subnet=
string
for the subnet to allow traffic fromAdds a new crypto-key source subnet.
Returns:
string
source subnets in the "added"
sectionstring
source subnets in the "not_added"
sectionremoveSourceSubnet
Expects:
subnet=
string
for the subnet to removeRemoves an existing crypto-key source subnet.
Returns:
string
source subnets in the "removed"
sectionstring
source subnets in the "not_removed"
sectiondhtPing
Expects:
box_pub_key=
string
, hex-encoded public key of the remote node to ping, in the same format as e.g. verbose output from a getDHT
responsecoords=
string
, location of the remote node in the network, in the same format as e.g. a getDHT
responsetarget=
string
, hex-encoded 512-bit NodeID to ask about, affects what the response from the remote node will be, optionalAsks 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:
box_pub_key
(string
) contains the EncryptionPublicKey
of the remote nodecoords
(string
) contains the coordinates of the node on the spanning treegetNodeInfo
Expects:
box_pub_key=
string
, hex-encoded public key of the remote node to ping, in the same format as e.g. verbose output from a getDHT
responsecoords=
string
, location of the remote node in the network, in the same format as e.g. a getDHT
responseAsks a remote node to respond with their nodeinfo.
Returns a nodeinfo
section with the nodeinfo. This can be in any format, containing any keys.