Update comments in configuration and some godoc descriptions

src/yggdrasil/ckr.go

@@ -28,6 +28,7 @@ type cryptokey_route struct {
 	destination []byte
 }
 
+// Initialise crypto-key routing. This must be done before any other CKR calls.
 func (c *cryptokey) init(core *Core) {
 	c.core = core
 	c.ipv4routes = make([]cryptokey_route, 0)
@@ -38,14 +39,19 @@ func (c *cryptokey) init(core *Core) {
 	c.ipv6sources = make([]net.IPNet, 0)
 }
 
+// Enable or disable crypto-key routing.
 func (c *cryptokey) setEnabled(enabled bool) {
 	c.enabled = enabled
 }
 
+// Check if crypto-key routing is enabled.
 func (c *cryptokey) isEnabled() bool {
 	return c.enabled
 }
 
+// Check whether the given address (with the address length specified in bytes)
+// matches either the current node's address, the node's routed subnet or the
+// list of subnets specified in IPv4Sources/IPv6Sources.
 func (c *cryptokey) isValidSource(addr address, addrlen int) bool {
 	ip := net.IP(addr[:addrlen])
 
@@ -86,6 +92,8 @@ func (c *cryptokey) isValidSource(addr address, addrlen int) bool {
 	return false
 }
 
+// Adds a source subnet, which allows traffic with these source addresses to
+// be tunnelled using crypto-key routing.
 func (c *cryptokey) addSourceSubnet(cidr string) error {
 	// Is the CIDR we've been given valid?
 	_, ipnet, err := net.ParseCIDR(cidr)
@@ -121,6 +129,8 @@ func (c *cryptokey) addSourceSubnet(cidr string) error {
 	return nil
 }
 
+// Adds a destination route for the given CIDR to be tunnelled to the node
+// with the given BoxPubKey.
 func (c *cryptokey) addRoute(cidr string, dest string) error {
 	// Is the CIDR we've been given valid?
 	ipaddr, ipnet, err := net.ParseCIDR(cidr)
@@ -190,6 +200,9 @@ func (c *cryptokey) addRoute(cidr string, dest string) error {
 	return errors.New("Unspecified error")
 }
 
+// Looks up the most specific route for the given address (with the address
+// length specified in bytes) from the crypto-key routing table. An error is
+// returned if the address is not suitable or no route was found.
 func (c *cryptokey) getPublicKeyForAddress(addr address, addrlen int) (boxPubKey, error) {
 	// Check if the address is a valid Yggdrasil address - if so it
 	// is exempt from all CKR checking

src/yggdrasil/config/config.go

@@ -4,8 +4,8 @@ package config
 type NodeConfig struct {
 	Listen                      string              `comment:"Listen address for peer connections. Default is to listen for all\nTCP connections over IPv4 and IPv6 with a random port."`
 	AdminListen                 string              `comment:"Listen address for admin connections Default is to listen for local\nconnections either on TCP/9001 or a UNIX socket depending on your\nplatform. Use this value for yggdrasilctl -endpoint=X."`
-	Peers                       []string            `comment:"List of connection strings for static peers in URI format, i.e.\ntcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j."`
+	Peers                       []string            `comment:"List of connection strings for static peers in URI format, e.g.\ntcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j."`
-	InterfacePeers              map[string][]string `comment:"List of connection strings for static peers in URI format, arranged\nby source interface, i.e. { \"eth0\": [ tcp://a.b.c.d:e ] }. Note that\nSOCKS peerings will NOT be affected by this option and should go in\nthe \"Peers\" section instead."`
+	InterfacePeers              map[string][]string `comment:"List of connection strings for static peers in URI format, arranged\nby source interface, e.g. { \"eth0\": [ tcp://a.b.c.d:e ] }. Note that\nSOCKS peerings will NOT be affected by this option and should go in\nthe \"Peers\" section instead."`
 	ReadTimeout                 int32               `comment:"Read timeout for connections, specified in milliseconds. If less\nthan 6000 and not negative, 6000 (the default) is used. If negative,\nreads won't time out."`
 	AllowedEncryptionPublicKeys []string            `comment:"List of peer encryption public keys to allow or incoming TCP\nconnections from. If left empty/undefined then all connections\nwill be allowed by default."`
 	EncryptionPublicKey         string              `comment:"Your public encryption key. Your peers may ask you for this to put\ninto their AllowedEncryptionPublicKeys configuration."`
@@ -17,7 +17,7 @@ type NodeConfig struct {
 	IfTAPMode                   bool                `comment:"Set local network interface to TAP mode rather than TUN mode if\nsupported by your platform - option will be ignored if not."`
 	IfMTU                       int                 `comment:"Maximux Transmission Unit (MTU) size for your local TUN/TAP interface.\nDefault is the largest supported size for your platform. The lowest\npossible value is 1280."`
 	SessionFirewall             SessionFirewall     `comment:"The session firewall controls who can send/receive network traffic\nto/from. This is useful if you want to protect this node without\nresorting to using a real firewall. This does not affect traffic\nbeing routed via this node to somewhere else. Rules are prioritised as\nfollows: blacklist, whitelist, always allow outgoing, direct, remote."`
-	TunnelRouting               TunnelRouting       `comment:"Allow tunneling non-Yggdrasil traffic over Yggdrasil."`
+	TunnelRouting               TunnelRouting       `comment:"Allow tunneling non-Yggdrasil traffic over Yggdrasil. This effectively\nallows you to use Yggdrasil to route to, or to bridge other networks,\nsimilar to a VPN tunnel. Tunnelling works between any two nodes and\ndoes not require them to be directly peered."`
 	//Net                         NetConfig `comment:"Extended options for connecting to peers over other networks."`
 }
 
@@ -39,9 +39,9 @@ type SessionFirewall struct {
 
 // TunnelRouting contains the crypto-key routing tables for tunneling
 type TunnelRouting struct {
-	Enable           bool              `comment:"Enable or disable tunneling."`
+	Enable           bool              `comment:"Enable or disable tunnel routing."`
-	IPv6Destinations map[string]string `comment:"IPv6 subnets, mapped to the EncryptionPublicKey to which they should\nbe routed to."`
+	IPv6Destinations map[string]string `comment:"IPv6 CIDR subnets, mapped to the EncryptionPublicKey to which they\nshould be routed, e.g. { \"aaaa:bbbb:cccc::/e\": \"boxpubkey\", ... }"`
-	IPv6Sources      []string          `comment:"Optional IPv6 subnets which are allowed to be used as source addresses\nin addition to this node's Yggdrasil address/subnet."`
+	IPv6Sources      []string          `comment:"Optional IPv6 source subnets which are allowed to be tunnelled in\naddition to this node's Yggdrasil address/subnet. If not\nspecified, only traffic originating from this node's Yggdrasil\naddress or subnet will be tunnelled."`
-	IPv4Destinations map[string]string `comment:"IPv4 subnets, mapped to the EncryptionPublicKey to which they should\nbe routed to."`
+	IPv4Destinations map[string]string `comment:"IPv4 CIDR subnets, mapped to the EncryptionPublicKey to which they\nshould be routed, e.g. { \"a.b.c.d/e\": \"boxpubkey\", ... }"`
-	IPv4Sources      []string          `comment:"Optional IPv4 subnets which are allowed to be used as source addresses."`
+	IPv4Sources      []string          `comment:"IPv4 source subnets which are allowed to be tunnelled. Unlike for\nIPv6, this option is required for bridging IPv4 traffic. Only\ntraffic with a source matching these subnets will be tunnelled."`
 }

src/yggdrasil/router.go

@@ -140,6 +140,7 @@ func (r *router) sendPacket(bs []byte) {
 		copy(sourceAddr[:addrlen], bs[12:])
 		copy(dest[:addrlen], bs[16:])
 	} else {
+		// Unknown address length
 		return
 	}
 	if !r.cryptokey.isValidSource(sourceAddr, addrlen) {
@@ -287,6 +288,7 @@ func (r *router) recvPacket(bs []byte, sinfo *sessionInfo) {
 		copy(sourceAddr[:addrlen], bs[12:])
 		copy(dest[:addrlen], bs[16:])
 	} else {
+		// Unknown address length
 		return
 	}
 	if !r.cryptokey.isValidSource(dest, addrlen) {