cwinfo/yggdrasil-network.github.io
5
0
Fork 0
mirror of https://github.com/cwinfo/yggdrasil-network.github.io.git synced 2025-02-28 19:51:34 +00:00
Code Releases Activity

Add new configuration options

Browse Source
This commit is contained in:
Neil Alexander 2018-12-09 11:56:15 +00:00
parent 233df45c2a
commit 0096866fb4
No known key found for this signature in database
GPG Key ID: A02A2019A2BB0944
1 changed files with 97 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
configuration.md
View File

@ -8,27 +8,54 @@ Yggdrasil can be run with a dynamically generated configuration, using sane-ish
In most cases, a static configuration simplifies most setups - it allows you to maintain the same IP address, configure static peers and various other options that will persist across restarts.
Configuration can be provided to Yggdrasil in HJSON format either through `stdin` (using `yggdrasil --useconf < path/to/yggdrasil.conf`) or through a path to a configuration file (using `yggdrasil --useconffile path/to/yggdrasil.conf`).
Yggdrasil supports configuration in either HJSON or JSON format. HJSON is the default preferred format, as it has comments, although JSON support is available due to ease of manipulation.
A new configuration file may be generated with `yggdrasil --genconf > path/to/yggdrasil.conf`, which looks something like:
## Generating Configuration
If you installed Yggdrasil through one of the platform packages (i.e. macOS, Debian, RPM) then a default configuration file may already exist in `/etc/yggdrasil.conf`.
Otherwise, you can generate a configuration file in the following ways:
- HJSON: `yggdrasil -genconf > /etc/yggdrasil.conf`
- JSON: `yggdrasil -genconf -json > /etc/yggdrasil.conf`
## Using Configuration
Yggdrasil can accept a configuration file either through `stdin` or by being given a path on the filesystem to a configuration file:
- Using `stdin`: `yggdrasilctl --useconf < /etc/yggdrasil.conf`
- Using file: `yggdrasilctl --useconffile /etc/yggdrasil.conf`
## Normalising Configuration
If you want to see the original format of the configuration file, or convert between HJSON and JSON formats, you can use the `-normaliseconf` option, e.g.
- Convert from HJSON to JSON: `yggdrasilctl -normaliseconf -useconffile /etc/yggdrasil.conf -json`
- Convert from JSON to HJSON: `yggdrasilctl -normaliseconf -useconffile /etc/yggdrasil.conf`
Normalising the configuration also adds any missing configuration items with their default values. This can be useful when upgrading to a newer version of Yggdrasil that adds new configuration options. Many of our distribution packages normalise the configuration automatically during upgrade.
## Configuration Layout
A new configuration file has the following format. Please note that some of the default values will vary from platform to platform.
```
{
# Listen address for peer connections. Default is to listen for all
# TCP connections over IPv4 and IPv6 with a random port.
Listen: "[::]:52072"
Listen: "[::]:xxxxx"
# Listen address for admin connections Default is to listen for local
# connections either on TCP/9001 or a UNIX socket depending on your
# platform. Use this value for yggdrasilctl -endpoint=X.
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, e.g.
# tcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j.
Peers: []
# List of connection strings for static peers in URI format, arranged
# by source interface, i.e. { "eth0": [ tcp://a.b.c.d:e ] }. Note that
# by source interface, e.g. { "eth0": [ tcp://a.b.c.d:e ] }. Note that
# SOCKS peerings will NOT be affected by this option and should go in
# the "Peers" section instead.
InterfacePeers: {}
@ -84,31 +111,68 @@ A new configuration file may be generated with `yggdrasil --genconf > path/to/yg
# being routed via this node to somewhere else. Rules are prioritised as
# follows: blacklist, whitelist, always allow outgoing, direct, remote.
SessionFirewall:
{
{
# Enable or disable the session firewall. If disabled, network traffic
# from any node will be allowed. If enabled, the below rules apply.
# from any node will be allowed. If enabled, the below rules apply.
Enable: false
# Allow network traffic from directly connected peers.
# Allow network traffic from directly connected peers.
AllowFromDirect: true
# Allow network traffic from remote nodes on the network that you are
# not directly peered with.
# not directly peered with.
AllowFromRemote: true
# Allow outbound network traffic regardless of AllowFromDirect or
# AllowFromRemote. This does allow a remote node to send unsolicited
# traffic back to you for the length of the session.
# traffic back to you for the length of the session.
AlwaysAllowOutbound: false
# List of public keys from which network traffic is always accepted,
# regardless of AllowFromDirect or AllowFromRemote.
# regardless of AllowFromDirect or AllowFromRemote.
WhitelistEncryptionPublicKeys: []
# List of public keys from which network traffic is always rejected,
# regardless of the whitelist, AllowFromDirect or AllowFromRemote.
# regardless of the whitelist, AllowFromDirect or AllowFromRemote.
BlacklistEncryptionPublicKeys: []
}
# Allow tunneling non-Yggdrasil traffic over Yggdrasil. This effectively
# allows you to use Yggdrasil to route to, or to bridge other networks,
# similar to a VPN tunnel. Tunnelling works between any two nodes and
# does not require them to be directly peered.
TunnelRouting:
{
# Enable or disable tunnel routing.
Enable: false
# IPv6 CIDR subnets, mapped to the EncryptionPublicKey to which they
# should be routed, e.g. { "aaaa:bbbb:cccc::/e": "boxpubkey", ... }
IPv6Destinations: {}
# Optional IPv6 source subnets which are allowed to be tunnelled in
# addition to this node's Yggdrasil address/subnet. If not
# specified, only traffic originating from this node's Yggdrasil
# address or subnet will be tunnelled.
IPv6Sources: []
# IPv4 CIDR subnets, mapped to the EncryptionPublicKey to which they
# should be routed, e.g. { "a.b.c.d/e": "boxpubkey", ... }
IPv4Destinations: {}
# IPv4 source subnets which are allowed to be tunnelled. Unlike for
# IPv6, this option is required for bridging IPv4 traffic. Only
# traffic with a source matching these subnets will be tunnelled.
IPv4Sources: []
}
# Advanced options for tuning the switch. Normally you will not need
# to edit these options.
SwitchOptions:
{
# Maximum size of all switch queues combined (in bytes).
MaxTotalQueueSize: 4194304
}
}
```
@ -124,7 +188,7 @@ Note that any field not specified in the configuration will use its default valu
- Port to listen on for the admin socket, specified in URI format, i.e. `tcp://localhost:9001`.
- On supported platforms, the admin socket can listen on a UNIX domain socket instead, i.e. `unix:///var/run/yggdrasil.sock`.
- 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.
- Note that if you change the listen address to a non-loopback address, this may allow other hosts on the network to manage the Yggdrasil process. This probably isn't desirable.
- `Peers`
- A list of strings in the form `[ "tcp://peerAddress:peerPort", "socks://proxyAddress:proxyPort/peerAddress:peerPort", ... ]` of peers to connect to.
- Peer hostnames can be specified either using IPv4 addresses, IPv6 addresses or DNS names.
@ -142,13 +206,13 @@ Note that any field not specified in the configuration will use its default valu
- A node's IP address is derived from the ID.
- `EncryptionPrivateKey`
- A hexadecimal string representing the node's private Curve25519 key.
- This is a private key, don't share it.
- This is a private key, **don't share it with anyone**.
- `SigningPublicKey`
- A hexadecimal string representing a node's public Ed25519 key.
- Used primarily for signatures in the greedy routing scheme.
- `SigningPrivateKey`
- A hexadecimal string representing the node's private Ed25519 key.
- This is a private key, don't share it.
- This is a private key, **don't share it with anyone**.
- `MulticastInterfaces`
- A list of regex strings for matching which interfaces to enable multicast peer discovery on. Interfaces that don't match any of the provided regexes are ignored.
- The default value (`.*`) matches all interfaces.
@ -160,13 +224,14 @@ Note that any field not specified in the configuration will use its default valu
- The behaviour of this option is different on different operating systems. Some quick notes:
- 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 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.
- `IfTAPMode`
- 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.
- 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, it may be possible to bridge with the Yggdrasil `tap` adapter, e.g. to allow container bridging.
- `IfMTU`
- 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.
@ -178,17 +243,23 @@ Note that any field not specified in the configuration will use its default valu
- Disables or enables the session firewall.
- If enabled, the rules from the below options apply. If disabled, all traffic is allowed.
- `AllowFromDirect`
- Allows traffic from nodes that are direct peers.
- Decides whether or not traffic should be allowed from nodes that are directly peered to you.
- `AllowFromRemote`
- Allows traffic from nodes that are not direct peers.
- Decides whether or not traffic should be allowed from nodes that are elsewhere on the network and *not* directly peered to you.
- `AlwaysAllowOutbound`
- Allows traffic to a node only when outbound traffic is sent to that node.
- Decides whether to allow traffic to be sent to any node on the network, as long the connection is initiated from your node.
- Note that once you open a session with a remote node, they *can* send traffic back to you for the lifetime of the session.
- `WhitelistEncryptionPublicKeys`
- A list of node's `EncryptionPublicKey` keys that are always allowed to send traffic to this host.
- A list of node's `EncryptionPublicKey` keys that are always allowed to exchange traffic with this host, both incoming or outgoing.
- Takes priority over the above options, but is overridden by the blacklist below.
- `BlacklistEncryptionPublicKeys`
- A list of node's `EncryptionPublicKey` keys that are never allowed to communicate with this node under any circumstances.
- A list of node's `EncryptionPublicKey` keys that are never allowed to communicate with this node under any circumstances, both incoming or outgoing.
- Takes priority over all other options.
- `SwitchOptions`
- Switch options are advanced tuning settings. Ordinarily you should not attempt to change these from their defaults.
- Contains the following configuration options:
- `MaxTotalQueueSize`
- The maximum allowed size, in bytes, of all local switch queues combined. Default is `4194304` (or 4MB).
# Use Cases