[asterisk-dev] proposed change to sip.conf.sample

[Luigi Rizzo]

Hi,
I would like to make the following change to the part of
sip.conf.sample that deals with NAT support.

Comments/objections/suggestion for better phrasing of the text ?
Note, it might well be that this is a comon topic for other channel
types, in which case one might put the documentation in one file,
e.g. asterisk.conf.sample, and put a reference to it in the
various <tech>.conf.sample files.

The STUN part is not there yet but it is really trivial to implement
now that we have ast_stun_request()
(besides, I can omit that part now, and add it when the code is
added to chan_sip.c)

	cheers
	luigi

Index: configs/sip.conf.sample
===================================================================
--- configs/sip.conf.sample	(revision 75381)
+++ configs/sip.conf.sample	(working copy)
@@ -293,29 +293,59 @@
 				; Default is 0 tries, continue forever
 
 ;----------------------------------------- NAT SUPPORT ------------------------
-; The externip, externhost and localnet settings are used if you use Asterisk
-; behind a NAT device to communicate with services on the outside.
+; When asterisk is behind a NAT device, the "local" address (and port) that
+; a socket is bound to, has different values when seen from the inside or
+; from the outside of the NATted network. Because the "local" address must
+; be communicated to the outside (e.g. in SIP and SDP messages), asterisk
+; needs to know:
+;
+; A. whether it is talking to someone "inside" or "outside".
+;   This is configured by assigning the "localnet" parameter with a list
+;   a list of network addresses that are considered "inside" of the NAT.
+;   Multiple entries are allowed, e.g. a reasonable set of defaults is this:
+;
+;      localnet=192.168.0.0/255.255.0.0 ; RFC 1918 addresses
+;      localnet=10.0.0.0/255.0.0.0	; Also RFC1918
+;      localnet=172.16.0.0/12		; Another RFC1918 with CIDR notation
+;      localnet=169.254.0.0/255.255.0.0 ;Zero conf local network
+;
+; B. the "internal" and "external" address (and port number).
+;   The "internal" address/port is computed internally as the address/port
+;   that the socket is bound to.
+;   The "external" address/port can be derived in a number of ways:
+;
+;   1. with the "externip" parameter, which specifies a static address/port
+;      to be used when talking to the outside.
+;
+;	externip = 12.34.56.78		; only address. Keep original port
+;	externip = 12.34.56.78:9900	; also port is remapped
+;	externip = foo.dyndns.net	; lookup only once.
+;
+;   2. with the "externhost" parameter, which is similar to "externip" except
+;      that it can contain a hostname which is looked up every
+;      "externrefresh" seconds (default 10s). Beware, you might suffer
+;      from service disruption when the name server resolution fails.
+;
+;	externhost=foo.dyndns.net	; refreshed periodically
+;	externrefresh=10		; default 10s
+;
+;   3. running STUN queries to the server specified in "stunaddr",
+;      also refreshed periodically every "externrefresh" seconds.
+;
+;	stunaddr = foo.stun.com:3478
+;	externrefresh = 10
+;
+; NOTE 1: in some cases, NAT boxes will need to use different port numbers in
+; the internal<->external mapping. In these cases, the "externip" and
+; "externhost" might not help you configure addresses properly, and you
+; really need to use STUN.
+;
+; NOTE 2: when using "externip" or "externhost", the address part is
+; also used as the external address for media sessions.
+; If you use "stunaddr", STUN queries will be sent to the same server
+; also from media sockets, and this should permit a correct mapping of
+; the port numbers as well.
 
-;externip = 200.201.202.203	; Address that we're going to put in outbound SIP
-				; messages if we're behind a NAT
-
-				; The externip and localnet is used
-				; when registering and communicating with other proxies
-				; that we're registered with
-;externhost=foo.dyndns.net	; Alternatively you can specify an 
-				; external host, and Asterisk will 
-				; perform DNS queries periodically.  Not
-				; recommended for production 
-				; environments!  Use externip instead
-;externrefresh=10		; How often to refresh externhost if 
-				; used
-				; You may add multiple local networks.  A reasonable 
-				; set of defaults are:
-;localnet=192.168.0.0/255.255.0.0; All RFC 1918 addresses are local networks
-;localnet=10.0.0.0/255.0.0.0	; Also RFC1918
-;localnet=172.16.0.0/12		; Another RFC1918 with CIDR notation
-;localnet=169.254.0.0/255.255.0.0 ;Zero conf local network
-
 ; The nat= setting is used when Asterisk is on a public IP, communicating with
 ; devices hidden behind a NAT device (broadband router).  If you have one-way
 ; audio problems, you usually have problems with your NAT configuration or your