"Fossies" - the Fresh Open Source Software Archive

Member "n2n-3.1.1/doc/ManagementAPI.md" (31 Mar 2022, 8612 Bytes) of package /linux/misc/n2n-3.1.1.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) GitHub Flavored Markdown source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 # Management API
    3 This document is focused on the machine readable API interfaces.
    5 Both the edge and the supernode provide a management interface UDP port.
    6 These interfaces have some documentation on their non machine readable
    7 commands in the respective daemon man pages.
    9 Default Ports:
   10 - UDP/5644 - edge
   11 - UDP/5645 - supernode
   13 A Quick start example query:
   14     `echo r 1 help | nc -w1 -u 5644`
   16 ## JSON Query interface
   18 A machine readable API is available for both the edge and supernode.  It
   19 takes a simple text request and replies with JSON formatted data.
   21 The request is in simple text so that the daemon does not need to include any
   22 complex parser.
   24 The replies are all in JSON so that the data is fully machine readable and
   25 the schema can be updated as needed - the burden is entirely on the client
   26 to handle different replies with different fields.  It is expected that
   27 any client software will be written in higher level programming languages
   28 where this flexibility is easy to provide.
   30 Since the API is over UDP, the replies are structured so that each part of
   31 the reply is clearly tagged as belonging to one request and there is a
   32 clear begin and end marker for the reply.  This is expected to support the
   33 future possibilities of pipelined and overlapping transactions as well as
   34 pub/sub asynchronous event channels.
   36 The replies will also handle some small amount of re-ordering of the
   37 packets, but that is not an specific goal of the protocol.
   39 Note that this API will reply with a relatively large number of UDP packets
   40 and that it is not intended for high frequency or high volume data transfer.
   41 It was written to use a low amount of memory and to support incremental
   42 generation of the reply data.
   44 With a small amount of effort, the API is intended to be human readable,
   45 but this is intended for debugging.
   47 ## Request API
   49 The request is a single UDP packet containing one line of text with at least
   50 three space separated fields.  Any text after the third field is available for
   51 the API method to use for additional parameters
   53 Fields:
   54 - Message Type
   55 - Options
   56 - Method
   57 - Optional Additional Parameters
   59 The maximum length of the entire line of text is 80 octets.
   61 All request packets should generate a reply.  However, this reply may simply
   62 be an error.
   64 ### Message Type
   66 This is a single octet specifying the type:
   68 - "r" for a read-only method (or one that does not need change permissions)
   69 - "w" for a write method (or one that makes changes)
   70 - "s" for a subscribe method to request this socket receive some events
   72 To simplify the interface, the reply from both read and write calls to the
   73 same method is expected to contain the same data.  In the case of a write
   74 call, the reply will contain the new state after making the requested change.
   76 The subscribe and events message flow works with a different set of messages.
   78 ### Options
   80 The options field is a colon separated set of options for this request.  Only
   81 the first subfield (the "tag") is mandatory.  The second subfield is a set
   82 of flags that describe which optional subfields are present.
   83 If there are no additional subfields then the flags can be omitted.
   85 SubFields:
   86 - Message Tag
   87 - Optional Message Flags (defaults to 0)
   88 - Optional Authentication Key
   90 #### Message Tag
   92 Each request provides a tag value.  Any non error reply associated with this
   93 request will include this tag value, allowing all related messages to be
   94 collected within the client.  The tag will be truncated if needed by the
   95 daemon, but there will be at least 8 octets of space available.
   97 Where possible, the error replies will also include this tag, however some
   98 errors occur before the tag is parsed.
  100 The tag is not interpreted by the daemon, it is simply echoed back in all
  101 the replies.  It is expected to be a short string that the client knows
  102 will be unique amongst all recent, still outstanding or subscription requests
  103 on a given socket.
  105 One possible client implementation is a number between 0 and 999, incremented
  106 for each request and wrapping around to zero when it is greater than 999.
  108 #### Message Flags
  110 This subfield is a set of bit flags that are hex-encoded and describe any
  111 remaining optional subfields.
  113 Currently, only one flag is defined.  The presence of that flag indicates
  114 that an authentication key subfield is also present.
  116 Values:
  117 - 0 - No additional subfields are present
  118 - 1 - One additional field, containing the authentication key
  120 #### Authentication Key
  122 A simple string password that is provided by the client to authenticate
  123 this request.  See the Authentication section below for more discussion.
  125 #### Example Options value
  127 e.g:
  128     `102:1:PassWord`
  130 ### Example Request string
  132 e.g:
  133     `r 103:1:PassWord peer`
  135 ## Reply API
  137 Each UDP packet in the reply is a complete and valid JSON dictionary
  138 containing a fragment of information related to the entire reply.
  140 Reply packets are generated both in response to requests and whenever
  141 an event is published to a subscribed channel.
  143 ### Common metadata
  145 There are two keys in each dictionary containing metadata.  First
  146 is the `_tag`, containing the Message Tag from the original request.
  147 Second is the `_type` which identifies the expected contents of this
  148 packet.
  150 ### `_type: error`
  152 If an error condition occurs, a packet with a `error` key describing
  153 the error will be sent.  This usually also indicates that there will
  154 be no more substantial data arriving related to this request.
  156 e.g:
  157     `{"_tag":"107","_type":"error","error":"badauth"}`
  159 ### `_type: begin`
  161 Before the start of any substantial data packets, a `begin` packet is
  162 sent.  For consistency checking, the method in the request is echoed
  163 back in the `error` key.
  165 e.g:
  166     `{"_tag":"108","_type":"begin","cmd":"peer"}`
  168 For simplicity in decoding, if a `begin` packet is sent, all attempts
  169 are made to ensure that a final `end` packet is also sent.
  171 ### `_type: end`
  173 After the last substantial data packet, a final `end` packet is sent
  174 to signal to the client that this reply is finished.
  176 e.g:
  177     `{"_tag":"108","_type":"end"}`
  179 ### `_type: row`
  181 The substantial bulk of the data in the reply is contained within one or
  182 more `row` packets.  The non metadata contents of each `row` packet is
  183 defined entirely by the method called and may change from version to version.
  185 Each `row` packet contains exactly one complete JSON object. The row replies
  186 may be processed incrementally as each row arrives and no batching of multiple
  187 packets will be required.
  189 e.g:
  190     `{"_tag":"108","_type":"row","mode":"p2p","ip4addr":"","macaddr":"86:56:21:E4:AA:39","sockaddr":"","desc":"client4","lastseen":1584682200}`
  192 ### `_type: subscribed`
  194 Signals that the subscription request has been successfully completed.
  195 Any future events on the requested channel will be asynchronously sent
  196 as `event` packets using the same tag as the subscribe request.
  198 ### `_type: unsubscribed`
  200 Only one management client can be subscribed to any given event topic, so if
  201 another subscribe request arrives, the older client will be sent this message
  202 to let them know that they have been replaced.
  204 (In the future, this may also be sent as a reply to a explicit unsubscribe
  205 request)
  207 ### `_type: replacing`
  209 If a new subscription request will replace an existing one, this message is
  210 sent to the new client to inform them that they have replaced an older
  211 connection.
  213 ### `_type: event`
  215 Asynchronous events will arrive with this message type, using the same tag as
  216 the original subscribe request.  Just like with the `row` packets, the non
  217 metadata contents are entirely defined by the topic and the specific n2n
  218 version.
  220 ## Subscribe API
  222 A client can subscribe to events using a request with the type of "s".
  223 Once a subscribe has been successfully completed, any events published
  224 on that channel will be forwarded to the client.
  226 Only one management client can be subscribed to any given event topic,
  227 with newer subscriptions replacing older ones.
  229 The special channel "debug" will receive copies of all events published.
  230 Note that this is for debugging of events and the packets may not have
  231 the same tag as the debug subscription.
  233 ## Authentication
  235 Some API requests will make global changes to the running daemon and may
  236 affect the availability of the n2n networking.  Therefore the machine
  237 readable API include an authentication component.
  239 Currently, the only authentication is a simple password that the client
  240 must provide. It defaults to 'n2n' and can manually be set through the
  241 command line parameter `--management-password <pw>` – for edge as well
  242 as for supernode.