<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
		<title>Overview</title>

		<section>
			<title> The idea</title>
			<para>
			A stun server working with the same port as SIP (5060) in order to
			gain accurate information. The benefit would be an exact external 
			address in the case of NATs translating differently when given 
			different destination ports. The server may also advertise different
			network addresses than the ones it is actually listening on.
			</para>
		</section>

		<section>
			<title> Basic Operation</title>
			<para>
			The stun server will use 4 sockets:
			<itemizedlist>
				<listitem>socket1 = ip1 : port1</listitem>
				<listitem>socket2 = ip1 : port2</listitem>
				<listitem>socket3 = ip2 : port1</listitem>
				<listitem>socket4 = ip2 : port2</listitem>
			</itemizedlist>
			where <emphasis>ip1</emphasis> / <emphasis>port1</emphasis>
			represent an UDP SIP listener and <emphasis>ip2</emphasis> /
			 <emphasis>port2</emphasis> are configured via the
			<xref linkend="param_alternate_ip"/> and
			<xref linkend="param_alternate_port"/>
			parameters.
			</para>
			<para>
				The sockets come from existing SIP sockets or are created.
			</para>
			<para>
				Socket1 must allways be a SIP UDP listener from OpenSIPS.
			</para>
			<para>
			If <xref linkend="param_use_listeners_as_primary"/> is enabled
			the STUN server will actually use multiple sets of sockets obtained
			from the IP/port combinations described above, each set corresponding
			to a SIP UDP listener from OpenSIPS.
			</para>
			<para>
				The server will create a separate process.
				This process will listen for data on created sockets.
				The server will register a callback function to SIP.
				This function is called when a specific (stun)header is found.
			</para>
		</section>

		<section>
			<title> Supported STUN Attributes </title>
			<para>
				This stun implements RFC3489 (and XOR_MAPPED_ADDRESS from 
				RFC5389)
			</para>
			<para>
			<itemizedlist>
				<listitem>MAPPED_ADDRESS</listitem>
				<listitem>RESPONSE_ADDRESS</listitem>
				<listitem>CHANGE_REQUEST</listitem>
				<listitem>SOURCE_ADDRESS</listitem>
				<listitem>CHANGED_ADDRESS</listitem>
				<listitem>ERROR_CODE</listitem>
				<listitem>UNKNOWN_ATTRIBUTES</listitem>
				<listitem>REFLECTED_FROM</listitem>
				<listitem>XOR_MAPPED_ADDRESS</listitem>
			</itemizedlist>
			</para>
			<para> Not supported attributes:</para>
			<para>
			<itemizedlist>
				<listitem>USERNAME</listitem>
				<listitem>PASSWORD</listitem>
				<listitem>MESSAGE_INTEGRITY</listitem>
			</itemizedlist>
			and associated ERROR_CODEs
			</para>

		</section>

	</section>

	<section id="dependencies" xreflabel="Dependencies">
		<title>Dependencies</title>
		<section>
			<title>&osips; Modules</title>
			<para>
			The following modules must be loaded before this module:
			</para>
			<para>
			<emphasis>None</emphasis>.
			</para>
		</section>

		<section>
			<title>External Libraries or Applications</title>
			<para>
			The following libraries or applications must be installed before 
			running &osips; with this module loaded:
				<itemizedlist>
					<listitem>
						<para>
							<emphasis>None</emphasis>.
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_primary_ip" xreflabel="primary_ip">
			<title>
				<varname>primary_ip</varname> (str)
			</title>
			<para>
			The IP of an interface which is configured as an UDP SIP listener
			in &osips;. This is a mandatory parameter, unless
			<xref linkend="param_use_listeners_as_primary"/> is enabled.
			</para>
			<para>
			Syntax: "ip [/ advertised_ip]
			</para>
			<para>
			By default, the <emphasis>primary_ip</emphasis> and the advertised
			<emphasis>primary_ip</emphasis> will be identical.
			This may be changed with an optional "/ xxx.xxx.xxx.xxx" string.
			</para>
			<example>
				<title>Set
					<varname>primary_ip</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("stun", "primary_ip", "192.168.0.100")

