Merge branch 'winwarnings' of https://github.com/dechamps/tinc into 1.1

[tinc] / doc / tinc.conf.5.in

diff --git a/doc/tinc.conf.5.in b/doc/tinc.conf.5.in
index f208803..9d9bf76 100644 (file)
--- a/doc/tinc.conf.5.in
+++ b/doc/tinc.conf.5.in
@@ -116,11 +116,13 @@ is selected, then depending on the operating system both IPv4 and IPv6 or just
 IPv6 listening sockets will be created.
 .It Va AutoConnect Li = yes | no Po no Pc Bq experimental
 If set to yes,
-.Nm
+.Nm tinc
 will automatically set up meta connections to other nodes,
 without requiring
 .Va ConnectTo
 variables.
+.Pp
+Note: it is not possible to connect to nodes using zero (system-assigned) ports in this way.
 .It Va BindToAddress Li = Ar address Op Ar port
 This is the same as
 .Va ListenAddress ,
@@ -155,6 +157,13 @@ Broadcast packets are sent directly to all nodes that can be reached directly.
 Broadcast packets received from other nodes are never forwarded.
 If the IndirectData option is also set, broadcast packets will only be sent to nodes which we have a meta connection to.
 .El
+.It Va BroadcastSubnet Li = Ar address Ns Op Li / Ns Ar prefixlength
+Declares a broadcast subnet. Any packet with a destination address falling into such a subnet will be routed as a broadcast (provided all nodes have it declared).
+This is most useful to declare subnet broadcast addresses (e.g. 10.42.255.255), otherwise
+.Nm tinc
+won't know what to do with them.
+.Pp
+Note that global broadcast addresses (MAC ff:ff:ff:ff:ff:ff, IPv4 255.255.255.255), as well as multicast space (IPv4 224.0.0.0/4, IPv6 ff00::/8) are always considered broadcast addresses and don't need to be declared.
 .It Va ConnectTo Li = Ar name
 Specifies which other tinc daemon to connect to on startup.
 Multiple
@@ -333,7 +342,15 @@ To only listen on a specific port but not on a specific address, use
 .Li *
 for the
 .Ar address .
-.It Va LocalDiscovery Li = yes | no Pq no
+.Pp
+If
+.Ar port
+is set to zero, it will be randomly assigned by the system. This is useful to randomize source ports of UDP packets, which can improve UDP hole punching reliability. In this case it is recommended to set
+.Va AddressFamily
+as well, otherwise
+.Nm tinc
+will assign different ports to different address families but other nodes can only know of one.
+.It Va LocalDiscovery Li = yes | no Pq yes
 When enabled,
 .Nm tinc
 will try to detect peers that are on the same local network.
@@ -380,7 +397,8 @@ while no routing table is managed.
 .It Va Name Li = Ar name Bq required
 This is the name which identifies this tinc daemon.
 It must be unique for the virtual private network this daemon will connect to.
-The Name may only consist of alphanumeric and underscore characters (a-z, A-Z, 0-9 and _), and is case sensitive.
+.Va Name
+may only consist of alphanumeric and underscore characters (a-z, A-Z, 0-9 and _), and is case sensitive.
 If 
 .Va Name
 starts with a
@@ -541,6 +559,14 @@ The port number on which this tinc daemon is listening for incoming connections,
 which is used if no port number is specified in an
 .Va Address
 statement.
+.Pp
+If this is set to zero, the port will be randomly assigned by the system. This is useful to randomize source ports of UDP packets, which can improve UDP hole punching reliability. When setting
+.Va Port
+to zero it is recommended to set
+.Va AddressFamily
+as well, otherwise
+.Nm tinc
+will assign different ports to different address families but other nodes can only know of one.
 .It Va PublicKey Li = Ar key Bq obsolete
 The public RSA key of this tinc daemon.
 It will be used to cryptographically verify it's identity and to set up a secure connection.