cwinfo/yggdrasil-network.github.io
5
0
Fork 0
mirror of https://github.com/cwinfo/yggdrasil-network.github.io.git synced 2024-11-09 16:50:31 +00:00
Code Releases Activity

Update documentation for UNIX admin sockets

Browse Source
This commit is contained in:
Neil Alexander 2018-07-07 11:36:54 +01:00
parent db9de7cac2
commit 0c51ddb738
No known key found for this signature in database
GPG Key ID: A02A2019A2BB0944
2 changed files with 17 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
admin.md
View File

@ -17,7 +17,8 @@ yggdrasilctl setTunTap name=auto mtu=65535 tap_mode=false
To perform an action on a remote Yggdrasil node, specify the `-endpoint` parameter: To perform an action on a remote Yggdrasil node, specify the `-endpoint` parameter:
``` ```
yggdrasilctl -endpoint=10.0.0.1:9001 getPeers 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: To get the JSON response body instead of a "friendly" output, specify the `-json` parameter:
@ -57,7 +58,7 @@ A request:
- *Must* have any other required fields for the request - *Must* have any other required fields for the request
- *Can* have any other optional fields for the request - *Can* have any other optional fields for the request
### Response ### Response
A typical response is structured like this: A typical response is structured like this:
``` ```
@ -68,11 +69,11 @@ A typical response is structured like this:
"foo": "bar", "foo": "bar",
"baz": "qux" "baz": "qux"
}, },
"response": "response":
{ {
}, },
"status": "success" "status": "success"
} }
``` ```
@ -85,7 +86,7 @@ A response:
### Request Types ### Request Types
The `"request"` field contains a verb that describes which request to perform. The `"request"` field contains a verb that describes which request to perform.
#### `getDHT` #### `getDHT`
@ -101,7 +102,7 @@ Returns known nodes in the DHT.
Expects no additional request fields. 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. Returns one or more records containing information about active peer sessions. The first record typically refers to the current node.
For each IPv6 address: For each IPv6 address:
- `bytes_sent` (`uint64`) contains the number of bytes sent to that peer - `bytes_sent` (`uint64`) contains the number of bytes sent to that peer
@ -129,7 +130,7 @@ Removes an existing peer.
Returns: Returns:
- Zero or more successful `string` ports in the `"removed"` section - Zero or more successful `string` ports in the `"removed"` section
- Zero or more failed `string` ports in the `"not_removed"` section - Zero or more failed `string` ports in the `"not_removed"` section
#### `getSwitchPeers` #### `getSwitchPeers`
@ -139,7 +140,7 @@ Returns zero or more records containing information about switch peers.
For each port number: For each port number:
- `coords` (`string`) contains the coordinates of the node on the spanning tree - `coords` (`string`) contains the coordinates of the node on the spanning tree
- `ip` (`string`) contains the IPv6 address of the node - `ip` (`string`) contains the IPv6 address of the node
#### `getSelf` #### `getSelf`
@ -167,7 +168,7 @@ For each IPv6 address:
Expects no additional request fields. Expects no additional request fields.
Returns exactly one record containing information about the current node's TUN/TAP adapter. Returns exactly one record containing information about the current node's TUN/TAP adapter.
For each adapter: For each adapter:
- `tap_mode` (`bool`) shows whether or not the interface is in TAP mode (if `false` then TUN mode is implied) - `tap_mode` (`bool`) shows whether or not the interface is in TAP mode (if `false` then TUN mode is implied)

14
configuration.md
View File

