Admin API - Uqda Network

// ADMIN SOCKET

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

// CONTROL UTILITY

The uqdactl utility provides a human-friendly CLI interface to the Uqda admin socket. It can connect to both local and remote Uqda instances.

Examples include:

uqdactl getSelf
uqdactl getPeers
uqdactl addPeer tcp://peer.example.com:12345
uqdactl removePeer tcp://peer.example.com:12345

To get a list of supported commands:

uqdactl list

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

uqdactl -endpoint=tcp://10.0.0.1:9001 getPeers
uqdactl -endpoint=unix:///var/run/uqda.sock getSelf

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

uqdactl -json getPeers

// ADMIN SOCKET PROTOCOL

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

A request must be:

A complete JSON stanza
Followed by a newline \n character

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

// REQUEST FORMAT

The structure of a typical request is as below:

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

A request:

Must have a "request" (string) field - a value containing the verb of the request
Can have a "keepalive" (bool) field - a true or false value stating whether the connection should be kept alive for further requests
Must have any other required fields for the request

// RESPONSE FORMAT

A typical response is structured like this:

{
  "request": { ... },
  "response": { ... },
  "status": "success"
}

A response:

Always has a "request" field, which contains the body of the original request
Always has a "status" field, which is either "success" or "error"
Optionally has a "response" section, which contains the response data from the request
Optionally has an "error" field, which contains error text

// COMMON COMMANDS

getSelf

Returns information about the current Uqda node, including IPv6 address, public key, and subnet.

getPeers

Returns information about active peer sessions. The first record typically refers to the current node.

addPeer

Adds a new peer connection. Requires a URI parameter (e.g., tcp://peer.example.com:12345).

removePeer

Removes a peer connection. Requires a URI parameter matching the peer to remove.

// NEXT STEPS

CONFIGURATION

Learn about configuration files

IMPLEMENTATION

Learn how Uqda works

UQDA NETWORK