# Example of a STUN server within OpenSIPS which is behind NAT
modparam("stun", "primary_ip", "192.168.0.100 / 64.50.46.78")
...
				</programlisting>
			</example>
		</section>
		
		<section id="param_primary_port" xreflabel="primary_port">
			<title>
				<varname>primary_port</varname> (str)
			</title>
			<para>
			The port configured (together with the <emphasis>primary_ip</emphasis>) as an UDP SIP
			listener in &osips;. The default value is 5060.
			</para>
			<para>
			Syntax: "port [/ advertised_port]
			</para>
			<para>
			By default, the <emphasis>primary_port</emphasis> and the advertised
			<emphasis>primary_port</emphasis> will be identical.
			This may be changed with an optional "/ adv_port" string.
			</para>
			<example>
				<title>Set <varname>primary_port</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("stun", "primary_port", "5060")

# Listening on a primary port, but advertising a different one
modparam("stun", "primary_port", "5060 / 5062")
...
				</programlisting>
			</example>
		</section>

		<section id="param_alternate_ip" xreflabel="alternate_ip">
			<title>
				<varname>alternate_ip</varname> (str)
			</title>
			<para>
			Another IP from another interface. This is a mandatory parameter.
			</para>
			<para>
			If <xref linkend="param_use_listeners_as_primary"/> is enabled, the
			alternate IP must be either:
			<itemizedlist>
				<listitem>
				<para>
				an IP from an existing UDP SIP listener configured in OpenSIPS,
				but one that is different from all the other UPD listeners;
				</para>
				</listitem>
				<listitem>
				<para>
				an IP that is different from the UDP SIP listeners configured in OpenSIPS.
				</para>
				</listitem>
			</itemizedlist>
			</para>
			<para>
			Syntax: "ip [/ advertised_ip]
			</para>
			<para>
			By default, the <emphasis>alternate_ip</emphasis> and the advertised
			<emphasis>alternate_ip</emphasis> will be identical.
			This may be changed with an optional "/ xxx.xxx.xxx.xxx" string.
			</para>
			<example>
				<title>Set
					<varname>alternate_ip</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("stun","alternate_ip","11.22.33.44")

# Example of a STUN server within OpenSIPS which is behind NAT
modparam("stun", "alternate_ip", "192.168.0.100 / 64.78.46.50")
...
				</programlisting>
			</example>
		</section>
		
		<section id="param_alternate_port" xreflabel="alternate_port">
			<title>
				<varname>alternate_port</varname> (str)
			</title>
			<para>
			The port used by the STUN server for the second interface.
			The default value is 3478 (default STUN port).
			</para>
			<para>
			If <xref linkend="param_use_listeners_as_primary"/> is enabled, the
			alternate port must be either:
			<itemizedlist>
				<listitem>
				<para>
				a port from an existing UDP SIP listener configured in OpenSIPS,
				but one that is different from all the other UPD listeners;
				</para>
				</listitem>
				<listitem>
				<para>
				a port that is different from the UDP SIP listeners configured in OpenSIPS.
				</para>
				</listitem>
			</itemizedlist>
			</para>
			<para>
			Syntax: "port [/ advertised_port]
			</para>
			<para>
			By default, the <emphasis>alternate_port</emphasis> and the advertised
			<emphasis>alternate_port</emphasis> will be identical.
			This may be changed with an optional "/ adv_port" string.
			</para>
			<example>
				<title>Set
					<varname>alternate_port</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("stun","alternate_port","3479")

# Listening on an alternate port, but advertising a different one
modparam("stun", "alternate_port", "5060 / 5062")
...
				</programlisting>
			</example>
		</section>

		<section id="param_use_listeners_as_primary" xreflabel="use_listeners_as_primary">
			<title>
				<varname>use_listeners_as_primary</varname> (int)
			</title>
			<para>
			Setting this parameter to <emphasis>1</emphasis> will allow all
			configured UDP SIP listeners to be automatically used as "primary"
			STUN sockets.
			</para>
			<para>
			The <xref linkend="param_primary_ip"/> and
			<xref linkend="param_primary_port"/>
			parameters will be ignored when this behavior is enabled.
			</para>
			<para>
			The default value is <emphasis>0</emphasis> (disabled).
			</para>
			<example>
				<title>Set
					<varname>use_listeners_as_primary</varname> parameter
				</title>
				<programlisting format="linespecific">
...
modparam("stun","use_listeners_as_primary",1)
...
				</programlisting>
			</example>
		</section>

	</section>

</chapter>
