Update config.go godoc

src/config/config.go

@@ -1,3 +1,19 @@
+/*
+The config package contains structures related to the configuration of an
+Yggdrasil node.
+
+The configuration contains, amongst other things, encryption keys which are used
+to derive a node's identity, information about peerings and node information
+that is shared with the network. There are also some module-specific options
+related to TUN/TAP, multicast and the admin socket.
+
+In order for a node to maintain the same identity across restarts, you should
+persist the configuration onto the filesystem or into some configuration storage
+so that the encryption keys (and therefore the node ID) do not change.
+
+Note that Yggdrasil will automatically populate sane defaults for any
+configuration option that is not provided.
+*/
 package config
 
 import (
@@ -8,30 +24,30 @@ import (
 	"github.com/yggdrasil-network/yggdrasil-go/src/defaults"
 )
 
-// NodeState represents the active and previous configuration of the node and
+// NodeState represents the active and previous configuration of an Yggdrasil
-// protects it with a mutex
+// node. A NodeState object is returned when starting an Yggdrasil node. Note
+// that this structure and related functions are likely to disappear soon.
 type NodeState struct {
 	Current  NodeConfig
 	Previous NodeConfig
 	Mutex    sync.RWMutex
 }
 
-// Current returns the current node config
+// Current returns the active node configuration.
 func (s *NodeState) GetCurrent() NodeConfig {
 	s.Mutex.RLock()
 	defer s.Mutex.RUnlock()
 	return s.Current
 }
 
-// Previous returns the previous node config
+// Previous returns the previous node configuration.
 func (s *NodeState) GetPrevious() NodeConfig {
 	s.Mutex.RLock()
 	defer s.Mutex.RUnlock()
 	return s.Previous
 }
 
-// Replace the node configuration with new configuration. This method returns
+// Replace the node configuration with new configuration.
-// both the new and the previous node configs
 func (s *NodeState) Replace(n NodeConfig) {
 	s.Mutex.Lock()
 	defer s.Mutex.Unlock()
@@ -39,7 +55,9 @@ func (s *NodeState) Replace(n NodeConfig) {
 	s.Current = n
 }
 
-// NodeConfig defines all configuration values needed to run a signle yggdrasil node
+// NodeConfig is the main configuration structure, containing configuration
+// options that are necessary for an Yggdrasil node to run. You will need to
+// supply one of these structs to the Yggdrasil core when starting a node.
 type NodeConfig struct {
 	Peers                       []string               `comment:"List of connection strings for outbound peer connections in URI format,\ne.g. tcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j. These connections\nwill obey the operating system routing table, therefore you should\nuse this section when you may connect via different interfaces."`
 	InterfacePeers              map[string][]string    `comment:"List of connection strings for outbound peer connections in URI format,\narranged by source interface, e.g. { \"eth0\": [ tcp://a.b.c.d:e ] }.\nNote that SOCKS peerings will NOT be affected by this option and should\ngo in the \"Peers\" section instead."`
@@ -62,7 +80,7 @@ type NodeConfig struct {
 	NodeInfo                    map[string]interface{} `comment:"Optional node info. This must be a { \"key\": \"value\", ... } map\nor set as null. This is entirely optional but, if set, is visible\nto the whole network on request."`
 }
 
-// SessionFirewall controls the session firewall configuration
+// SessionFirewall controls the session firewall configuration.
 type SessionFirewall struct {
 	Enable                        bool     `comment:"Enable or disable the session firewall. If disabled, network traffic\nfrom any node will be allowed. If enabled, the below rules apply."`
 	AllowFromDirect               bool     `comment:"Allow network traffic from directly connected peers."`
@@ -72,7 +90,8 @@ type SessionFirewall struct {
 	BlacklistEncryptionPublicKeys []string `comment:"List of public keys from which network traffic is always rejected,\nregardless of the whitelist, AllowFromDirect or AllowFromRemote."`
 }
 
-// TunnelRouting contains the crypto-key routing tables for tunneling
+// TunnelRouting contains the crypto-key routing tables for tunneling regular
+// IPv4 or IPv6 subnets across the Yggdrasil network.
 type TunnelRouting struct {
 	Enable            bool              `comment:"Enable or disable tunnel routing."`
 	IPv6RemoteSubnets map[string]string `comment:"IPv6 subnets belonging to remote nodes, mapped to the node's public\nkey, e.g. { \"aaaa:bbbb:cccc::/e\": \"boxpubkey\", ... }"`
@@ -81,18 +100,15 @@ type TunnelRouting struct {
 	IPv4LocalSubnets  []string          `comment:"IPv4 subnets belonging to this node's end of the tunnels. Only traffic\nfrom these ranges will be tunnelled."`
 }
 
-// SwitchOptions contains tuning options for the switch
+// SwitchOptions contains tuning options for the switch. These are advanced
+// options and shouldn't be changed unless necessary.
 type SwitchOptions struct {
 	MaxTotalQueueSize uint64 `comment:"Maximum size of all switch queues combined (in bytes)."`
 }
 
-// Generates default configuration. This is used when outputting the -genconf
+// Generates default configuration and returns a pointer to the resulting
-// parameter and also when using -autoconf. The isAutoconf flag is used to
+// NodeConfig. This is used when outputting the -genconf parameter and also when
-// determine whether the operating system should select a free port by itself
+// using -autoconf.
-// (which guarantees that there will not be a conflict with any other services)
-// or whether to generate a random port number. The only side effect of setting
-// isAutoconf is that the TCP and UDP ports will likely end up with different
-// port numbers.
 func GenerateConfig() *NodeConfig {
 	// Generate encryption keys.
 	bpub, bpriv := crypto.NewBoxKeys()
@@ -122,16 +138,19 @@ func GenerateConfig() *NodeConfig {
 	return &cfg
 }
 
-// NewEncryptionKeys generates a new encryption keypair. The encryption keys are
+// NewEncryptionKeys replaces the encryption keypair in the NodeConfig with a
-// used to encrypt traffic and to derive the IPv6 address/subnet of the node.
+// new encryption keypair. The encryption keys are used by the router to encrypt
+// traffic and to derive the node ID and IPv6 address/subnet of the node, so
+// this is equivalent to discarding the node's identity on the network.
 func (cfg *NodeConfig) NewEncryptionKeys() {
 	bpub, bpriv := crypto.NewBoxKeys()
 	cfg.EncryptionPublicKey = hex.EncodeToString(bpub[:])
 	cfg.EncryptionPrivateKey = hex.EncodeToString(bpriv[:])
 }
 
-// NewSigningKeys generates a new signing keypair. The signing keys are used to
+// NewSigningKeys replaces the signing keypair in the NodeConfig with a new
-// derive the structure of the spanning tree.
+// signing keypair. The signing keys are used by the switch to derive the
+// structure of the spanning tree.
 func (cfg *NodeConfig) NewSigningKeys() {
 	spub, spriv := crypto.NewSigKeys()
 	cfg.SigningPublicKey = hex.EncodeToString(spub[:])