"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

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)