aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2012-08-29 11:49:46 +0200
committerAnders Svensson <[email protected]>2012-08-29 18:22:22 +0200
commit6530d6b10490311d37080da982282a3b69bad059 (patch)
tree8d77e7ea0e90d91400817116ae2c630f9877cbb5 /lib/diameter
parente70a331569b2d161d976950d209989a5dc06a2bc (diff)
downloadotp-6530d6b10490311d37080da982282a3b69bad059.tar.gz
otp-6530d6b10490311d37080da982282a3b69bad059.tar.bz2
otp-6530d6b10490311d37080da982282a3b69bad059.zip
Add SCTP warning, more references
Diffstat (limited to 'lib/diameter')
-rw-r--r--lib/diameter/doc/src/diameter_sctp.xml48
-rw-r--r--lib/diameter/doc/src/diameter_tcp.xml49
-rw-r--r--lib/diameter/doc/src/diameter_transport.xml2
3 files changed, 64 insertions, 35 deletions
diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml
index 03e2f1f6be..7e02a07bb4 100644
--- a/lib/diameter/doc/src/diameter_sctp.xml
+++ b/lib/diameter/doc/src/diameter_sctp.xml
@@ -60,9 +60,9 @@ and implements the behaviour documented in
<v>Type = connect | accept</v>
<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
<v>Svc = #diameter_service{}</v>
-<v>Opt = {raddr, inet:ip_address()} | {rport, integer()} | term()</v>
+<v>Opt = {raddr, <seealso marker="kernel:inet">inet:ip_address()</seealso>} | {rport, integer()} | term()</v>
<v>Pid = pid()</v>
-<v>LAddr = inet:ip_address()</v>
+<v>LAddr = <seealso marker="kernel:inet">inet:ip_address()</seealso></v>
<v>Reason = term()</v>
</type>
<desc>
@@ -75,12 +75,13 @@ marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
The only diameter_sctp-specific argument is the options list.
Options <c>raddr</c> and <c>rport</c> specify the remote address
and port for a connecting transport and not valid for a listening
-transport.
-The former is required while latter defaults to 3868 if unspecified.
+transport: the former is required while latter defaults to 3868 if
+unspecified.
More than one <c>raddr</c> option can be specified, in which case the
connecting transport in question attempts each in sequence until
an association is established.
-Remaining options are any accepted by gen_sctp:open/1, with the exception
+Remaining options are any accepted by <seealso
+marker="kernel:gen_sctp">gen_sctp:open/1</seealso>, with the exception
of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
and <c>sctp_events</c>.
Note that options <c>ip</c> and <c>port</c> specify the local address
@@ -88,30 +89,45 @@ and port respectively.</p>
<p>
Multiple <c>ip</c> options can be specified for a multihomed peer.
-If none are specified then the values of Host-IP-Address
-on the service are used. (In particular, one of these must be specified.)
+If none are specified then the values of <c>Host-IP-Address</c>
+in the <c>#diameter_service{}</c> record are used.
+(In particular, one of these must be specified.)
Option <c>port</c> defaults to 3868 for a listening transport and 0 for a
connecting transport.</p>
+<warning>
+<p>
+An insufficiently large receive buffer may result in a peer having to
+resend incoming messages: set the <seealso
+marker="kernel:inet">inet</seealso> option <c>recbuf</c> to increase
+the buffer size.</p>
+
+<p>
+An insufficiently large send buffer may result in outgoing messages
+being discarded: set the <seealso
+marker="kernel:inet">inet</seealso> option <c>sndbuf</c> to increase
+the buffer size.</p>
+</warning>
+
<p>
diameter_sctp uses the <c>transport_data</c> field of
-the <c>diameter_packet</c> record to communicate the stream on which an
+the <c>#diameter_packet{}</c> record to communicate the stream on which an
inbound message has been received, or on which an outbound message
should be sent: the value will be of the form <c>{stream, Id}</c>
on an inbound message passed to a <seealso
marker="diameter_app#handle_request">handle_request</seealso> or <seealso
marker="diameter_app#handle_answer">handle_answer</seealso> callback.
-For an outbound message, either <c>undefined</c> (explicitly of
-by specifying the outbound message as a <c>binary()</c>) or a tuple
+For an outbound message, either <c>undefined</c> (explicitly or
+by receiving the outbound message as a <c>binary()</c>) or a tuple
should be set in the return value of <seealso
marker="diameter_app#handle_request">handle_request</seealso>
(typically by retaining the value passed into this function)
or <seealso
marker="diameter_app#prepare_request">prepare_request</seealso>.
-The value <c>undefined</c> uses a "next outbound stream" id and then
-increments this modulo the total number outbound streams. That
-is, successive values of <c>undefined</c> cycle through all outbound
-streams.</p>
+The value <c>undefined</c> uses a "next outbound stream" id and
+increments this modulo the total number outbound streams.
+That is, successive values of <c>undefined</c> cycle through all
+outbound streams.</p>
<!-- TODO: Some way of getting at the number of available outbound -->
<!-- streams. -->
@@ -128,7 +144,9 @@ streams.</p>
<title>SEE ALSO</title>
<p>
-<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>,
+<seealso marker="kernel:gen_sctp">gen_sctp(3)</seealso>,
+<seealso marker="kernel:inet">inet(3)</seealso></p>
</section>
diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml
index 6ad98c8640..b42d65701e 100644
--- a/lib/diameter/doc/src/diameter_tcp.xml
+++ b/lib/diameter/doc/src/diameter_tcp.xml
@@ -38,8 +38,9 @@ under the License.
<description>
<p>
-This module implements diameter transport over TCP using gen_tcp.
-It can be specified as the value of a transport_module option to
+This module implements diameter transport over TCP using <seealso
+marker="kernel:gen_sctp">gen_tcp</seealso>.
+It can be specified as the value of a <c>transport_module</c> option to
<seealso
marker="diameter#add_transport">diameter:add_transport/2</seealso>
and implements the behaviour documented in
@@ -67,15 +68,15 @@ before configuring TLS capability on diameter transports.</p>
<v>Type = connect | accept</v>
<v>Ref = <seealso marker="diameter#transport_ref">diameter:transport_ref()</seealso></v>
<v>Svc = #diameter_service{}</v>
-<v>Opt = OwnOpt | SslOpt | OtherOpt</v>
+<v>Opt = OwnOpt | SslOpt | TcpOpt</v>
<v>Pid = pid()</v>
-<v>LAddr = inet:ip_address()</v>
+<v>LAddr = <seealso marker="kernel:inet">inet:ip_address()</seealso></v>
<v>Reason = term()</v>
-<v>OwnOpt = {raddr, inet:ip_address()}
+<v>OwnOpt = {raddr, <seealso marker="kernel:inet">inet:ip_address()</seealso>}
| {rport, integer()}
| {port, integer()}</v>
<v>SslOpt = {ssl_options, true | list()}</v>
-<v>OtherOpt = term()</v>
+<v>TcpOpt = term()</v>
</type>
<desc>
@@ -89,25 +90,32 @@ Options <c>raddr</c> and <c>rport</c> specify the remote address
and port for a connecting transport and are not valid for a listening
transport.
Option <c>ssl_options</c> must be specified for a transport
-that must be able to support TLS: a value of <c>true</c> results in a
+that should support TLS: a value of <c>true</c> results in a
TLS handshake immediately upon connection establishment while
-list() specifies options to be passed to ssl:connect/2 of ssl:ssl_accept/2
+<c>list()</c> specifies options to be passed to <seealso
+marker="ssl:ssl">ssl:connect/2</seealso> or
+<seealso marker="ssl:ssl">ssl:ssl_accept/2</seealso>
after capabilities exchange if TLS is negotiated.
-Remaining options are any accepted by ssl:connect/3 or gen_tcp:connect/3 for
-a connecting transport, or ssl:listen/3 or gen_tcp:listen/2 for
+Remaining options are any accepted by <seealso
+marker="ssl:ssl">ssl:connect/3</seealso> or <seealso
+marker="kernel:gen_tcp">gen_tcp:connect/3</seealso> for
+a connecting transport, or <seealso
+marker="ssl:ssl">ssl:listen/3</seealso> or <seealso
+marker="kernel:gen_tcp">gen_tcp:listen/2</seealso> for
a listening transport, depending on whether or not <c>{ssl_options, true}</c>
has been specified.
-Options <c>binary</c>, <c>packet</c> and <c>active</c> cannot be specified.
+Options <c>binary</c>,
+<c>packet</c> and <c>active</c> cannot be specified.
Also, option <c>port</c> can be specified for a listening transport
to specify the local listening port, the default being the standardized
3868 if unspecified.
-Note that option <c>ip</c> specifies the local address.</p>
+Note that the option <c>ip</c> specifies the local address.</p>
<p>
An <c>ssl_options</c> list must be specified if and only if
-the transport in question has specified an Inband-Security-Id
-AVP with value TLS on the relevant call to
-<seealso
+the transport in question has set <c>Inband-Security-Id</c> to
+1 (<c>TLS</c>), as
+specified to either <seealso
marker="diameter#start_service">start_service/2</seealso> or
<seealso
marker="diameter#add_transport">add_transport/2</seealso>,
@@ -122,9 +130,9 @@ that will not be forthcoming, which will eventually cause the RFC 3539
watchdog to take down the connection.</p>
<p>
-If the service specifies more than one Host-IP-Address and
-option <c>ip</c> is unspecified then the
-first of the service's addresses is used as the local address.</p>
+If the <c>#diameter_service{}</c> record has more than one
+<c>Host-IP-Address</c> and option <c>ip</c> is unspecified then the
+first of the these addresses is used as the local address.</p>
<p>
The returned local address list has length one.</p>
@@ -142,7 +150,10 @@ The returned local address list has length one.</p>
<p>
<seealso marker="diameter">diameter(3)</seealso>,
-<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
+<seealso marker="diameter_transport">diameter_transport(3)</seealso>,
+<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>,
+<seealso marker="kernel:inet">inet(3)</seealso>,
+<seealso marker="ssl:ssl">ssl(3)</seealso></p>
</section>
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 4890333669..e852041278 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -63,7 +63,7 @@ parent).</p>
<v>Svc = #diameter_service{}</v>
<v>Opts = term()</v>
<v>Pid = pid()</v>
-<v>LAddrs = [inet:ip_address()]</v>
+<v>LAddrs = [<seealso marker="kernel:inet">inet:ip_address()</seealso>]</v>
<v>Reason = term()</v>
</type>
<desc>