@ -16,7 +16,7 @@ A new configuration file may be generated with `yggdrasil --genconf > path/to/yg
# Listen address for admin connections Default is to listen for local # Listen address for admin connections Default is to listen for local
# connections only on TCP port 9001. # connections only on TCP port 9001.
AdminListen: localhost:9001 AdminListen: "tcp://localhost:9001"
# List of connection strings for static peers in URI format, i.e. # List of connection strings for static peers in URI format, i.e.
# tcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j # tcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j
@ -73,9 +73,10 @@ Note that any field not specified in the configuration will use its default valu
- Note that, due to Go language design choices, `[::]` listens on IPv4 and IPv6 on most platforms, while an empty IP or `0.0.0.0` listens only to IPv4. - Note that, due to Go language design choices, `[::]` listens on IPv4 and IPv6 on most platforms, while an empty IP or `0.0.0.0` listens only to IPv4.
- The default is to listen on all addresses (`[::]`) with a random port. - The default is to listen on all addresses (`[::]`) with a random port.
- `AdminListen` - `AdminListen`
- Port to listen on for the (TCP) admin socket. - Port to listen on for the admin socket, specified in URI format, i.e. `tcp://localhost:9001`.
- The default is to listen on the loopback interface (`localhost:9001`) which ensures that only local connections to the admin socket are allowed. - On supported platforms, the admin socket can listen on a UNIX domain socket instead, i.e. `unix:///var/run/yggdrasil.sock`.
- Note that if you change the listen address to a non-loopback address, this will allow other hosts on the network to manage the Yggdrasil process. This probably isn't desirable. - The default is to listen on the loopback interface (`tcp://localhost:9001`) which ensures that only local connections to the admin socket are allowed.
- Note that if you change the listen address to a non-loopback address, this will allow other hosts on the network to manage the Yggdrasil process. This probably isn't desirable.
- `Peers` - `Peers`
- A list of strings in the form `[ "peerAddress:peerPort", "peerAddress:peerPort", ... ]` of peers to connect to. - A list of strings in the form `[ "peerAddress:peerPort", "peerAddress:peerPort", ... ]` of peers to connect to.
- Peer hostnames can be specified either using IPv4 addresses, IPv6 addresses or DNS names. - Peer hostnames can be specified either using IPv4 addresses, IPv6 addresses or DNS names.
@ -108,14 +109,14 @@ Note that any field not specified in the configuration will use its default valu
- You can also specify `"none"` as the interface name, in which case Yggdrasil will run as a router only without opening a network interface. This effectively allows Yggdrasil to carry traffic for other nodes without exposing the system to the network. - You can also specify `"none"` as the interface name, in which case Yggdrasil will run as a router only without opening a network interface. This effectively allows Yggdrasil to carry traffic for other nodes without exposing the system to the network.
- The behaviour of this option is different on different operating systems. Some quick notes: - The behaviour of this option is different on different operating systems. Some quick notes:
- On Linux, any suitable interface name can be specified. - On Linux, any suitable interface name can be specified.
- On FreeBSD, OpenBSD and NetBSD, a full path to the TAP interface should be specified, i.e. `"/dev/tap0"`. - On FreeBSD, OpenBSD and NetBSD, a full path to the TAP interface should be specified, i.e. `"/dev/tap0"`.
- On macOS, a utun device is automatically assigned by the operating system, therefore you cannot specify a name. - On macOS, a utun device is automatically assigned by the operating system, therefore you cannot specify a name.
- On Windows, a network adapter friendly name (like `"Local Area Connection 2"`) can be specified to choose a specific adapter. Use "Network Adapters" in Control Panel to see and/or rename adapters. - On Windows, a network adapter friendly name (like `"Local Area Connection 2"`) can be specified to choose a specific adapter. Use "Network Adapters" in Control Panel to see and/or rename adapters.
- `IfTAPMode` - `IfTAPMode`
- If true, then the interface will be a `tap` device (Layer 2) instead of a `tun` (Layer 3) device. - If true, then the interface will be a `tap` device (Layer 2) instead of a `tun` (Layer 3) device.
- Default value is platform specific, and some platforms support only `tun` or `tap` mode. - Default value is platform specific, and some platforms support only `tun` or `tap` mode.
- Note that the network only transports IPv6 packets, so frames sent to or received from a `tap` are decapsulated or encapsulated at the end points of a connection. - Note that the network only transports IPv6 packets, so frames sent to or received from a `tap` are decapsulated or encapsulated at the end points of a connection.
- In TAP mode, Yggdrasil automatically answers Neighbor Discovery Packet (NDP) requests on behalf of Yggdrasil IPv6 addresses. - In TAP mode, Yggdrasil automatically answers Neighbor Discovery Packet (NDP) requests on behalf of Yggdrasil IPv6 addresses.
- `IfMTU` - `IfMTU`
- The MTU of the `tun`/`tap` interface. - The MTU of the `tun`/`tap` interface.
- Defaults to the maximum value supported on each platform, up to `65535` on Linux/macOS/Windows, `32767` on FreeBSD, `16384` on OpenBSD, `9000` on NetBSD, etc. - Defaults to the maximum value supported on each platform, up to `65535` on Linux/macOS/Windows, `32767` on FreeBSD, `16384` on OpenBSD, `9000` on NetBSD, etc.
@ -184,4 +185,3 @@ GOPATH=$PWD go run -tags debug misc/genkeys.go
This continually generates new keys and prints them out each time a new best set of keys is discovered. This continually generates new keys and prints them out each time a new best set of keys is discovered.
These keys may then be manually added to the configuration file. These keys may then be manually added to the configuration file.