diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 308 |
1 files changed, 271 insertions, 37 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index b7669b760b..db19fbb271 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1,5 +1,9 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY spawn_opt + '<seealso marker="erts:erlang#spawn_opt-2">erlang:spawn_opt/2</seealso>'> + <!ENTITY nodes + '<seealso marker="erts:erlang#nodes-0">erlang:nodes/0</seealso>'> <!ENTITY make_ref '<seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>'> <!ENTITY transport_module @@ -16,7 +20,7 @@ <header> <copyright> -<year>2011</year><year>2012</year> +<year>2011</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -25,12 +29,12 @@ Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. - + Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - + </legalnotice> <title>diameter(3)</title> @@ -41,7 +45,7 @@ under the License. <approved></approved> <checked></checked> <date></date> -<rev>%VSN%</rev> +<rev></rev> <file>diameter.xml</file> </header> @@ -69,8 +73,8 @@ Incoming Diameter requests are communicated as callbacks to a specified in the service configuration.</p> <p> -Beware the difference between <em>diameter</em> (not capitalised) and -<em>Diameter</em> (capitalised). +Beware the difference between <em>diameter</em> (not capitalized) and +<em>Diameter</em> (capitalized). The former refers to the Erlang application named diameter whose main api is defined here, the latter to Diameter protocol in the sense of &the_rfc;.</p> @@ -188,7 +192,7 @@ Defaults to the value of the <c>alias</c> option if unspecified.</p> <item> <p> Specifies whether or not the &app_pick_peer; -application callback can modify the application state, +application callback can modify the application state. Defaults to <c>false</c> if unspecified.</p> <note> @@ -206,11 +210,13 @@ probably avoid it.</p> <item> <p> Determines the manner in which incoming answer messages containing -decode errors are handled. +decode errors are handled.</p> + +<p> If <c>callback</c> then errors result in a &app_handle_answer; callback in the same fashion as for &app_handle_request;, with errors communicated in the <c>errors</c> field of the -<c>#diameter_packet{}</c> record passed to the callback. +<c>#diameter_packet{}</c> passed to the callback. If <c>report</c> then an answer containing errors is discarded without a callback and a warning report is written to the log. If <c>discard</c> then an answer containing errors is silently @@ -224,6 +230,39 @@ question is as if a callback had taken place and returned Defaults to <c>report</c> if unspecified.</p> </item> +<tag><c>{request_errors, answer_3xxx|answer|callback}</c></tag> +<item> +<p> +Determines the manner in which incoming requests are handled when an +error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot +be associated with an application callback module), is detected.</p> + +<p> +If <c>answer_3xxx</c> then requests are answered without a +&app_handle_request; callback taking place. +If <c>answer</c> then even 5xxx errors are answered without a +callback unless the connection in question has configured the RFC 3588 +common dictionary as noted below. +If <c>callback</c> then a &app_handle_request; callback always takes +place and the return value determines the answer sent to the peer.</p> + +<p> +Defaults to <c>answer_3xxx</c> if unspecified.</p> + +<note> +<p> +Answers sent by diameter set the E-bit in the Diameter Header. +Since RFC 3588 allowed only 3xxx result codes in an +<c>answer-message</c>, <c>answer</c> has the same semantics as +<c>answer_3xxx</c> if the peer connection in question has configured +the RFC 3588 common dictionary, <c>diameter_gen_base_rfc3588</c>. +RFC 6733 allows both 3xxx and 5xxx result codes in an +<c>answer-message</c> so a connection configured with the RFC 6733 +common dictionary, <c>diameter_gen_base_rfc6733</c>, does +distinguish between <c>answer_3xxx</c> and <c>answer</c>.</p> +</note> +</item> + </taglist> <marker id="call_opt"/> @@ -306,8 +345,9 @@ Has one of the following types.</p> An address list is available to the start function of a &transport_module;, which can return a new list for use in the subsequent CER or CEA. -Host-IP-Address need not be specified if the transport start function -returns an address list.</p> +Host-IP-Address need not be specified if the transport module in +question communicates an address list as described in +&man_transport;</p> </item> <tag><c>{'Vendor-Id', &dict_Unsigned32;}</c></tag> @@ -488,16 +528,23 @@ candidates list.</p> <marker id="service_event"/> </item> - -<tag><c>service_event() = #diameter_event{}</c></tag> +<tag><c>service_event() = #diameter_event{service = &service_name;, + info = &service_event_info;}</c></tag> <item> <p> An event message sent to processes that have subscribed to these using &subscribe;.</p> +<marker id="service_event_info"/> +</item> + +<tag><c>service_event_info() = term()</c></tag> + +<item> + <p> -The <c>info</c> field of the event record can have one of the -following types.</p> +The <c>info</c> field of a &service_event; record. +Can have one of the following types.</p> <taglist> @@ -527,16 +574,16 @@ Pkt = #diameter_packet{} The RFC 3539 watchdog state machine has transitioned into (<c>up</c>) or out of (<c>down</c>) the OKAY state. -If a <c>#diameter_packet{}</c> record is present in an <c>up</c> event +If a <c>#diameter_packet{}</c> is present in an <c>up</c> event then there has been a capabilties exchange on a newly established transport connection and the record contains the received CER or CEA. Otherwise a connection has reestablished without the loss or connectivity.</p> <p> -Note that a single <c>up</c>/<c>down</c> event for a given peer -corresponds to one &app_peer_up;/&app_peer_down; -callback for each of the Diameter applications negotiated during +Note that a single <c>up</c> or <c>down</c> event for a given peer +corresponds to multiple &app_peer_up; or &app_peer_down; +callbacks, one for each of the Diameter applications negotiated during capablilities exchange. That is, the event communicates connectivity with the peer as a whole while the callbacks communicate connectivity with @@ -582,7 +629,7 @@ CB = &evaluable; <p> An incoming CER has been answered with the indicated result code or discarded. -<c>Caps</c> contains pairs of values for the the local node and remote +<c>Caps</c> contains pairs of values for the local node and remote peer. <c>Pkt</c> contains the CER in question. In the case of rejection by a capabilities callback, the tuple @@ -600,7 +647,7 @@ Pkt = #diameter_packet{} <p> An incoming CER contained errors and has been answered with the indicated result code. -<c>Caps</c> contains only values for the the local node. +<c>Caps</c> contains only values for the local node. <c>Pkt</c> contains the CER in question.</p> </item> @@ -624,7 +671,7 @@ ResultCode = integer() An incoming CEA has been rejected for the indicated reason. An integer-valued <c>Result</c> indicates the result code sent by the peer. -<c>Caps</c> contains pairs of values for the the local node and remote +<c>Caps</c> contains pairs of values for the local node and remote peer. <c>Pkt</c> contains the CEA in question. In the case of rejection by a capabilities callback, the tuple @@ -640,7 +687,7 @@ Pkt = #diameter_packet{} <p> An incoming CEA contained errors and has been rejected. -<c>Caps</c> contains only values for the the local node. +<c>Caps</c> contains only values for the local node. <c>Pkt</c> contains the CEA in question.</p> </item> @@ -667,11 +714,14 @@ Config = {connect|listen, [transport_opt()]} An RFC 3539 watchdog state machine has changed state.</p> </item> -</taglist> - +<tag><c>any()</c></tag> +<item> <p> For forward compatibility, a subscriber should be prepared to receive info fields of forms other than the above.</p> +</item> + +</taglist> <marker id="service_name"/> </item> @@ -709,6 +759,15 @@ passed to &call;, while for an incoming request the application identifier in the message header determines the application, the identifier being specified in the application's &dictionary; file.</p> + +<warning> +<p> +The capabilities advertised by a node must match its configured +applications. In particular, <c>application</c> configuration must +be matched by corresponding &capability; configuration, of +Application-Id AVP's in particular.</p> +</warning> + </item> <tag><c>{restrict_connections, false @@ -718,16 +777,16 @@ the application's &dictionary; file.</p> | evaluable()}</c></tag> <item> <p> -Specifies the degree to which multiple transport connections to the -same peer are accepted by the service.</p> +Specifies the degree to which the service allows multiple transport +connections to the same peer.</p> <p> If type <c>[node()]</c> then a connection is rejected if another already exists on any of the specified nodes. -Values of type <c>false</c>, <c>node</c>, <c>nodes</c> or +Types <c>false</c>, <c>node</c>, <c>nodes</c> and &evaluable; are equivalent to -values <c>[]</c>, <c>[node()]</c>, <c>[node()|nodes()]</c> and the -evaluated value, respectively, evaluation of each expression taking +<c>[]</c>, <c>[node()]</c>, <c>[node()|nodes()]</c> and the +evaluated value respectively, evaluation of each expression taking place whenever a new connection is to be established. Note that <c>false</c> allows an unlimited number of connections to be established with the same peer.</p> @@ -765,6 +824,100 @@ non-negative integer less than <c>1 bsl (32-N)</c>.</p> <p> Defaults to <c>{0,32}</c>.</p> + +<warning> +<p> +Multiple Erlang nodes implementing the same Diameter node should +be configured with different sequence masks to ensure that each node +uses a unique range of End-to-End and Hop-by-Hop identifiers for +outgoing requests.</p> +</warning> +</item> + +<tag><c>{share_peers, boolean() | [node()] | evaluable()}</c></tag> +<item> +<p> +Specifies nodes to which peer connections established on the local +Erlang node are communicated. +Shared peers become available in the remote candidates list passed to +&app_pick_peer; callbacks on remote nodes whose services are +configured to use them: see <c>use_shared_peers</c> below.</p> + +<p> +If <c>false</c> then peers are not shared. +If <c>[node()]</c> then peers are shared with the specified list of +nodes. +If <c>evaluable()</c> then peers are shared with the nodes returned +by the specified function, evaluated whenever a peer connection +becomes available or a remote service requests information about local +connections. +The value <c>true</c> is equivalent to <c>fun &nodes;</c>. +The value <c>node()</c> in a node list is ignored, so a collection of +services can all be configured to share with the same list of +nodes.</p> + +<p> +Defaults to <c>false</c>.</p> + +<note> +<p> +Peers are only shared with services of the same name for the purpose +of sending outgoing requests. +Since the value of the &application_opt; <c>alias</c>, passed to +&call;, is the handle for identifying a peer as a suitable +candidate, services that share peers must use the same aliases to +identify their supported applications. +They should typically also configure identical &capabilities;, since +by sharing peer connections they are distributing the implementation +of a single Diameter node across multiple Erlang nodes.</p> +</note> +</item> + +<tag><c>{spawn_opt, [term()]}</c></tag> +<item> +<p> +An options list passed to &spawn_opt; when spawning a process for an +incoming Diameter request, unless the transport in question +specifies another value. +Options <c>monitor</c> and <c>link</c> are ignored.</p> + +<p> +Defaults to the empty list.</p> +</item> + +<tag><c>{use_shared_peers, boolean() | [node()] | evaluable()}</c></tag> +<item> +<p> +Specifies nodes from which communicated peers are made available in +the remote candidates list of &app_pick_peer; callbacks.</p> + +<p> +If <c>false</c> then remote peers are not used. +If <c>[node()]</c> then only peers from the specified list of nodes +are used. +If <c>evaluable()</c> then only peers returned by the specified +function are used, evaluated whenever a remote service communicates +information about an available peer connection. +The value <c>true</c> is equivalent to <c>fun &nodes;</c>. +The value <c>node()</c> in a node list is ignored.</p> + +<p> +Defaults to <c>false</c>.</p> + +<note> +<p> +A service that does not use shared peers will always pass the empty +list as the second argument of &app_pick_peer; callbacks.</p> +</note> + +<warning> +<p> +Sending a request over a peer connection on a remote node is less +efficient than sending it over a local connection. +It may be preferable to make use of the &service_opt; +<c>restrict_connections</c> and maintain a dedicated connection on +each node from which requests are sent.</p> +</warning> </item> </taglist> @@ -787,6 +940,16 @@ The list of Diameter applications to which the transport should be restricted. Defaults to all applications configured on the service in question. Applications not configured on the service in question are ignored.</p> + +<warning> +<p> +The capabilities advertised by a node must match its configured +applications. +In particular, setting <c>applications</c> on a transport typically +implies having to set matching Application-Id AVP's in a +&capabilities; tuple.</p> +</warning> + </item> <marker id="capabilities"/> @@ -858,9 +1021,8 @@ case the corresponding callbacks are applied until either all return The number of milliseconds after which a transport process having an established transport connection will be terminated if the expected capabilities exchange message (CER or CEA) is not received from the peer. -For a connecting transport, the timing reconnection attempts is -governed by &watchdog_timer; or -&reconnect_timer; expiry. +For a connecting transport, the timing of reconnection attempts is +governed by &watchdog_timer; or &reconnect_timer; expiry. For a listening transport, the peer determines the timing.</p> <p> @@ -877,7 +1039,7 @@ transport connection having watchdog state <c>OKAY</c>. Applied to <c>Reason=transport|service|application</c> and the <c>&transport_ref;</c> and <c>&app_peer;</c> -in question, <c>Reason</c> indicating whether the the diameter +in question, <c>Reason</c> indicating whether the diameter application is being stopped, the service in question is being stopped at &stop_service; or the transport in question is being removed at &remove_transport;, @@ -947,6 +1109,42 @@ configured them.</p> Defaults to a single callback returning <c>dpr</c>.</p> </item> +<marker id="length_errors"/> +<tag><c>{length_errors, exit|handle|discard}</c></tag> +<item> +<p> +Specifies how to deal with errors in the Message Length field of the +Diameter Header in an incoming message. +An error in this context is that the length is not at least 20 bytes +(the length of a Header), is not a multiple of 4 (a valid length) or +is not the length of the message in question, as received over the +transport interface documented in &man_transport;.</p> + +<p> +If <c>exit</c> then a warning report is emitted and the parent of the +transport process in question exits, which causes the transport +process itself to exit as described in &man_transport;. +If <c>handle</c> then the message is processed as usual, a resulting +&app_handle_request; or &app_handle_answer; callback (if one takes +place) indicating the <c>5015</c> error (DIAMETER_INVALID_MESSAGE_LENGTH). +If <c>discard</c> then the message in question is silently discarded.</p> + +<p> +Defaults to <c>exit</c>.</p> + +<note> +<p> +The default value reflects the fact that a transport module for a +stream-oriented transport like TCP may not be able to recover from a +message length error since such a transport must use the Message +Length header to divide the incoming byte stream into individual +Diameter messages. +An invalid length leaves it with no reliable way to rediscover message +boundaries, which may result in the failure of subsequent messages. +See &man_tcp; for the behaviour of that module.</p> +</note> +</item> + <marker id="reconnect_timer"/> <tag><c>{reconnect_timer, Tc}</c></tag> <item> @@ -977,9 +1175,21 @@ Defaults to 30000 for a connecting transport and 60000 for a listening transport.</p> </item> +<marker id="spawn_opt"/> +<tag><c>{spawn_opt, [term()]}</c></tag> +<item> +<p> +An options list passed to &spawn_opt; when spawning a process for an +incoming Diameter request. +Options <c>monitor</c> and <c>link</c> are ignored.</p> + +<p> +Defaults to the list configured on the service if not specified.</p> +</item> + <marker id="transport_config"/> <tag><c>{transport_config, term()}</c></tag> -<tag><c>{transport_config, term(), &dict_Unsigned32;}</c></tag> +<tag><c>{transport_config, term(), &dict_Unsigned32; | infinity}</c></tag> <item> <p> A term passed as the third argument to the &transport_start; function of @@ -1026,6 +1236,30 @@ modules in order until one establishes a connection within the corresponding timeout (see below) or all fail.</p> </item> +<marker id="watchdog_config"/> +<tag><c>{watchdog_config, [{okay|suspect, non_neg_integer()}]}</c></tag> +<item> +<p> +Specifies configuration that alters the behaviour of the watchdog +state machine. +On key <c>okay</c>, the non-negative number of answered DWR +messages before transitioning from REOPEN to OKAY. +On key <c>suspect</c>, the number of watchdog timeouts before +transitioning from OKAY to SUSPECT when DWR is unanswered, or 0 to +not make the transition.</p> + +<p> +Defaults to <c>[{okay, 3}, {suspect, 1}]</c>. +Not specifying a key is equivalent to specifying +the default value for that key.</p> +<warning> +<p> +The default value is as required by RFC 3539: changing it results +in non-standard behaviour that should only be used to simulate +misbehaving nodes during test.</p> +</warning> +</item> + <marker id="watchdog_timer"/> <tag><c>{watchdog_timer, TwInit}</c></tag> <item> @@ -1418,7 +1652,7 @@ The <c>caps</c> entry identifies the capabilities sent by the local node and received from the peer during capabilities exchange. The <c>port</c> entry displays socket-level information about the transport connection. -The <c>statistics</c> entry presents Diameter-level counters, +The <c>statistics</c> entry presents Diameter-level counters, an entry like <c>{{{0,280,1},recv},2}</c> saying that the client has received 2 DWR messages: <c>{0,280,1} = {Application_Id, Command_Code, R_Flag}</c>.</p> @@ -1733,7 +1967,7 @@ a service.</p> It is not an error to subscribe to events from a service that does not yet exist. Doing so before adding transports is required to guarantee the -reception of all related events.</p> +reception of all transport-related events.</p> </desc> </func> |