"Fossies" - the Fresh Open Source Software Archive 
Source code changes of the file "doc/ManagementAPI.md" between
n2n-3.0.tar.gz and n2n-3.1.1.tar.gz
About: n2n is a layer-two peer-to-peer virtual private network (VPN) which allows bypassing intermediate firewalls. Pre-release.
| ManagementAPI.md (n2n-3.0) | : | ManagementAPI.md (n2n-3.1.1) | ||
|---|---|---|---|---|
| skipping to change at line 61 | skipping to change at line 61 | |||
| the API method to use for additional parameters | the API method to use for additional parameters | |||
| Fields: | Fields: | |||
| - Message Type | - Message Type | |||
| - Options | - Options | |||
| - Method | - Method | |||
| - Optional Additional Parameters | - Optional Additional Parameters | |||
| The maximum length of the entire line of text is 80 octets. | The maximum length of the entire line of text is 80 octets. | |||
| All request packets should generate a reply. However, this reply may simply | ||||
| be an error. | ||||
| ### Message Type | ### Message Type | |||
| This is a single octet that is either "r" for a read (or query) method | This is a single octet specifying the type: | |||
| call or "w" for a write (or change) method call. | ||||
| - "r" for a read-only method (or one that does not need change permissions) | ||||
| - "w" for a write method (or one that makes changes) | ||||
| - "s" for a subscribe method to request this socket receive some events | ||||
| To simplify the interface, the reply from both read and write calls to the | To simplify the interface, the reply from both read and write calls to the | |||
| same method is expected to contain the same data. In the case of a write | same method is expected to contain the same data. In the case of a write | |||
| call, the reply will contain the new state after making the requested change. | call, the reply will contain the new state after making the requested change. | |||
| The subscribe and events message flow works with a different set of messages. | ||||
| ### Options | ### Options | |||
| The options field is a colon separated set of options for this request. Only | The options field is a colon separated set of options for this request. Only | |||
| the first subfield (the "tag") is mandatory. The second subfield is a set | the first subfield (the "tag") is mandatory. The second subfield is a set | |||
| of flags that describe which optional subfields are present. | of flags that describe which optional subfields are present. | |||
| If there are no additional subfields then the flags can be omitted. | If there are no additional subfields then the flags can be omitted. | |||
| SubFields: | SubFields: | |||
| - Message Tag | - Message Tag | |||
| - Optional Message Flags (defaults to 0) | - Optional Message Flags (defaults to 0) | |||
| - Optional Authentication Key | - Optional Authentication Key | |||
| #### Message Tag | #### Message Tag | |||
| Each request provides a tag value. Any non error reply associated with this | Each request provides a tag value. Any non error reply associated with this | |||
| request will include this tag value, allowing all related messages to be | request will include this tag value, allowing all related messages to be | |||
| collected within the client. | collected within the client. The tag will be truncated if needed by the | |||
| daemon, but there will be at least 8 octets of space available. | ||||
| Where possible, the error replies will also include this tag, however some | Where possible, the error replies will also include this tag, however some | |||
| errors occur before the tag is parsed. | errors occur before the tag is parsed. | |||
| The tag is not interpreted by the daemon, it is simply echoed back in all | The tag is not interpreted by the daemon, it is simply echoed back in all | |||
| the replies. It is expected to be a short string that the client chooses | the replies. It is expected to be a short string that the client knows | |||
| to be unique amongst all recent or still outstanding requests. | will be unique amongst all recent, still outstanding or subscription requests | |||
| on a given socket. | ||||
| One possible client implementation is a number between 0 and 999, incremented | One possible client implementation is a number between 0 and 999, incremented | |||
| for each request and wrapping around to zero when it is greater than 999. | for each request and wrapping around to zero when it is greater than 999. | |||
| #### Message Flags | #### Message Flags | |||
| This subfield is a set of bit flags that are hex-encoded and describe any | This subfield is a set of bit flags that are hex-encoded and describe any | |||
| remaining optional subfields. | remaining optional subfields. | |||
| Currently, only one flag is defined. The presence of that flag indicates | Currently, only one flag is defined. The presence of that flag indicates | |||
| skipping to change at line 130 | skipping to change at line 140 | |||
| ### Example Request string | ### Example Request string | |||
| e.g: | e.g: | |||
| `r 103:1:PassWord peer` | `r 103:1:PassWord peer` | |||
| ## Reply API | ## Reply API | |||
| Each UDP packet in the reply is a complete and valid JSON dictionary | Each UDP packet in the reply is a complete and valid JSON dictionary | |||
| containing a fragment of information related to the entire reply. | containing a fragment of information related to the entire reply. | |||
| Reply packets are generated both in response to requests and whenever | ||||
| an event is published to a subscribed channel. | ||||
| ### Common metadata | ### Common metadata | |||
| There are two keys in each dictionary containing metadata. First | There are two keys in each dictionary containing metadata. First | |||
| is the `_tag`, containing the Message Tag from the original request. | is the `_tag`, containing the Message Tag from the original request. | |||
| Second is the `_type` whic identifies the expected contents of this | Second is the `_type` which identifies the expected contents of this | |||
| packet. | packet. | |||
| ### `_type: error` | ### `_type: error` | |||
| If an error condition occurs, a packet with a `error` key describing | If an error condition occurs, a packet with a `error` key describing | |||
| the error will be sent. This usually also indicates that there will | the error will be sent. This usually also indicates that there will | |||
| be no more substantial data arriving related to this request. | be no more substantial data arriving related to this request. | |||
| e.g: | e.g: | |||
| `{"_tag":"107","_type":"error","error":"badauth"}` | `{"_tag":"107","_type":"error","error":"badauth"}` | |||
| skipping to change at line 179 | skipping to change at line 192 | |||
| more `row` packets. The non metadata contents of each `row` packet is | more `row` packets. The non metadata contents of each `row` packet is | |||
| defined entirely by the method called and may change from version to version. | defined entirely by the method called and may change from version to version. | |||
| Each `row` packet contains exactly one complete JSON object. The row replies | Each `row` packet contains exactly one complete JSON object. The row replies | |||
| may be processed incrementally as each row arrives and no batching of multiple | may be processed incrementally as each row arrives and no batching of multiple | |||
| packets will be required. | packets will be required. | |||
| e.g: | e.g: | |||
| `{"_tag":"108","_type":"row","mode":"p2p","ip4addr":"10.135.98.84","macaddr" :"86:56:21:E4:AA:39","sockaddr":"192.168.7.191:41701","desc":"client4","lastseen ":1584682200}` | `{"_tag":"108","_type":"row","mode":"p2p","ip4addr":"10.135.98.84","macaddr" :"86:56:21:E4:AA:39","sockaddr":"192.168.7.191:41701","desc":"client4","lastseen ":1584682200}` | |||
| ### `_type: subscribed` | ||||
| Signals that the subscription request has been successfully completed. | ||||
| Any future events on the requested channel will be asynchronously sent | ||||
| as `event` packets using the same tag as the subscribe request. | ||||
| ### `_type: unsubscribed` | ||||
| Only one management client can be subscribed to any given event topic, so if | ||||
| another subscribe request arrives, the older client will be sent this message | ||||
| to let them know that they have been replaced. | ||||
| (In the future, this may also be sent as a reply to a explicit unsubscribe | ||||
| request) | ||||
| ### `_type: replacing` | ||||
| If a new subscription request will replace an existing one, this message is | ||||
| sent to the new client to inform them that they have replaced an older | ||||
| connection. | ||||
| ### `_type: event` | ||||
| Asynchronous events will arrive with this message type, using the same tag as | ||||
| the original subscribe request. Just like with the `row` packets, the non | ||||
| metadata contents are entirely defined by the topic and the specific n2n | ||||
| version. | ||||
| ## Subscribe API | ||||
| A client can subscribe to events using a request with the type of "s". | ||||
| Once a subscribe has been successfully completed, any events published | ||||
| on that channel will be forwarded to the client. | ||||
| Only one management client can be subscribed to any given event topic, | ||||
| with newer subscriptions replacing older ones. | ||||
| The special channel "debug" will receive copies of all events published. | ||||
| Note that this is for debugging of events and the packets may not have | ||||
| the same tag as the debug subscription. | ||||
| ## Authentication | ## Authentication | |||
| Some API requests will make global changes to the running daemon and may | Some API requests will make global changes to the running daemon and may | |||
| affect the availability of the n2n networking. Therefore the machine | affect the availability of the n2n networking. Therefore the machine | |||
| readable API include an authentication component. | readable API include an authentication component. | |||
| Currently, the only authentication is a simple password that the client | Currently, the only authentication is a simple password that the client | |||
| must provide. It defaults to 'n2n' and can manually be set through the | must provide. It defaults to 'n2n' and can manually be set through the | |||
| command line parameter `--management-password <pw>` – for edge as well | command line parameter `--management-password <pw>` – for edge as well | |||
| as for supernode. | as for supernode. | |||
| End of changes. 8 change blocks. | ||||
| 6 lines changed or deleted | 60 lines changed or added | |||