From: Etienne Dechamps <etienne@edechamps.fr>
Date: Sun, 6 Jul 2014 10:34:57 +0000 (+0100)
Subject: Add documentation about using system-assigned ports.
X-Git-Tag: release-1.1pre11~65
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=7bf61575fe1009ecb93b3f6b8f5145525874e470;p=oweals%2Ftinc.git

Add documentation about using system-assigned ports.

There are two caveats to be aware of which are documented in this
commit:

 - Because the system will likely assign different ports when binding
   several times to different address families, it is recommended to
   only use a single address family, otherwise other nodes will only
   get one port among the several that were assigned, possibly breaking
   communication.

 - AutoConnect won't work in this scenario, because it relies on the UDP
   port being the same as the TCP port, which is not the case when using
   system-assigned ports.
---

diff --git a/doc/tinc.conf.5.in b/doc/tinc.conf.5.in
index 771a25f..9d9bf76 100644
--- a/doc/tinc.conf.5.in
+++ b/doc/tinc.conf.5.in
@@ -121,6 +121,8 @@ 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 ,
@@ -340,6 +342,14 @@ To only listen on a specific port but not on a specific address, use
 .Li *
 for the
 .Ar address .
+.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
@@ -549,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.