diff options
Diffstat (limited to 'lib/diameter/doc')
| -rw-r--r-- | lib/diameter/doc/src/Makefile | 4 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 216 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 4 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_codec.xml | 8 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 2 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_intro.xml | 4 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_make.xml | 94 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_sctp.xml | 2 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_soc_rfc6733.xml | 2 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameterc.xml (renamed from lib/diameter/doc/src/diameter_compile.xml) | 6 | ||||
| -rw-r--r-- | lib/diameter/doc/src/files.mk | 2 | ||||
| -rw-r--r-- | lib/diameter/doc/src/notes.xml | 72 | ||||
| -rw-r--r-- | lib/diameter/doc/src/ref_man.xml | 4 | ||||
| -rw-r--r-- | lib/diameter/doc/src/seealso.ent | 4 | ||||
| -rw-r--r-- | lib/diameter/doc/standard/rfc7068.txt | 1627 | ||||
| -rw-r--r-- | lib/diameter/doc/standard/rfc7075.txt | 563 |
16 files changed, 2477 insertions, 137 deletions
diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile index bd2b6b103a..229812fd08 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -82,6 +82,7 @@ gifs: $(GIF_FILES:%=$(HTMLDIR)/%) man: $(MAN1_FILES) $(MAN3_FILES) $(MAN4_FILES) $(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE) + $(gen_verbose) \ sed -e 's/%VSN%/$(VSN)/; \ s/%ERLANG_SITE%/www\.erlang\.se\//; \ s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \ @@ -140,7 +141,10 @@ release_spec: depend.mk: depend.sed Makefile seealso.ent \ $(XML_REF_FILES) $(XML_CHAPTER_FILES) + $(gen_verbose) + $(V_at) \ sed -f seehere.sed seealso.ent > seehere.ent + $(V_at) \ (for f in $(XML_REF_FILES) $(XML_CHAPTER_FILES); do \ sed -f $< $$f | sed "s@%FILE%@`basename $$f .xml`@g"; \ done) \ diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index db19fbb271..9864b21bc5 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -130,7 +130,7 @@ ExtraArgs = list() <p> A module implementing the callback interface defined in &man_app;, along with any -extra arguments to be appended to those documented for the interface. +extra arguments to be appended to those documented. Note that extra arguments specific to an outgoing request can be specified to &call;, in which case those are are appended to any module-specific extra arguments.</p> @@ -138,7 +138,7 @@ those are are appended to any module-specific extra arguments.</p> <p> Specifying a <c>#diameter_callback{}</c> record allows individual functions to be configured in place of the usual &man_app; callbacks. -See that module for details.</p> +See <c>diameter_callback.erl</c> for details.</p> <marker id="application_opt"/> </item> @@ -155,7 +155,7 @@ Has one the following types.</p> <tag><c>{alias, &application_alias;}</c></tag> <item> <p> -An unique identifier for the application in the scope of the +A unique identifier for the application in the scope of the service. Defaults to the value of the <c>dictionary</c> option if unspecified.</p> @@ -166,8 +166,8 @@ unspecified.</p> <p> The name of an encode/decode module for the Diameter messages defined by the application. -These modules are generated from a specification file whose format is -documented in &man_dict;.</p> +These modules are generated from files whose format is documented in +&man_dict;.</p> </item> <tag><c>{module, &application_module;}</c></tag> @@ -195,15 +195,14 @@ Specifies whether or not the &app_pick_peer; application callback can modify the application state. Defaults to <c>false</c> if unspecified.</p> -<note> +<warning> <p> -&app_pick_peer; callbacks -are serialized when these are allowed to modify state, which is a -potential performance bottleneck. +&app_pick_peer; callbacks are serialized when this option is <c>true</c>, +which is a potential performance bottleneck. A simple Diameter client may suffer no ill effects from using mutable state but a server or agent that responds to incoming request should probably avoid it.</p> -</note> +</warning> </item> <tag><c>{answer_errors, callback|report|discard}</c></tag> @@ -234,7 +233,7 @@ Defaults to <c>report</c> if unspecified.</p> <item> <p> Determines the manner in which incoming requests are handled when an -error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot +error other than 3007 (DIAMETER_APPLICATION_UNSUPPORTED, which cannot be associated with an application callback module), is detected.</p> <p> @@ -244,7 +243,8 @@ 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> +place and its return value determines the answer sent to the peer, if +any.</p> <p> Defaults to <c>answer_3xxx</c> if unspecified.</p> @@ -252,13 +252,14 @@ 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 +Since RFC 3588 allows 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 +<c>answer_3xxx</c> when the transport in question has +been configured with <c>diameter_gen_base_rfc3588</c> as its common +dictionary. +Since RFC 6733 allows both 3xxx and 5xxx result codes in an +<c>answer-message</c>, a transport with +<c>diameter_gen_base_rfc6733</c> as its common dictionary does distinguish between <c>answer_3xxx</c> and <c>answer</c>.</p> </note> </item> @@ -291,9 +292,8 @@ Multiple options append to the argument list.</p> <tag><c>{filter, &peer_filter;}</c></tag> <item> <p> -A filter to apply to the list of available peers before passing them to -the &app_pick_peer; -callback for the application in question. +A filter to apply to the list of available peers before passing it to +the &app_pick_peer; callback for the application in question. Multiple options are equivalent a single <c>all</c> filter on the corresponding list of filters. Defaults to <c>none</c>.</p> @@ -312,7 +312,7 @@ Defaults to 5000.</p> <p> Causes &call; to return <c>ok</c> as soon as the request in -question has been encoded instead of waiting for and returning +question has been encoded, instead of waiting for and returning the result from a subsequent &app_handle_answer; or &app_handle_error; callback.</p> </item> @@ -331,8 +331,8 @@ An invalid option will cause &call; to fail.</p> <p> AVP values sent in outgoing CER or CEA messages during capabilities exchange. -Can be configured both on a service and a transport, values specified -on the latter taking precedence over any specified on the former. +Can be configured both on a service and a transport, values +on the latter taking precedence. Has one of the following types.</p> <taglist> @@ -358,7 +358,7 @@ question communicates an address list as described in Origin-State-Id is optional but will be included in outgoing messages sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA. Setting a value of <c>0</c> (zero) is equivalent to not setting a -value as documented in &the_rfc;. +value, as documented in &the_rfc;. The function &origin_state_id; can be used as to retrieve a value that is computed when the diameter application is started.</p> @@ -370,8 +370,8 @@ application is started.</p> <item> <p> Inband-Security-Id defaults to the empty list, which is equivalent to a -list containing only 0 (= NO_INBAND_SECURITY). -If 1 (= TLS) is specified then TLS is selected if the CER/CEA received +list containing only 0 (NO_INBAND_SECURITY). +If 1 (TLS) is specified then TLS is selected if the CER/CEA received from the peer offers it.</p> </item> @@ -437,38 +437,38 @@ Has one of the following types.</p> <p> Matches any peer. This is a convenience that provides a filter equivalent to no -filter at all.</p> +filter.</p> </item> <tag><c>host</c></tag> <item> <p> -Matches only those peers whose <c>Origin-Host</c> has the same value -as <c>Destination-Host</c> in the outgoing request in question, +Matches only those peers whose Origin-Host has the same value +as Destination-Host in the outgoing request in question, or any peer if the request does not contain -a <c>Destination-Host</c> AVP.</p> +a Destination-Host AVP.</p> </item> <tag><c>realm</c></tag> <item> <p> -Matches only those peers whose <c>Origin-Realm</c> has the same value -as <c>Destination-Realm</c> in the outgoing request in question, +Matches only those peers whose Origin-Realm has the same value +as Destination-Realm in the outgoing request in question, or any peer if the request does not contain -a <c>Destination-Realm</c> AVP.</p> +a Destination-Realm AVP.</p> </item> <tag><c>{host, any|&dict_DiameterIdentity;}</c></tag> <item> <p> -Matches only those peers whose <c>Origin-Host</c> has the +Matches only those peers whose Origin-Host has the specified value, or all peers if the atom <c>any</c>.</p> </item> <tag><c>{realm, any|&dict_DiameterIdentity;</c></tag> <item> <p> -Matches only those peers whose <c>Origin-Realm</c> has the +Matches only those peers whose Origin-Realm has the specified value, or all peers if the atom <c>any</c>.</p> </item> @@ -477,7 +477,8 @@ specified value, or all peers if the atom <c>any</c>.</p> <p> Matches only those peers for which the specified <c>&evaluable;</c> returns -<c>true</c> on the connection's <c>diameter_caps</c> record. +<c>true</c> when applied to the connection's <c>diameter_caps</c> +record. Any other return value or exception is equivalent to <c>false</c>.</p> </item> @@ -508,10 +509,10 @@ that matches no peer.</p> <note> <p> -The <c>host</c> and <c>realm</c> filters examine the -outgoing request as passed to &call;, -assuming that this is a record- or list-valued <c>&codec_message;</c>, -and that the message contains at most one of each AVP. +The <c>host</c> and <c>realm</c> filters cause the Destination-Host +and Destination-Realm AVPs to be extracted from the +outgoing request, assuming it to be a record- or list-valued +<c>&codec_message;</c>, and assuming at most one of each AVP. If this is not the case then the <c>{host|realm, &dict_DiameterIdentity;}</c> filters must be used to achieve the desired result. An empty <c>&dict_DiameterIdentity;</c> @@ -555,7 +556,7 @@ Can have one of the following types.</p> <p> The service is being started or stopped. No event precedes a <c>start</c> event. -No event follows a <c>stop</c> event and this event +No event follows a <c>stop</c> event, and this event implies the termination of all transport processes.</p> </item> @@ -575,16 +576,15 @@ 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> 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> +then there has been a capabilities exchange on a newly established +transport connection and the record contains the received CER or +CEA.</p> <p> 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. +capabilities exchange. That is, the event communicates connectivity with the peer as a whole while the callbacks communicate connectivity with respect to individual Diameter applications.</p> @@ -599,7 +599,7 @@ Opts = [&transport_opt;] <p> A connecting transport is attempting to establish/reestablish a -transport connection with a peer following &reconnect_timer; or +transport connection with a peer following &connect_timer; or &watchdog_timer; expiry.</p> </item> @@ -627,10 +627,10 @@ CB = &evaluable; </pre> <p> -An incoming CER has been answered with the indicated result code or +An incoming CER has been answered with the indicated result code, or discarded. -<c>Caps</c> contains pairs of values for the local node and remote -peer. +<c>Caps</c> contains pairs of values, for the local node and remote +peer respectively. <c>Pkt</c> contains the CER in question. In the case of rejection by a capabilities callback, the tuple contains the rejecting callback.</p> @@ -647,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 local node. +<c>Caps</c> contains values for the local node only. <c>Pkt</c> contains the CER in question.</p> </item> @@ -754,7 +754,7 @@ Defines a Diameter application supported by the service.</p> <p> A service must configure one tuple for each Diameter application it intends to support. -For an outgoing Diameter request, the relevant <c>&application_alias;</c> is +For an outgoing request, the relevant <c>&application_alias;</c> is passed to &call;, while for an incoming request the application identifier in the message header determines the application, the identifier being specified in @@ -765,7 +765,7 @@ the application's &dictionary; file.</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> +*-Application-Id AVPs in particular.</p> </warning> </item> @@ -778,10 +778,11 @@ Application-Id AVP's in particular.</p> <item> <p> Specifies the degree to which the service allows multiple transport -connections to the same peer.</p> +connections to the same peer, as identified by its Origin-Host +at capabilities exchange.</p> <p> -If type <c>[node()]</c> then a connection is rejected if another already +If <c>[node()]</c> then a connection is rejected if another already exists on any of the specified nodes. Types <c>false</c>, <c>node</c>, <c>nodes</c> and &evaluable; are equivalent to @@ -803,8 +804,8 @@ Defaults to <c>nodes</c>.</p> <item> <p> Specifies a constant value <c>H</c> for the topmost <c>32-N</c> bits of -of 32-bit End-to-End and Hop-by-Hop identifiers generated -by the service, either explicity or as a return value of a function +of 32-bit End-to-End and Hop-by-Hop Identifiers generated +by the service, either explicitly or as a return value of a function to be evaluated at &start_service;. In particular, an identifier <c>Id</c> is mapped to a new identifier as follows.</p> @@ -812,11 +813,11 @@ as follows.</p> (H bsl N) bor (Id band ((1 bsl N) - 1)) </pre> <p> -Note that &the_rfc; requires that End-to-End identifiers remain unique +Note that &the_rfc; requires that End-to-End Identifiers remain unique for a period of at least 4 minutes and that this and the call rate -places a lower bound on the appropriate values of <c>N</c>: -at a rate of <c>R</c> requests per second an <c>N</c>-bit counter -traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes so +places a lower bound on appropriate values of <c>N</c>: +at a rate of <c>R</c> requests per second, an <c>N</c>-bit counter +traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes, so the bound is <c>4*R*60 =< 1 bsl N</c>.</p> <p><c>N</c> must lie in the range <c>0..32</c> and <c>H</c> must be a @@ -829,7 +830,7 @@ Defaults to <c>{0,32}</c>.</p> <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 +uses a unique range of End-to-End and Hop-by-Hop Identifiers for outgoing requests.</p> </warning> </item> @@ -852,7 +853,7 @@ 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 +The value <c>node()</c> in a list is ignored, so a collection of services can all be configured to share with the same list of nodes.</p> @@ -899,7 +900,7 @@ 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> +The value <c>node()</c> in a list is ignored.</p> <p> Defaults to <c>false</c>.</p> @@ -946,7 +947,7 @@ Applications not configured on the service in question are ignored.</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 +implies having to set matching *-Application-Id AVPs in a &capabilities; tuple.</p> </warning> @@ -956,7 +957,7 @@ implies having to set matching Application-Id AVP's in a <tag><c>{capabilities, [&capability;]}</c></tag> <item> <p> -AVP's used to construct outgoing CER/CEA messages. +AVPs used to construct outgoing CER/CEA messages. Values take precedence over any specified on the service in question.</p> @@ -1021,14 +1022,45 @@ 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 of reconnection attempts is -governed by &watchdog_timer; or &reconnect_timer; expiry. +For a connecting transport, the timing of connection attempts is +governed by &connect_timer; or &watchdog_timer; expiry. For a listening transport, the peer determines the timing.</p> <p> Defaults to 10000.</p> </item> +<marker id="connect_timer"/> +<tag><c>{connect_timer, Tc}</c></tag> +<item> +<pre> +Tc = &dict_Unsigned32; +</pre> + +<p> +For a connecting transport, the &the_rfc; Tc timer, in milliseconds. +This timer determines the frequency with which a transport +attempts to establish an initial connection with its peer +following transport configuration. +Once an initial connection has been +established, &watchdog_timer; determines the frequency of +reconnection attempts, as required by RFC 3539.</p> + +<p> +For a listening transport, the timer specifies the time after which a +previously connected peer will be forgotten: a connection after this time is +regarded as an initial connection rather than reestablishment, +causing the RFC 3539 state machine to pass to state OKAY rather than +REOPEN. +Note that these semantics are not governed by the RFC and +that a listening transport's &connect_timer; should be greater +than its peer's Tw plus jitter.</p> + +<p> +Defaults to 30000 for a connecting transport and 60000 for a listening +transport.</p> +</item> + <marker id="disconnect_cb"/> <tag><c>{disconnect_cb, &evaluable;}</c></tag> @@ -1036,14 +1068,12 @@ Defaults to 10000.</p> <p> A callback invoked prior to terminating the transport process of a 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 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;, -respectively.</p> +Applied to <c>application|service|transport</c> and the +<c>&transport_ref;</c> and <c>&app_peer;</c> in question: +<c>application</c> indicates that the diameter application is +being stopped, <c>service</c> that the service in question is being +stopped by &stop_service;, and <c>transport</c> that the transport in +question is being removed by &remove_transport;.</p> <p> The return value can have one of the following types.</p> @@ -1145,36 +1175,6 @@ See &man_tcp; for the behaviour of that module.</p> </note> </item> -<marker id="reconnect_timer"/> -<tag><c>{reconnect_timer, Tc}</c></tag> -<item> -<pre> -Tc = &dict_Unsigned32; -</pre> - -<p> -For a connecting transport, the &the_rfc; Tc timer, in milliseconds. -Note that this timer determines the frequency with which a transport -will attempt to establish a connection with its peer only <em>before</em> -an initial connection is established: once there is an initial -connection it's &watchdog_timer; that determines the -frequency of reconnection attempts, as required by RFC 3539.</p> - -<p> -For a listening transport, the timer specifies the time after which a -previously connected peer will be forgotten: a connection after this time is -regarded as an initial connection rather than a reestablishment, -causing the RFC 3539 state machine to pass to state OKAY rather than -REOPEN. -Note that these semantics are not governed by the RFC and -that a listening transport's &reconnect_timer; should be greater -than its peer's Tw plus jitter.</p> - -<p> -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> @@ -1661,7 +1661,7 @@ R_Flag}</c>.</p> Note that <c>watchdog</c>, <c>peer</c>, <c>apps</c>, <c>caps</c> and <c>port</c> entries depend on connectivity with the peer and may not be present. -Note also that the <c>statistics</c> entry presents values acuumulated +Note also that the <c>statistics</c> entry presents values accumulated during the lifetime of the transport configuration.</p> <p> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index e6c9cc9a90..0b6839dcb2 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -308,7 +308,7 @@ The return value <c>{Peer, NewState}</c> is only allowed if the Diameter application in question was configured with the &mod_application_opt; <c>{call_mutates_state, true}</c>. Otherwise, the <c>State</c> argument is always -the intial value as configured on the application, not any subsequent +the initial value as configured on the application, not any subsequent value returned by a &peer_up; or &peer_down; callback.</p> </warning> @@ -565,7 +565,7 @@ Equivalent to</p> </pre> <p> where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified -Result-Code and (if the request contained one) Session-Id AVP's, and +Result-Code and (if the request contained one) Session-Id AVPs, and possibly Failed-AVP as described below.</p> <p> diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml index 4a77d5435b..9d26466b25 100644 --- a/lib/diameter/doc/src/diameter_codec.xml +++ b/lib/diameter/doc/src/diameter_codec.xml @@ -13,7 +13,7 @@ <erlref> <header> <copyright> -<year>2012</year> +<year>2012</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -73,7 +73,7 @@ are defined in diameter.hrl, which can be included as follows.</p> </pre> <p> -Application-specific records are definied in the hrl +Application-specific records are defined in the hrl files resulting from dictionary file compilation.</p> </description> @@ -122,7 +122,7 @@ Fields have the following types.</p> <item> <p> Values in the AVP header, corresponding to AVP Code, the M flag, P -flags and Vendor-ID respectivelty. +flags and Vendor-ID respectively. A Vendor-ID other than <c>undefined</c> implies a set V flag.</p> </item> @@ -222,7 +222,7 @@ header.</p> <tag><c>is_retransmitted = boolean()</c></tag> <item> <p> -Values correspoding to the R(equest), P(roxiable), E(rror) +Values corresponding to the R(equest), P(roxiable), E(rror) and T(Potentially re-transmitted message) flags of the Diameter header.</p> </item> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 8bf4a14240..4f51a12ebc 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -431,7 +431,7 @@ equivalent to specifying it with <c>@avp_vendor_id</c>.</p> Defines values of AVP Name having type Enumerated. Section content consists of names and corresponding integer values. Integer values can be prefixed with 0x to be interpreted as -hexidecimal.</p> +hexadecimal.</p> <p> Note that the AVP in question can be defined in an inherited diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml index 288ebc0c7c..6c1d1910d2 100644 --- a/lib/diameter/doc/src/diameter_intro.xml +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -40,7 +40,7 @@ under the License. The diameter application is an implementation of the Diameter protocol as defined by &the_rfc;. It supports arbitrary Diameter applications by way of a -<em>dictionary</em> interface that allows messages and AVP's to be +<em>dictionary</em> interface that allows messages and AVPs to be defined and input into diameter as configuration. It has support for all roles defined in the RFC: client, server and agent. @@ -69,7 +69,7 @@ interface</seealso>.</p> <p> While a service typically implements a single Diameter node (as identified by an Origin-Host AVP), transports can themselves be -associated with capabilities AVP's so that a single service can be +associated with capabilities AVPs so that a single service can be used to implement more than one Diameter node.</p> <p> diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml index ec71251be1..1c1eff6c6a 100644 --- a/lib/diameter/doc/src/diameter_make.xml +++ b/lib/diameter/doc/src/diameter_make.xml @@ -1,5 +1,7 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY compile_forms2 + '<seealso marker="compiler:compile#forms-2">compile:forms/2</seealso>'> <!ENTITY filename '<seealso marker="kernel:file#type-name">file:name()</seealso>'> <!ENTITY dictionary @@ -51,7 +53,7 @@ under the License. The function &codec; is used to compile a diameter &dictionary; into Erlang source. The resulting source implements the interface diameter required -to encode and decode the dictionary's messages and AVP's.</p> +to encode and decode the dictionary's messages and AVPs.</p> <p> The utility &man_compile; provides an alternate compilation @@ -64,16 +66,47 @@ interface.</p> <funcs> <func> -<name>codec(Path::string(), [Opt]) -> ok | {error, Reason}</name> +<name>codec(File :: iolist() | binary(), [Opt]) -> ok + | {ok, [Out]} + | {error, Reason}</name> <fsummary>Compile a dictionary file into Erlang source.</fsummary> <desc> <p> -Compile a single dictionary file to Erlang source. -<c>Opt</c> can have the following types.</p> +Compile a single dictionary file. +The input <c>File</c> can be either a path or a literal dictionary, +the occurrence of newline (ascii NL) or carriage return (ascii CR) +identifying the latter. +<c>Opt</c> determines the format of the results and whether they are +written to file or returned, and can have the following types.</p> <taglist> +<tag><c>parse | forms | erl | hrl</c></tag> +<item> +<p> +Specifies an output format. +Whether the output is returned or written to file depends on whether +or not option <c>return</c> is specified. +When written to file, the resulting file(s) will have extensions +<c>.D</c>, <c>.F</c>, <c>.erl</c>, and <c>.hrl</c> +respectively, basenames defaulting to <c>dictionary</c> if the input +dictionary is literal and does not specify <c>&dict_name;</c>. +When returned, results are in the order of the corresponding format +options. +Format options default to <c>erl</c> and <c>hrl</c> (in this order) if +unspecified.</p> + +<p> +The <c>parse</c> format is an internal representation that can be +passed to &flatten; and &format;, while the <c>forms</c> format can be +passed to &compile_forms2;. +The <c>erl</c> and <c>hrl</c> formats are returned as +iolists.</p> +<!-- That codec/2 can take the parsed format is undocumented, and + options name and inherits have no effect in this case. --> +</item> + <tag><c>{include, string()}</c></tag> <item> <p> @@ -90,7 +123,15 @@ Multiple <c>include</c> options can be specified.</p> <item> <p> Write generated source to the specified directory. -Defaults to the current working directory.</p> +Defaults to the current working directory. +Has no effect if option <c>return</c> is specified.</p> +</item> + +<tag><c>return</c></tag> +<item> +<p> +Return results in a <c>{ok, [Out]}</c> tuple instead of writing to +file and returning <c>ok</c>.</p> </item> <tag><c>{name|prefix, string()}</c></tag> @@ -108,7 +149,7 @@ Transform the input dictionary before compilation, appending <c>&dict_inherits;</c> of the specified string.</p> <p> -Two forms of <c>@inherits</c> have special meaning:</p> +Two forms have special meaning:</p> <pre> {inherits, "-"} @@ -127,6 +168,41 @@ Multiple <c>inherits</c> options can be specified.</p> </taglist> +<p> +Note that a dictionary's <c>&dict_name;</c>, together with the +<c>outdir</c> option, determine the output paths when the +<c>return</c> option is not specified. +The <c>&dict_name;</c> of a literal input dictionary defaults to +<c>dictionary</c>.</p> + +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>format(Parsed) -> iolist()</name> +<fsummary>Format a parsed dictionary.</fsummary> +<desc> +<p> +Turns a parsed dictionary, as returned by &codec;, back into the +dictionary format.</p> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>flatten(Parsed) -> term()</name> +<fsummary>Flatten a parsed dictionary.</fsummary> +<desc> + +<p> +Reconstitute a parsed dictionary, as returned by &codec;, without +using <c>&dict_inherits;</c>. +That is, construct an equivalent dictionary in which all AVP's are +definined in the dictionary itself. +The return value is also a parsed dictionary.</p> </desc> </func> @@ -138,11 +214,7 @@ Multiple <c>inherits</c> options can be specified.</p> <title>BUGS</title> <p> -All options are string-valued. -In particular, it is not currently possible to specify -an &dict_inherits; module as an atom(), or a path as an arbitrary -&filename;</p> - +Unrecognized options are silently ignored.</p> </section> <!-- ===================================================================== --> diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml index 5fe14b1ef6..2be77e3dfd 100644 --- a/lib/diameter/doc/src/diameter_sctp.xml +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -90,7 +90,7 @@ 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. -Mupltiple <c>raddr</c> options can be specified, in which case the +Multiple <c>raddr</c> options can be specified, in which case the connecting transport in question attempts each in sequence until an association is established.</p> diff --git a/lib/diameter/doc/src/diameter_soc_rfc6733.xml b/lib/diameter/doc/src/diameter_soc_rfc6733.xml index 8d85569650..deb4d05b0f 100644 --- a/lib/diameter/doc/src/diameter_soc_rfc6733.xml +++ b/lib/diameter/doc/src/diameter_soc_rfc6733.xml @@ -1272,7 +1272,7 @@ during capabilities exchange.)</p> <p> The frequency of reconnection attempts is configured with the -&mod_transport_opt; <c>reconnect_timer</c> and +&mod_transport_opt; <c>connect_timer</c> and <c>watchdog_timer</c>.</p> <pre> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameterc.xml index 6630019e5c..039f4f9cdd 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameterc.xml @@ -29,7 +29,7 @@ supplied. <docno></docno> <date></date> <rev></rev> -<file>diameter_compile.xml</file> +<file>diameterc.xml</file> </header> <com>diameterc</com> @@ -41,7 +41,7 @@ supplied. The diameterc utility is used to compile a diameter &dictionary; into Erlang source. The resulting source implements the interface diameter required -to encode and decode the dictionary's messages and AVP's.</p> +to encode and decode the dictionary's messages and AVPs.</p> <p> The module &man_make; provides an alternate compilation interface.</p> @@ -83,7 +83,7 @@ Defaults to the current working directory.</p> <tag><![CDATA[-H]]></tag> <item> <p> -Supress erl and hrl generation, respectively.</p> +Suppress erl and hrl generation, respectively.</p> </item> <tag><![CDATA[--name <name>]]></tag> diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk index 510786a7fb..6e8b1f9068 100644 --- a/lib/diameter/doc/src/files.mk +++ b/lib/diameter/doc/src/files.mk @@ -21,7 +21,7 @@ XML_APPLICATION_FILES = \ ref_man.xml XML_REF1_FILES = \ - diameter_compile.xml + diameterc.xml XML_REF3_FILES = \ diameter.xml \ diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index 32082e565d..18c712ec3d 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -42,6 +42,78 @@ first.</p> <!-- ===================================================================== --> +<section><title>diameter 1.5</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Rename reconnect_timer to connect_timer.</p> + <p> + The former is still accepted for backwards compatibility, + but the name is misleading given the semantics of the + timer.</p> + <p> + Own Id: OTP-11168</p> + </item> + <item> + <p> + Extend diameter_make(3).</p> + <p> + Dictionaries can now be compiled from strings, not just + filesystem paths, and results can be returned instead of + written to the filesystem.</p> + <p> + Own Id: OTP-11348</p> + </item> + <item> + <p> + Remove hardcoding of diameter_base as @prefix on + dictionaries for application id 0.</p> + <p> + Own Id: OTP-11361</p> + </item> + <item> + <p> + Fix silent make rules (Thanks to Anthony Ramine)</p> + <p> + Own Id: OTP-11514</p> + </item> + </list> + </section> + +</section> + +<section><title>diameter 1.4.4</title> + + <section><title>Known Bugs and Problems</title> + <list> + <item> + <p> + Fix setting of End-to-End and Hop-by-Hop Identifiers in + outgoing DWA.</p> + <p> + Broken by OTP-11184, which caused the identifiers to be + set anew, discarding the values from the incoming DWR.</p> + <p> + Own Id: OTP-11367</p> + </item> + <item> + <p> + Fix handling of 5014, DIAMETER_INVALID_AVP_LENGTH.</p> + <p> + The error was detected as 5004, + DIAMETER_INVALID_AVP_VALUE, for some Diameter types, in + which case an AVP length that pointed past the end of a + message resulted in encode failure.</p> + <p> + Own Id: OTP-11395</p> + </item> + </list> + </section> + +</section> + <section><title>diameter 1.4.3</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml index 4b99fe716d..1095887144 100644 --- a/lib/diameter/doc/src/ref_man.xml +++ b/lib/diameter/doc/src/ref_man.xml @@ -6,7 +6,7 @@ <header> <copyright> <year>2011</year> -<year>2012</year> +<year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -39,7 +39,7 @@ applications on top of the Diameter protocol. </p> </description> <xi:include href="diameter.xml"/> -<xi:include href="diameter_compile.xml"/> +<xi:include href="diameterc.xml"/> <xi:include href="diameter_app.xml"/> <xi:include href="diameter_codec.xml"/> <xi:include href="diameter_dict.xml"/> diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent index 76b9823f79..7bf7460351 100644 --- a/lib/diameter/doc/src/seealso.ent +++ b/lib/diameter/doc/src/seealso.ent @@ -66,7 +66,7 @@ significant. <!ENTITY disconnect_cb '<seealso marker="#disconnect_cb">disconnect_cb</seealso>'> <!ENTITY transport_config '<seealso marker="#transport_config">transport_config</seealso>'> <!ENTITY transport_module '<seealso marker="#transport_module">transport_module</seealso>'> -<!ENTITY reconnect_timer '<seealso marker="#reconnect_timer">reconnect_timer</seealso>'> +<!ENTITY connect_timer '<seealso marker="#connect_timer">connect_timer</seealso>'> <!ENTITY watchdog_timer '<seealso marker="#watchdog_timer">watchdog_timer</seealso>'> <!-- diameter_app --> @@ -115,6 +115,8 @@ significant. <!-- diameter_make --> <!ENTITY make_codec '<seealso marker="diameter_make#codec-2">diameter_make:codec/2</seealso>'> +<!ENTITY make_format '<seealso marker="diameter_make#format-1">diameter_make:format/1</seealso>'> +<!ENTITY make_flatten '<seealso marker="diameter_make#flatten-1">diameter_make:flatten/1</seealso>'> <!-- diameter_transport --> diff --git a/lib/diameter/doc/standard/rfc7068.txt b/lib/diameter/doc/standard/rfc7068.txt new file mode 100644 index 0000000000..70fc24fab0 --- /dev/null +++ b/lib/diameter/doc/standard/rfc7068.txt @@ -0,0 +1,1627 @@ + + + + + + +Internet Engineering Task Force (IETF) E. McMurry +Request for Comments: 7068 B. Campbell +Category: Informational Oracle +ISSN: 2070-1721 November 2013 + + + Diameter Overload Control Requirements + +Abstract + + When a Diameter server or agent becomes overloaded, it needs to be + able to gracefully reduce its load, typically by advising clients to + reduce traffic for some period of time. Otherwise, it must continue + to expend resources parsing and responding to Diameter messages, + possibly resulting in a progressively severe overload condition. The + existing Diameter mechanisms are not sufficient for managing overload + conditions. This document describes the limitations of the existing + mechanisms. Requirements for new overload management mechanisms are + also provided. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Not all documents + approved by the IESG are a candidate for any level of Internet + Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7068. + + + + + + + + + + + + + + + + +McMurry & Campbell Informational [Page 1] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +Copyright Notice + + Copyright (c) 2013 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +McMurry & Campbell Informational [Page 2] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +Table of Contents + + 1. Introduction ....................................................4 + 1.1. Documentation Conventions ..................................4 + 1.2. Causes of Overload .........................................5 + 1.3. Effects of Overload ........................................6 + 1.4. Overload vs. Network Congestion ............................6 + 1.5. Diameter Applications in a Broader Network .................7 + 2. Overload Control Scenarios ......................................7 + 2.1. Peer-to-Peer Scenarios .....................................8 + 2.2. Agent Scenarios ...........................................10 + 2.3. Interconnect Scenario .....................................14 + 3. Diameter Overload Case Studies .................................15 + 3.1. Overload in Mobile Data Networks ..........................15 + 3.2. 3GPP Study on Core Network Overload .......................16 + 4. Existing Mechanisms ............................................17 + 5. Issues with the Current Mechanisms .............................18 + 5.1. Problems with Implicit Mechanism ..........................18 + 5.2. Problems with Explicit Mechanisms .........................18 + 6. Extensibility and Application Independence .....................19 + 7. Solution Requirements ..........................................20 + 7.1. General ...................................................20 + 7.2. Performance ...............................................21 + 7.3. Heterogeneous Support for Solution ........................22 + 7.4. Granular Control ..........................................23 + 7.5. Priority and Policy .......................................23 + 7.6. Security ..................................................23 + 7.7. Flexibility and Extensibility .............................24 + 8. Security Considerations ........................................25 + 8.1. Access Control ............................................25 + 8.2. Denial-of-Service Attacks .................................26 + 8.3. Replay Attacks ............................................26 + 8.4. Man-in-the-Middle Attacks .................................26 + 8.5. Compromised Hosts .........................................27 + 9. References .....................................................27 + 9.1. Normative References ......................................27 + 9.2. Informative References ....................................27 + Appendix A. Contributors ..........................................29 + Appendix B. Acknowledgements ......................................29 + + + + + + + + + + + + +McMurry & Campbell Informational [Page 3] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +1. Introduction + + A Diameter [RFC6733] node is said to be overloaded when it has + insufficient resources to successfully process all of the Diameter + requests that it receives. When a node becomes overloaded, it needs + to be able to gracefully reduce its load, typically by advising + clients to reduce traffic for some period of time. Otherwise, it + must continue to expend resources parsing and responding to Diameter + messages, possibly resulting in a progressively severe overload + condition. The existing mechanisms provided by Diameter are not + sufficient for managing overload conditions. This document describes + the limitations of the existing mechanisms and provides requirements + for new overload management mechanisms. + + This document draws on the work done on SIP overload control + ([RFC5390], [RFC6357]) as well as on experience gained via overload + handling in Signaling System No. 7 (SS7) networks and studies done by + the Third Generation Partnership Project (3GPP) (Section 3). + + Diameter is not typically an end-user protocol; rather, it is + generally used as one component in support of some end-user activity. + + For example, a SIP server might use Diameter to authenticate and + authorize user access. Overload in the Diameter backend + infrastructure will likely impact the experience observed by the end + user in the SIP application. + + The impact of Diameter overload on the client application (a client + application may use the Diameter protocol and other protocols to do + its job) is beyond the scope of this document. + + This document presents non-normative descriptions of causes of + overload, along with related scenarios and studies. Finally, it + offers a set of normative requirements for an improved overload + indication mechanism. + +1.1. Documentation Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as defined in [RFC2119], with the + exception that they are not intended for interoperability of + implementations. Rather, they are used to describe requirements + towards future specifications where the interoperability requirements + will be defined. + + The terms "client", "server", "agent", "node", "peer", "upstream", + and "downstream" are used as defined in [RFC6733]. + + + +McMurry & Campbell Informational [Page 4] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +1.2. Causes of Overload + + Overload occurs when an element, such as a Diameter server or agent, + has insufficient resources to successfully process all of the traffic + it is receiving. Resources include all of the capabilities of the + element used to process a request, including CPU processing, memory, + I/O, and disk resources. It can also include external resources such + as a database or DNS server, in which case the CPU, processing, + memory, I/O, and disk resources of those elements are effectively + part of the logical element processing the request. + + External resources can include upstream Diameter nodes; for example, + a Diameter agent can become effectively overloaded if one or more + upstream nodes are overloaded. + + A Diameter node can become overloaded due to request levels that + exceed its capacity, a reduction of available resources (for example, + a local or upstream hardware failure), or a combination of the two. + + Overload can occur for many reasons, including: + + Inadequate capacity: When designing Diameter networks, that is, + application-layer multi-node Diameter deployments, it can be very + difficult to predict all scenarios that may cause elevated + traffic. It may also be more costly to implement support for some + scenarios than a network operator may deem worthwhile. This + results in the likelihood that a Diameter network will not have + adequate capacity to handle all situations. + + Dependency failures: A Diameter node can become overloaded because a + resource on which it depends has failed or become overloaded, + greatly reducing the logical capacity of the node. In these + cases, even minimal traffic might cause the node to go into + overload. Examples of such dependency overloads include DNS + servers, databases, disks, and network interfaces that have failed + or become overloaded. + + Component failures: A Diameter node can become overloaded when it is + a member of a cluster of servers that each share the load of + traffic and one or more of the other members in the cluster fail. + In this case, the remaining nodes take over the work of the failed + nodes. Normally, capacity planning takes such failures into + account, and servers are typically run with enough spare capacity + to handle failure of another node. However, unusual failure + conditions can cause many nodes to fail at once. This is often + the case with software failures, where a bad packet or bad + database entry hits the same bug in a set of nodes in a cluster. + + + + +McMurry & Campbell Informational [Page 5] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Network-initiated traffic flood: Certain access network events can + precipitate floods of Diameter signaling traffic. For example, + operational changes can trigger avalanche restarts, or frequent + radio overlay handovers can generate excessive authorization + requests. Failure of a Diameter proxy may also result in a large + amount of signaling as connections and sessions are reestablished. + + Subscriber-initiated traffic flood: Large gatherings of subscribers + or events that result in many subscribers interacting with the + network in close time proximity can result in Diameter signaling + traffic floods. For example, the finale of a large fireworks show + could be immediately followed by many subscribers posting + messages, pictures, and videos concentrated on one portion of a + network. Subscriber devices such as smartphones may use + aggressive registration strategies that generate unusually high + Diameter traffic loads. + + DoS attacks: An attacker wishing to disrupt service in the network + can cause a large amount of traffic to be launched at a target + element. This can be done from a central source of traffic or + through a distributed DoS attack. In all cases, the volume of + traffic well exceeds the capacity of the element, sending the + system into overload. + +1.3. Effects of Overload + + Modern Diameter networks, composed of application-layer multi-node + deployments of Diameter elements, may operate at very large + transaction volumes. If a Diameter node becomes overloaded or, even + worse, fails completely, a large number of messages may be lost very + quickly. Even with redundant servers, many messages can be lost in + the time it takes for failover to complete. While a Diameter client + or agent should be able to retry such requests, an overloaded peer + may cause a sudden large increase in the number of transactions + needing to be retried, rapidly filling local queues or otherwise + contributing to local overload. Therefore, Diameter devices need to + be able to shed load before critical failures can occur. + +1.4. Overload vs. Network Congestion + + This document uses the term "overload" to refer to application-layer + overload at Diameter nodes. This is distinct from "network + congestion", that is, congestion that occurs at the lower networking + layers that may impact the delivery of Diameter messages between + nodes. This document recognizes that element overload and network + congestion are interrelated, and that overload can contribute to + network congestion and vice versa. + + + + +McMurry & Campbell Informational [Page 6] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Network congestion issues are better handled by the transport + protocols. Diameter uses TCP and the Stream Control Transmission + Protocol (SCTP), both of which include congestion management + features. Analysis of whether those features are sufficient for + transport-level congestion between Diameter nodes and of any work to + further mitigate network congestion is out of scope for both this + document and the work proposed by it. + +1.5. Diameter Applications in a Broader Network + + Most elements using Diameter applications do not use Diameter + exclusively. It is important to realize that overload of an element + can be caused by a number of factors that may be unrelated to the + processing of Diameter or Diameter applications. + + An element that doesn't use Diameter exclusively needs to be able to + signal to Diameter peers that it is experiencing overload regardless + of the cause of the overload, since the overload will affect that + element's ability to process Diameter transactions. If the element + communicates with protocols other than Diameter, it may also need to + signal the overload situation on these protocols, depending on its + function and the architecture of the network and application for + which it is providing services. Whether that is necessary can only + be decided within the context of that architecture and use cases. + This specification details the requirements for a mechanism for + signaling overload with Diameter; this mechanism provides Diameter + nodes the ability to inform their Diameter peers of overload, + mitigating that part of the issue. Diameter nodes may need to use + this, as well as other mechanisms, to solve their broader overload + issues. Indicating overload on protocols other than Diameter is out + of scope for this document and for the work proposed by it. + +2. Overload Control Scenarios + + Several Diameter deployment scenarios exist that may impact overload + management. The following scenarios help motivate the requirements + for an overload management mechanism. + + These scenarios are by no means exhaustive and are in general + simplified for the sake of clarity. In particular, this document + assumes for the sake of clarity that the client sends Diameter + requests to the server, and the server sends responses to the client, + even though Diameter supports bidirectional applications. Each + direction in such an application can be modeled separately. + + In a large-scale deployment, many of the nodes represented in these + scenarios would be deployed as clusters of servers. This document + assumes that such a cluster is responsible for managing its own + + + +McMurry & Campbell Informational [Page 7] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + internal load-balancing and overload management so that it appears as + a single Diameter node. That is, other Diameter nodes can treat it + as a single, monolithic node for the purposes of overload management. + + These scenarios do not illustrate the client application. As + mentioned in Section 1, Diameter is not typically an end-user + protocol; rather, it is generally used in support of some other + client application. These scenarios do not consider the impact of + Diameter overload on the client application. + +2.1. Peer-to-Peer Scenarios + + This section describes Diameter peer-to-peer scenarios, that is, + scenarios where a Diameter client talks directly with a Diameter + server, without the use of a Diameter agent. + + Figure 1 illustrates the simplest possible Diameter relationship. + The client and server share a one-to-one peer-to-peer relationship. + If the server becomes overloaded, either because the client exceeds + the server's capacity or because the server's capacity is reduced due + to some resource dependency, the client needs to reduce the amount of + Diameter traffic it sends to the server. Since the client cannot + forward requests to another server, it must either queue requests + until the server recovers or itself become overloaded in the context + of the client application and other protocols it may also use. + + +------------------+ + | | + | | + | Server | + | | + +--------+---------+ + | + | + +--------+---------+ + | | + | | + | Client | + | | + +------------------+ + + Figure 1: Basic Peer-to-Peer Scenario + + + + + + + + + +McMurry & Campbell Informational [Page 8] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Figure 2 shows a similar scenario, except in this case the client has + multiple servers that can handle work for a specific realm and + application. If Server 1 becomes overloaded, the client can forward + traffic to Server 2. Assuming that Server 2 has sufficient reserve + capacity to handle the forwarded traffic, the client should be able + to continue serving client application protocol users. If Server 1 + is approaching overload, but can still handle some number of new + requests, it needs to be able to instruct the client to forward a + subset of its traffic to Server 2. + + +------------------+ +------------------+ + | | | | + | | | | + | Server 1 | | Server 2 | + | | | | + +--------+-`.------+ +------.'+---------+ + `. .' + `. .' + `. .' + `. .' + +-------`.'--------+ + | | + | | + | Client | + | | + +------------------+ + + Figure 2: Multiple-Server Peer-to-Peer Scenario + + Figure 3 illustrates a peer-to-peer scenario with multiple Diameter + realm and application combinations. In this example, Server 2 can + handle work for both applications. Each application might have + different resource dependencies. For example, a server might need to + access one database for Application A and another for Application B. + This creates a possibility that Server 2 could become overloaded for + Application A but not for Application B, in which case the client + would need to divert some part of its Application A requests to + Server 1, but the client should not divert any Application B + requests. This requires that Server 2 be able to distinguish between + applications when it indicates an overload condition to the client. + + On the other hand, it's possible that the servers host many + applications. If Server 2 becomes overloaded for all applications, + it would be undesirable for it to have to notify the client + separately for each application. Therefore, it also needs a way to + indicate that it is overloaded for all possible applications. + + + + + +McMurry & Campbell Informational [Page 9] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + +---------------------------------------------+ + | Application A +----------------------+----------------------+ + |+------------------+ | +----------------+ | +------------------+| + || | | | | | | || + || | | | | | | || + || Server 1 | | | Server 2 | | | Server 3 || + || | | | | | | || + |+--------+---------+ | +-------+--------+ | +-+----------------+| + | | | | | | | + +---------+-----------+----------+-----------+ | | + | | | | | + | | | | Application B | + | +----------+----------------+-----------------+ + ``-.._ | | + `-..__ | _.-'' + `--._ | _.-'' + ``-._ | _.-'' + +-----`-.-''-----+ + | | + | | + | Client | + | | + +----------------+ + + Figure 3: Multiple-Application Peer-to-Peer Scenario + +2.2. Agent Scenarios + + This section describes scenarios that include a Diameter agent, in + the form of either a Diameter relay or Diameter proxy. These + scenarios do not consider Diameter redirect agents, since they are + more readily modeled as end servers. The examples have been kept + simple deliberately, to illustrate basic concepts. Significantly + more complicated topologies are possible with Diameter, including + multiple intermediate agents in a path connected in a variety + of ways. + + + + + + + + + + + + + + + +McMurry & Campbell Informational [Page 10] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Figure 4 illustrates a simple Diameter agent scenario with a single + client, agent, and server. In this case, overload can occur at the + server, at the agent, or both. But in most cases, client behavior is + the same whether overload occurs at the server or at the agent. From + the client's perspective, server overload and agent overload are the + same thing. + + +------------------+ + | | + | | + | Server | + | | + +--------+---------+ + | + | + +--------+---------+ + | | + | | + | Agent | + | | + +--------+---------+ + | + | + +--------+---------+ + | | + | | + | Client | + | | + +------------------+ + + Figure 4: Basic Agent Scenario + + Figure 5 shows an agent scenario with multiple servers. If Server 1 + becomes overloaded but Server 2 has sufficient reserve capacity, the + agent may be able to transparently divert some or all Diameter + requests originally bound for Server 1 to Server 2. + + In most cases, the client does not have detailed knowledge of the + Diameter topology upstream of the agent. If the agent uses dynamic + discovery to find eligible servers, the set of eligible servers may + not be enumerable from the perspective of the client. Therefore, in + most cases the agent needs to deal with any upstream overload issues + in a way that is transparent to the client. If one server notifies + the agent that it has become overloaded, the notification should not + be passed back to the client in a way that the client could + mistakenly perceive the agent itself as being overloaded. If the set + + + + + +McMurry & Campbell Informational [Page 11] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + of all possible destinations upstream of the agent no longer has + sufficient capacity for incoming load, the agent itself becomes + effectively overloaded. + + On the other hand, there are cases where the client needs to be able + to select a particular server from behind an agent. For example, if + a Diameter request is part of a multiple-round-trip authentication, + or is otherwise part of a Diameter "session", it may have a + Destination-Host Attribute-Value Pair (AVP) that requires that the + request be served by Server 1. Therefore, the agent may need to + inform a client that a particular upstream server is overloaded or + otherwise unavailable. Note that there can be many ways a server can + be specified, which may have different implications (e.g., by IP + address, by host name, etc). + + +------------------+ +------------------+ + | | | | + | | | | + | Server 1 | | Server 2 | + | | | | + +--------+-`.------+ +------.'+---------+ + `. .' + `. .' + `. .' + `. .' + +-------`.'--------+ + | | + | | + | Agent | + | | + +--------+---------+ + | + | + | + +--------+---------+ + | | + | | + | Client | + | | + +------------------+ + + Figure 5: Multiple-Server Agent Scenario + + + + + + + + + +McMurry & Campbell Informational [Page 12] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Figure 6 shows a scenario where an agent routes requests to a set of + servers for more than one Diameter realm and application. In this + scenario, if Server 1 becomes overloaded or unavailable while + Server 2 still has available capacity, the agent may effectively + operate at reduced capacity for Application A but at full capacity + for Application B. Therefore, the agent needs to be able to report + that it is overloaded for one application but not for another. + + +--------------------------------------------+ + | Application A +----------------------+----------------------+ + |+------------------+ | +----------------+ | +------------------+| + || | | | | | | || + || | | | | | | || + || Server 1 | | | Server 2 | | | Server 3 || + || | | | | | | || + |+---------+--------+ | +-------+--------+ | +--+---------------+| + | | | | | | | + +----------+----------+----------+-----------+ | | + | | | | | + | | | | Application B | + | +----------+-----------------+----------------+ + | | | + ``--.__ | _. + ``-.__ | __.--'' + `--.._ | _..--' + +----``-+.''-----+ + | | + | | + | Agent | + | | + +-------+--------+ + | + | + +-------+--------+ + | | + | | + | Client | + | | + +----------------+ + + Figure 6: Multiple-Application Agent Scenario + + + + + + + + + + +McMurry & Campbell Informational [Page 13] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +2.3. Interconnect Scenario + + Another scenario to consider when looking at Diameter overload is + that of multiple network operators using Diameter components + connected through an interconnect service, e.g., using IPX (IP Packet + eXchange). IPX [IR.34] is an Inter-Operator IP Backbone that + provides a roaming interconnection network between mobile operators + and service providers. IPX is also used to transport Diameter + signaling between operators [IR.88]. Figure 7 shows two network + operators with an interconnect network between them. There could be + any number of these networks between any two network operators' + networks. + + +-------------------------------------------+ + | Interconnect | + | | + | +--------------+ +--------------+ | + | | Server 3 |------| Server 4 | | + | +--------------+ +--------------+ | + | .' `. | + +------.-'--------------------------`.------+ + .' `. + .-' `. + ------------.'-----+ +----`.------------- + +----------+ | | +----------+ + | Server 1 | | | | Server 2 | + +----------+ | | +----------+ + | | + Network Operator 1 | | Network Operator 2 + -------------------+ +------------------- + + Figure 7: Two-Network Interconnect Scenario + + The characteristics of the information that an operator would want to + share over such a connection are different from the information + shared between components within a network operator's network. For + example, network operators may not want to convey topology or + operational information; this would in turn limit how much overload + and loading information can be sent. For the interconnect scenario + shown in Figure 7, Server 2 may want to signal overload to Server 1, + to affect traffic coming from Network Operator 1. + + This case is distinct from those internal to a network operator's + network, where there may be many more elements in a more complicated + topology. Also, the elements in the interconnect network may not + support Diameter overload control, and the network operators may not + want the interconnect network to use overload or loading information. + They may only want the information to pass through the interconnect + + + +McMurry & Campbell Informational [Page 14] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + network without further processing or action by the interconnect + network, even if the elements in the interconnect network do support + Diameter overload control. + +3. Diameter Overload Case Studies + +3.1. Overload in Mobile Data Networks + + As the number of smartphone devices that are Third Generation (3G) + and Long Term Evolution (LTE) enabled continues to expand in mobile + networks, there have been situations where high signaling traffic + load led to overload events at the Diameter-based Home Location + Registers (HLRs) and/or Home Subscriber Servers (HSS) [TR23.843]. + The root causes of the HLR overload events were manifold but included + hardware failure and procedural errors. The result was high + signaling traffic load on the HLR and HSS. + + The 3GPP architecture [TS23.002] makes extensive use of Diameter. It + is used for mobility management [TS29.272], the IP Multimedia + Subsystem (IMS) [TS29.228], and policy and charging control + [TS29.212], as well as other functions. The details of the + architecture are out of scope for this document, but it is worth + noting that there are quite a few Diameter applications, some with + quite large amounts of Diameter signaling in deployed networks. + + The 3GPP specifications do not currently address overload for + Diameter applications or provide a load control mechanism equivalent + to those provided in the more traditional SS7 elements in the Global + System for Mobile Communications (GSM); see [TS29.002]. The + capabilities specified in the 3GPP standards do not adequately + address the abnormal condition where excessively high signaling + traffic load situations are experienced. + + Smartphones, which comprise an increasingly large percentage of + mobile devices, contribute much more heavily, relative to + non-smartphones, to the continuation of a registration surge, due to + their very aggressive registration algorithms. Smartphone behavior + contributes to network loading and can contribute to overload + conditions. The aggressive smartphone logic is designed to: + + a. always have voice and data registration, and + + b. constantly try to be on 3G or LTE data (and thus on 3G voice or + Voice over LTE (VoLTE) [IR.92]) for their added benefits. + + Non-smartphones typically have logic to wait for a time period after + registering successfully on voice and data. + + + + +McMurry & Campbell Informational [Page 15] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + The aggressive smartphone registration is problematic in two ways: + + o first, by generating excessive signaling load towards the HSS that + is ten times the load from a non-smartphone, and + + o second, by causing continual registration attempts when a network + failure affects registrations through the 3G data network. + +3.2. 3GPP Study on Core Network Overload + + A study in the 3GPP System Aspects working group 2 (SA2) on core + network overload has produced the technical report [TR23.843]. This + enumerates several causes of overload in mobile core networks, + including portions that are signaled using Diameter. [TR23.843] is a + work in progress and is not complete. However, it is useful for + pointing out scenarios and the general need for an overload control + mechanism for Diameter. + + It is common for mobile networks to employ more than one radio + technology and to do so in an overlay fashion with multiple + technologies present in the same location (such as 2nd or 3rd + generation mobile technologies, along with LTE). This presents + opportunities for traffic storms when issues occur on one overlay and + not another as all devices that had been on the overlay with issues + switch. This causes a large amount of Diameter traffic as locations + and policies are updated. + + Another scenario called out by this study is a flood of registration + and mobility management events caused by some element in the core + network failing. This flood of traffic from end nodes falls under + the network-initiated traffic flood category. There is likely to + also be traffic resulting directly from the component failure in this + case. A similar flood can occur when elements or components recover + as well. + + Subscriber-initiated traffic floods are also indicated in this study + as an overload mechanism where a large number of mobile devices are + attempting to access services at the same time, such as in response + to an entertainment event or a catastrophic event. + + While this 3GPP study is concerned with the broader effects of these + scenarios on wireless networks and their elements, they have + implications specifically for Diameter signaling. One of the goals + of this document is to provide guidance for a core mechanism that can + be used to mitigate the scenarios called out by this study. + + + + + + +McMurry & Campbell Informational [Page 16] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +4. Existing Mechanisms + + Diameter offers both implicit and explicit mechanisms for a Diameter + node to learn that a peer is overloaded or unreachable. The implicit + mechanism is simply the lack of responses to requests. If a client + fails to receive a response in a certain time period, it assumes that + the upstream peer is unavailable or is overloaded to the point of + effective unavailability. The watchdog mechanism [RFC3539] ensures + that transaction responses occur at a certain rate even when there is + otherwise little or no other Diameter traffic. + + The explicit mechanism can involve specific protocol error responses, + where an agent or server tells a downstream peer that it is either + too busy to handle a request (DIAMETER_TOO_BUSY) or unable to route a + request to an upstream destination (DIAMETER_UNABLE_TO_DELIVER) + perhaps because that destination itself is overloaded to the point of + unavailability. + + Another explicit mechanism, a DPR (Disconnect-Peer-Request) message, + can be sent with a Disconnect-Cause of BUSY. This signals the + sender's intent to close the transport connection and requests that + the client not reconnect. + + Once a Diameter node learns via one of these mechanisms that an + upstream peer has become overloaded, it can then attempt to take + action to reduce the load. This usually means forwarding traffic to + an alternate destination, if available. If no alternate destination + is available, the node must either reduce the number of messages it + originates (in the case of a client) or inform the client to reduce + traffic (in the case of an agent). + + Diameter requires the use of a congestion-managed transport layer, + currently TCP or SCTP, to mitigate network congestion. It is + expected that these transports manage network congestion and that + issues with transport (e.g., congestion propagation and window + management) are managed at that level. But even with a congestion- + managed transport, a Diameter node can become overloaded at the + Diameter protocol or application layers due to the causes described + in Section 1.2, and congestion-managed transports do not provide + facilities (and are at the wrong level) to handle server overload. + Transport-level congestion management is also not sufficient to + address overload in cases of multi-hop and multi-destination + signaling. + + + + + + + + +McMurry & Campbell Informational [Page 17] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +5. Issues with the Current Mechanisms + + The currently available Diameter mechanisms for indicating an + overload condition are not adequate to avoid service outages due to + overload. This inadequacy may, in turn, contribute to broader + impacts resulting from overload due to unresponsive Diameter nodes + causing application-layer or transport-layer retransmissions. In + particular, they do not allow a Diameter agent or server to shed load + as it approaches overload. At best, a node can only indicate that it + needs to entirely stop receiving requests, i.e., that it has + effectively failed. Even that is problematic due to the inability to + indicate durational validity on the transient errors available in the + base Diameter protocol. Diameter offers no mechanism to allow a node + to indicate different overload states for different categories of + messages, for example, if it is overloaded for one Diameter + application but not another. + +5.1. Problems with Implicit Mechanism + + The implicit mechanism doesn't allow an agent or server to inform the + client of a problem until it is effectively too late to do anything + about it. The client does not know that it needs to take action + until the upstream node has effectively failed. A Diameter node has + no opportunity to shed load early to avoid collapse in the first + place. + + Additionally, the implicit mechanism cannot distinguish between + overload of a Diameter node and network congestion. Diameter treats + the failure to receive an answer as a transport failure. + +5.2. Problems with Explicit Mechanisms + + The Diameter specification is ambiguous on how a client should handle + receipt of a DIAMETER_TOO_BUSY response. The base specification + [RFC6733] indicates that the sending client should attempt to send + the request to a different peer. It makes no suggestion that the + receipt of a DIAMETER_TOO_BUSY response should affect future Diameter + messages in any way. + + The Authentication, Authorization, and Accounting (AAA) Transport + Profile [RFC3539] recommends that a AAA node that receives a "Busy" + response failover all remaining requests to a different agent or + server. But while the Diameter base specification explicitly depends + on [RFC3539] to define transport behavior, it does not refer to + [RFC3539] in the description of behavior on receipt of a + DIAMETER_TOO_BUSY error. There's a strong likelihood that at least + some implementations will continue to send Diameter requests to an + upstream peer even after receiving a DIAMETER_TOO_BUSY error. + + + +McMurry & Campbell Informational [Page 18] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + BCP 41 [RFC2914] describes, among other things, how end-to-end + application behavior can help avoid congestion collapse. In + particular, an application should avoid sending messages that will + never be delivered or processed. The DIAMETER_TOO_BUSY behavior as + described in the Diameter base specification fails at this, since if + an upstream node becomes overloaded, a client attempts each request + and does not discover the need to failover the request until the + initial attempt fails. + + The situation is improved if implementations follow the [RFC3539] + recommendation to keep state about upstream peer overload. But even + then, the Diameter specification offers no guidance on how long a + client should wait before retrying the overloaded destination. If an + agent or server supports multiple realms and/or applications, + DIAMETER_TOO_BUSY offers no way to indicate that it is overloaded for + one application but not another. A DIAMETER_TOO_BUSY error can only + indicate overload at a "whole server" scope. + + Agent processing of a DIAMETER_TOO_BUSY response is also problematic + as described in the base specification. DIAMETER_TOO_BUSY is defined + as a protocol error. If an agent receives a protocol error, it may + either handle it locally or forward the response back towards the + downstream peer. If a downstream peer receives the DIAMETER_TOO_BUSY + response, it may stop sending all requests to the agent for some + period of time, even though the agent may still be able to deliver + requests to other upstream peers. + + DIAMETER_UNABLE_TO_DELIVER errors, or using DPR with cause code BUSY, + also have no mechanisms for specifying the scope or cause of the + failure, or the durational validity. + + The issues with error responses described in [RFC6733] extend beyond + the particular issues for overload control and have been addressed in + an ad hoc fashion by various implementations. Addressing these in a + standard way would be a useful exercise, but it is beyond the scope + of this document. + +6. Extensibility and Application Independence + + Given the variety of scenarios in which Diameter elements can be + deployed and the variety of roles they can fulfill with Diameter and + other technologies, a single algorithm for handling overload may not + be sufficient. For purposes of this discussion, an algorithm is + inclusive of behavior for control of overload but does not encompass + the general mechanism for transporting control information. This + effort cannot anticipate all possible future scenarios and roles. + Extensibility, particularly of algorithms used to deal with overload, + will be important to cover these cases. + + + +McMurry & Campbell Informational [Page 19] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + Similarly, the scopes to which overload information may apply may + include cases that have not yet been considered. Extensibility in + this area will also be important. + + The basic mechanism is intended to be application independent, that + is, a Diameter node can use it across any existing and future + Diameter applications and expect reasonable results. Certain + Diameter applications might, however, benefit from application- + specific behavior over and above the mechanism's defaults. For + example, an application specification might specify relative + priorities of messages or selection of a specific overload control + algorithm. + +7. Solution Requirements + + This section proposes requirements for an improved mechanism to + control Diameter overload, with the goals of addressing the issues + described in Section 5 and supporting the scenarios described in + Section 2. These requirements are stated primarily in terms of + individual node behavior to inform the design of the improved + mechanism; solution designers should keep in mind that the overall + goal is improved overall system behavior across all the nodes + involved, not just improved behavior from specific individual nodes. + +7.1. General + + REQ 1: The solution MUST provide a communication method for Diameter + nodes to exchange load and overload information. + + REQ 2: The solution MUST allow Diameter nodes to support overload + control regardless of which Diameter applications they + support. Diameter clients and agents must be able to use the + received load and overload information to support graceful + behavior during an overload condition. Graceful behavior + under overload conditions is best described by REQ 3. + + REQ 3: The solution MUST limit the impact of overload on the overall + useful throughput of a Diameter server, even when the + incoming load on the network is far in excess of its + capacity. The overall useful throughput under load is the + ultimate measure of the value of a solution. + + REQ 4: Diameter allows requests to be sent from either side of a + connection, and either side of a connection may have need to + provide its overload status. The solution MUST allow each + side of a connection to independently inform the other of its + overload status. + + + + +McMurry & Campbell Informational [Page 20] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + REQ 5: Diameter allows nodes to determine their peers via dynamic + discovery or manual configuration. The solution MUST work + consistently without regard to how peers are determined. + + REQ 6: The solution designers SHOULD seek to minimize the amount of + new configuration required in order to work. For example, it + is better to allow peers to advertise or negotiate support + for the solution, rather than to require that this knowledge + be configured at each node. + +7.2. Performance + + REQ 7: The solution and any associated default algorithm(s) MUST + ensure that the system remains stable. At some point after + an overload condition has ended, the solution MUST enable + capacity to stabilize and become equal to what it would be in + the absence of an overload condition. Note that this also + requires that the solution MUST allow nodes to shed load + without introducing non-converging oscillations during or + after an overload condition. + + REQ 8: Supporting nodes MUST be able to distinguish current overload + information from stale information. + + REQ 9: The solution MUST function across fully loaded as well as + quiescent transport connections. This is partially derived + from the requirement for stability in REQ 7. + + REQ 10: Consumers of overload information MUST be able to determine + when the overload condition improves or ends. + + REQ 11: The solution MUST be able to operate in networks of different + sizes. + + REQ 12: When a single network node fails, goes into overload, or + suffers from reduced processing capacity, the solution MUST + make it possible to limit the impact of the affected node on + other nodes in the network. This helps to prevent a small- + scale failure from becoming a widespread outage. + + REQ 13: The solution MUST NOT introduce substantial additional work + for a node in an overloaded state. For example, a + requirement for an overloaded node to send overload + information every time it received a new request would + introduce substantial work. + + + + + + +McMurry & Campbell Informational [Page 21] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + REQ 14: Some scenarios that result in overload involve a rapid + increase of traffic with little time between normal levels + and levels that induce overload. The solution SHOULD provide + for rapid feedback when traffic levels increase. + + REQ 15: The solution MUST NOT interfere with the congestion control + mechanisms of underlying transport protocols. For example, a + solution that opened additional TCP connections when the + network is congested would reduce the effectiveness of the + underlying congestion control mechanisms. + +7.3. Heterogeneous Support for Solution + + REQ 16: The solution is likely to be deployed incrementally. The + solution MUST support a mixed environment where some, but not + all, nodes implement it. + + REQ 17: In a mixed environment with nodes that support the solution + and nodes that do not, the solution MUST NOT result in + materially less useful throughput during overload as would + have resulted if the solution were not present. It SHOULD + result in less severe overload in this environment. + + REQ 18: In a mixed environment of nodes that support the solution and + nodes that do not, the solution MUST NOT preclude elements + that support overload control from treating elements that do + not support overload control in an equitable fashion relative + to those that do. Users and operators of nodes that do not + support the solution MUST NOT unfairly benefit from the + solution. The solution specification SHOULD provide guidance + to implementors for dealing with elements not supporting + overload control. + + REQ 19: It MUST be possible to use the solution between nodes in + different realms and in different administrative domains. + + REQ 20: Any explicit overload indication MUST be clearly + distinguishable from other errors reported via Diameter. + + REQ 21: In cases where a network node fails, is so overloaded that it + cannot process messages, or cannot communicate due to a + network failure, it may not be able to provide explicit + indications of the nature of the failure or its levels of + overload. The solution MUST result in at least as much + useful throughput as would have resulted if the solution were + not in place. + + + + + +McMurry & Campbell Informational [Page 22] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +7.4. Granular Control + + REQ 22: The solution MUST provide a way for a node to throttle the + amount of traffic it receives from a peer node. This + throttling SHOULD be graded so that it can be applied + gradually as offered load increases. Overload is not a + binary state; there may be degrees of overload. + + REQ 23: The solution MUST provide sufficient information to enable a + load-balancing node to divert messages that are rejected or + otherwise throttled by an overloaded upstream node to other + upstream nodes that are the most likely to have sufficient + capacity to process them. + + REQ 24: The solution MUST provide a mechanism for indicating load + levels, even when not in an overload condition, to assist + nodes in making decisions to prevent overload conditions from + occurring. + +7.5. Priority and Policy + + REQ 25: The base specification for the solution SHOULD offer general + guidance on which message types might be desirable to send or + process over others during times of overload, based on + application-specific considerations. For example, it may be + more beneficial to process messages for existing sessions + ahead of new sessions. Some networks may have a requirement + to give priority to requests associated with emergency + sessions. Any normative or otherwise detailed definition of + the relative priorities of message types during an overload + condition will be the responsibility of the application + specification. + + REQ 26: The solution MUST NOT prevent a node from prioritizing + requests based on any local policy, so that certain requests + are given preferential treatment, given additional + retransmission, not throttled, or processed ahead of others. + +7.6. Security + + REQ 27: The solution MUST NOT provide new vulnerabilities to + malicious attack or increase the severity of any existing + vulnerabilities. This includes vulnerabilities to DoS and + DDoS attacks as well as replay and man-in-the-middle attacks. + Note that the Diameter base specification [RFC6733] lacks + end-to-end security, and this must be considered (see + Security Considerations in this document (Section 8)). Note + + + + +McMurry & Campbell Informational [Page 23] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + that this requirement was expressed at a high level so as to + not preclude any particular solution. Is is expected that + the solution will address this in more detail. + + REQ 28: The solution MUST NOT depend on being deployed in + environments where all Diameter nodes are completely trusted. + It SHOULD operate as effectively as possible in environments + where other nodes are malicious; this includes preventing + malicious nodes from obtaining more than a fair share of + service. Note that this does not imply any responsibility on + the solution to detect, or take countermeasures against, + malicious nodes. + + REQ 29: It MUST be possible for a supporting node to make + authorization decisions about what information will be sent + to peer nodes based on the identity of those nodes. This + allows a domain administrator who considers the load of their + nodes to be sensitive information to restrict access to that + information. Of course, in such cases, there is no + expectation that the solution itself will help prevent + overload from that peer node. + + REQ 30: The solution MUST NOT interfere with any Diameter-compliant + method that a node may use to protect itself from overload + from non-supporting nodes or from denial-of-service attacks. + +7.7. Flexibility and Extensibility + + REQ 31: There are multiple situations where a Diameter node may be + overloaded for some purposes but not others. For example, + this can happen to an agent or server that supports multiple + applications, or when a server depends on multiple external + resources, some of which may become overloaded while others + are fully available. The solution MUST allow Diameter nodes + to indicate overload with sufficient granularity to allow + clients to take action based on the overloaded resources + without unreasonably forcing available capacity to go unused. + The solution MUST support specification of overload + information with granularities of at least "Diameter node", + "realm", and "Diameter application" and MUST allow + extensibility for others to be added in the future. + + REQ 32: The solution MUST provide a method for extending the + information communicated and the algorithms used for overload + control. + + + + + + +McMurry & Campbell Informational [Page 24] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + REQ 33: The solution MUST provide a default algorithm that is + mandatory to implement. + + REQ 34: The solution SHOULD provide a method for exchanging overload + and load information between elements that are connected by + intermediaries that do not support the solution. + +8. Security Considerations + + A Diameter overload control mechanism is primarily concerned with the + load-related and overload-related behavior of nodes in a Diameter + network, and the information used to affect that behavior. Load and + overload information is shared between nodes and directly affects the + behavior, and thus the information is potentially vulnerable to a + number of methods of attack. + + Load and overload information may also be sensitive from both + business and network protection viewpoints. Operators of Diameter + equipment want to control the visibility of load and overload + information to keep it from being used for competitive intelligence + or for targeting attacks. It is also important that the Diameter + overload control mechanism not introduce any way in which any other + information carried by Diameter is sent inappropriately. + + Note that the Diameter base specification [RFC6733] lacks end-to-end + security, making it difficult for non-adjacent nodes to verify the + authenticity and ownership of load and overload information. + Authentication of load and overload information helps to alleviate + several of the security issues listed in this section. + + This document includes requirements intended to mitigate the effects + of attacks and to protect the information used by the mechanism. + This section discusses potential security considerations for overload + control solutions. This discussion provides the motivation for + several normative requirements described in Section 7. The + discussion includes specific references to the normative requirements + that apply for each issue. + +8.1. Access Control + + To control the visibility of load and overload information, sending + should be subject to some form of authentication and authorization of + the receiver. It is also important to the receivers that they are + confident the load and overload information they receive is from a + legitimate source. REQ 28 requires that the solution work without + assuming that all Diameter nodes in a network are trusted for the + purposes of exchanging overload and load information. REQ 29 + requires that the solution let nodes restrict unauthorized parties + + + +McMurry & Campbell Informational [Page 25] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + from seeing overload information. Note that this implies a certain + amount of configurability on the nodes supporting the Diameter + overload control mechanism. + +8.2. Denial-of-Service Attacks + + An overload control mechanism provides a very attractive target for + denial-of-service attacks. A small number of messages may effect a + large service disruption by falsely reporting overload conditions. + Alternately, attacking servers nearing, or in, overload may also be + facilitated by disrupting their overload indications, potentially + preventing them from mitigating their overload condition. + + A design goal for the Diameter overload control mechanism is to + minimize or eliminate the possibility of using the mechanism for this + type of attack. More strongly, REQ 27 forbids the solution from + introducing new vulnerabilities to malicious attack. Additionally, + REQ 30 stipulates that the solution not interfere with other + mechanisms used for protection against denial-of-service attacks. + + As the intent of some denial-of-service attacks is to induce overload + conditions, an effective overload control mechanism should help to + mitigate the effects of such an attack. + +8.3. Replay Attacks + + An attacker that has managed to obtain some messages from the + overload control mechanism may attempt to affect the behavior of + nodes supporting the mechanism by sending those messages at + potentially inopportune times. In addition to time shifting, replay + attacks may send messages to other nodes as well (target shifting). + + A design goal for the Diameter overload control solution is to + minimize or eliminate the possibility of causing disruption by using + a replay attack on the Diameter overload control mechanism. + (Allowing a replay attack using the overload control solution would + violate REQ 27.) + +8.4. Man-in-the-Middle Attacks + + By inserting themselves between two nodes supporting the Diameter + overload control mechanism, an attacker may potentially both access + and alter the information sent between those nodes. This can be used + for information gathering for business intelligence and attack + targeting, as well as direct attacks. + + + + + + +McMurry & Campbell Informational [Page 26] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + REQs 27, 28, and 29 imply a need to prevent man-in-the-middle attacks + on the overload control solution. A transport using Transport Layer + Security (TLS) and/or IPsec may be desirable for this purpose. + +8.5. Compromised Hosts + + A compromised host that supports the Diameter overload control + mechanism could be used for information gathering as well as for + sending malicious information to any Diameter node that would + normally accept information from it. While it is beyond the scope of + the Diameter overload control mechanism to mitigate any operational + interruption to the compromised host, REQs 28 and 29 imply a need to + minimize the impact that a compromised host can have on other nodes + through the use of the Diameter overload control mechanism. Of + course, a compromised host could be used to cause damage in a number + of other ways. This is out of scope for a Diameter overload control + mechanism. + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC6733] Fajardo, V., Arkko, J., Loughney, J., and G. Zorn, + "Diameter Base Protocol", RFC 6733, October 2012. + + [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, + RFC 2914, September 2000. + + [RFC3539] Aboba, B. and J. Wood, "Authentication, Authorization and + Accounting (AAA) Transport Profile", RFC 3539, June 2003. + +9.2. Informative References + + [RFC5390] Rosenberg, J., "Requirements for Management of Overload + in the Session Initiation Protocol", RFC 5390, + December 2008. + + [RFC6357] Hilt, V., Noel, E., Shen, C., and A. Abdelal, "Design + Considerations for Session Initiation Protocol (SIP) + Overload Control", RFC 6357, August 2011. + + [TR23.843] 3GPP, "Study on Core Network (CN) overload solutions", + TR 23.843 1.2.0, Work in Progress, October 2013. + + + + + +McMurry & Campbell Informational [Page 27] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + + [IR.34] GSMA, "Inter-Service Provider IP Backbone Guidelines", + IR 34 9.1, May 2013. + + [IR.88] GSMA, "LTE Roaming Guidelines", IR 88 9.0, January 2013. + + [IR.92] GSMA, "IMS Profile for Voice and SMS", IR 92 7.0, + March 2013. + + [TS23.002] 3GPP, "Network Architecture", TS 23.002 12.2.0, + June 2013. + + [TS29.272] 3GPP, "Evolved Packet System (EPS); Mobility Management + Entity (MME) and Serving GPRS Support Node (SGSN) related + interfaces based on Diameter protocol", TS 29.272 12.2.0, + September 2013. + + [TS29.212] 3GPP, "Policy and Charging Control (PCC) over Gx/Sd + reference point", TS 29.212 12.2.0, September 2013. + + [TS29.228] 3GPP, "IP Multimedia (IM) Subsystem Cx and Dx interfaces; + Signalling flows and message contents", TS 29.228 12.0.0, + September 2013. + + [TS29.002] 3GPP, "Mobile Application Part (MAP) specification", + TS 29.002 12.2.0, September 2013. + + + + + + + + + + + + + + + + + + + + + + + + + + +McMurry & Campbell Informational [Page 28] + +RFC 7068 Diameter Overload Control Requirements November 2013 + + +Appendix A. Contributors + + Significant contributions to this document were made by Adam Roach + and Eric Noel. + +Appendix B. Acknowledgements + + Review of, and contributions to, this specification by Martin Dolly, + Carolyn Johnson, Jianrong Wang, Imtiaz Shaikh, Jouni Korhonen, Robert + Sparks, Dieter Jacobsohn, Janet Gunn, Jean-Jacques Trottin, Laurent + Thiebaut, Andrew Booth, and Lionel Morand were most appreciated. We + would like to thank them for their time and expertise. + +Authors' Addresses + + Eric McMurry + Oracle + 17210 Campbell Rd. + Suite 250 + Dallas, TX 75252 + US + + EMail: [email protected] + + + Ben Campbell + Oracle + 17210 Campbell Rd. + Suite 250 + Dallas, TX 75252 + US + + EMail: [email protected] + + + + + + + + + + + + + + + + + + +McMurry & Campbell Informational [Page 29] + diff --git a/lib/diameter/doc/standard/rfc7075.txt b/lib/diameter/doc/standard/rfc7075.txt new file mode 100644 index 0000000000..f5fd905e72 --- /dev/null +++ b/lib/diameter/doc/standard/rfc7075.txt @@ -0,0 +1,563 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Tsou +Request for Comments: 7075 Huawei Technologies (USA) +Updates: 6733 R. Hao +Category: Standards Track Comcast Cable +ISSN: 2070-1721 T. Taylor, Ed. + Huawei Technologies + November 2013 + + + Realm-Based Redirection In Diameter + +Abstract + + The Diameter protocol includes a capability for message redirection, + controlled by an application-independent "redirect agent". In some + circumstances, an operator may wish to redirect messages to an + alternate domain without specifying individual hosts. This document + specifies an application-specific mechanism by which a Diameter + server or proxy (node) can perform such a redirection when the + Straightforward-Naming Authority Pointer (S-NAPTR) is not used for + dynamic peer discovery. A node performing this new function is + referred to as a "Realm-based Redirect Server". + + This memo updates Sections 6.13 and 6.14 of RFC 6733 with respect to + the usage of the Redirect-Host-Usage and Redirect-Max-Cache-Time + Attribute-Value Pairs (AVPs). + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7075. + + + + + + + + + + + +Tsou, et al. Standards Track [Page 1] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +Copyright Notice + + Copyright (c) 2013 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Support of Realm-Based Redirection Within Applications . . . 4 + 3. Realm-Based Redirection . . . . . . . . . . . . . . . . . . . 5 + 3.1. Configuration of the Realm-Based Redirect Server . . . . 5 + 3.2. Behavior of Diameter Nodes . . . . . . . . . . . . . . . 6 + 3.2.1. Behavior at the Realm-Based Redirect Server . . . . . 6 + 3.2.2. Proxy Behavior . . . . . . . . . . . . . . . . . . . 6 + 3.2.3. Client Behavior . . . . . . . . . . . . . . . . . . . 7 + 3.3. The Redirect-Realm AVP . . . . . . . . . . . . . . . . . 7 + 3.4. DIAMETER_REALM_REDIRECT_INDICATION Protocol Error Code . 7 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 + 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 + 7.2. Informative References . . . . . . . . . . . . . . . . . 9 + + + + + + + + + + + + + + + + + +Tsou, et al. Standards Track [Page 2] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +1. Introduction + + The Diameter base protocol [RFC6733] specifies a basic redirection + service provided by a redirect agent. The redirect indication + returned by the redirect agent is described in Section 6.1.8 and + Sections 6.12 through 6.14 of [RFC6733]. It provides one or more + individual hosts to the message sender as the destination of the + redirected message. + + However, consider the case where an operator has offered a specific + service but no longer wishes to do so. The operator has arranged for + an alternative domain to provide the service. To aid in the + transition to the new arrangement, the original operator maintains a + redirect server to indicate to the message sender the alternative + domain to which the redirect the request should be sent. However, + the original operator should not have to configure the redirect + server with a list of hosts to contact in the alternative operator's + domain; the original operator should simply be able to provide + redirect indications to the domain as a whole. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Within this specification, the term "realm-based redirection" is used + to refer to a mode of operation where a realm, rather than an + individual host, is returned as the redirect indication. + + The term "Realm-based Redirect Server" denotes the Diameter node + (Diameter server or proxy) that returns the realm-based redirection. + The behavior of the Realm-based Redirect Server itself is a slight + modification to the behavior of a basic redirect agent as described + in Section 6.1.8 of [RFC6733]. + + The use of a number of terms in this document is consistent with the + usage in [RFC6733]: "Diameter client", "Diameter node", "Diameter + peer", "Diameter server", "proxy", "realm" or "domain", "redirect + agent", and "session" as defined in Section 1.2, and "application" as + defined implicitly by Sections 1.3.4, 2.3, and 2.4. + + + + + + + + + + +Tsou, et al. Standards Track [Page 3] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +2. Support of Realm-Based Redirection Within Applications + + The DNS-based dynamic peer discovery mechanism defined in the + Diameter base protocol [RFC6733] provides a simple mechanism for + realm-based redirection using the S-NAPTR DDDS application [RFC3958]. + When S-NAPTR is used for peer discovery, redirection of Diameter + requests from the original realm to a new realm may be performed by + updating the existing NAPTR resource records (RRs) for the original + realm as follows: the NAPTR RR for the desired application(s) and + supported application protocol(s) provided by the new realm will have + an empty FLAG field and the REPLACEMENT field will contain the new + realm to use for the next DNS lookup. The new realm can be + arbitrary; the restriction in [RFC6733] that the NAPTR replacement + field match the domain of the original query does not apply for + realm-based redirect purposes. + + However, the use of DNS-based dynamic peer discovery is optional for + Diameter implementations. For deployments that do not make use of + S-NAPTR peer discovery, support of realm-based redirection needs to + be specified as part of the functionality supported by a Diameter + application. In this way, support of the considered Diameter + application (discovered during capabilities exchange phase as defined + in Diameter base protocol [RFC6733]) indicates implicit support of + the realm-based redirection mechanism. A new application + specification can incorporate the mechanism specified here by making + it mandatory to implement for the application and referencing this + specification normatively. + + The result of making realm-based redirection an application-specific + behavior is that it cannot be performed by a redirect agent as + defined in [RFC6733], but MUST be performed instead by an + application-aware Diameter node (Diameter server or proxy) (hereafter + called a "Realm-based Redirect Server"). + + An application can specify that realm-based redirection operates only + on complete sessions beginning with the initial message or on every + message within the application, even if earlier messages of the same + session were not redirected. This distinction matters only when + realm-based redirection is first initiated. In the former case, + existing sessions will not be disrupted by the deployment of realm- + based redirection. In the latter case, existing sessions will be + disrupted if they are stateful. + + + + + + + + + +Tsou, et al. Standards Track [Page 4] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +3. Realm-Based Redirection + + This section specifies an extension of the Diameter base protocol + [RFC6733] to achieve realm-based redirection. The elements of this + solution are: + + o a new result code, DIAMETER_REALM_REDIRECT_INDICATION (3011); + + o a new attribute-value pair (AVP), Redirect-Realm (620); and + + o associated behavior at Diameter nodes implementing this + specification. + + This behavior includes the optional use of the Redirect-Host-Usage + and Redirect-Max-Cache-Time AVPs. In this document, these AVPs apply + to the peer discovered by a node acting on the redirect server's + response, an extension to their normal usage as described in Sections + 6.13 and 6.14 of [RFC6733]. + + Section 3.2.2 and Section 3.2.3 describe how a proxy or client may + update its routing table for the application and initial realm as a + result of selecting a peer in the new realm after realm-based + redirection. Note that as a result, the proxy or client will + automatically route subsequent requests for that application to the + new realm (with the possible exception of requests within sessions + already established with the initial realm) until the cached routing + entry expires. This should be borne in mind if the rerouting is + intended to be temporary. + +3.1. Configuration of the Realm-Based Redirect Server + + A Diameter node (Diameter server or proxy) acting as a Realm-based + Redirect Server MUST be configured as follows to execute realm-based + redirection: + + o configured with an application that incorporates realm-based + redirection; + + o the Local Action field of the routing table described in + Section 2.7 of [RFC6733] is set to LOCAL; + + o an application-specific field is set to indicate that the required + local action is to perform realm-based redirection; + + o an associated application-specific field is configured with the + identities of one or more realms to which the request should be + redirected. + + + + +Tsou, et al. Standards Track [Page 5] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +3.2. Behavior of Diameter Nodes + +3.2.1. Behavior at the Realm-Based Redirect Server + + As mentioned in Section 2, an application can specify that realm- + based redirection operates only on complete sessions beginning with + the initial message (i.e., to prevent disruption of established + sessions) or on every message within the application, even if earlier + messages of the same session were not redirected. + + If a Realm-based Redirect Server configured as described in + Section 3.1 receives a request to which realm-based redirection + applies, the Realm-based Redirect Server MUST reply with an answer + message with the 'E' bit set, while maintaining the Hop-by-Hop + Identifier in the header. The Realm-based Redirect Server MUST + include the Result-Code AVP set to + DIAMETER_REALM_REDIRECT_INDICATION. The Realm-based Redirect Server + MUST also include the alternate realm identifier(s) with which it has + been configured, each in a separate Redirect-Realm AVP instance. + + The Realm-based Redirect Server MAY include a copy of the Redirect- + Host-Usage AVP, which SHOULD be set to REALM_AND_APPLICATION. If + this AVP is added, the Redirect-Max-Cache-Time AVP MUST also be + included. Note that these AVPs apply to the peer discovered by a + node acting on the Realm-based Redirect Server's response as + described in the next section. This is an extension of their normal + usage as described by Sections 6.13 and 6.14 of [RFC6733]. + + Realm-based redirection MAY be applied even if a Destination-Host + AVP is present in the request, depending on the operator-based + policy. + +3.2.2. Proxy Behavior + + A proxy conforming to this specification that receives an answer + message with the Result-Code AVP set to + DIAMETER_REALM_REDIRECT_INDICATION MUST attempt to reroute the + original request to a server in a realm identified by a Redirect- + Realm AVP instance in the answer message, and if it fails MUST + forward the indication toward the client. To reroute the request, it + MUST take the following actions: + + 1. Select a specific realm from amongst those identified in + instances of the Redirect-Realm AVP in the answer message. + + 2. If successful, locate and establish a route to a peer in the + realm given by the Redirect-Realm AVP, using normal discovery + procedures as described in Section 5.2 of [RFC6733]. + + + +Tsou, et al. Standards Track [Page 6] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + + 3. If again successful: + + A. update its cache of routing entries for the realm and + application to which the original request was directed, + taking into account the Redirect-Host-Usage and Redirect-Max- + Cache-Time AVPs, if present in the answer. + + B. Remove the Destination-Host (if present) and Destination- + Realm AVPs from the original request and add a new + Destination-Realm AVP containing the realm selected in the + initial step. + + C. Forward the modified request. + + 4. If either of the preceding steps 2-3 fail and additional realms + have been identified in the original answer, select another + instance of the Redirect-Realm AVP in that answer and repeat + steps 2-3 for the realm that it identifies. + +3.2.3. Client Behavior + + A client conforming to this specification MUST be prepared to receive + either an answer message containing a Result-Code AVP set to + DIAMETER_REALM_REDIRECT_INDICATION, or, as the result of proxy + action, some other result from a realm differing from the one to + which it sent the original request. In the case where it receives + DIAMETER_REALM_REDIRECT_INDICATION, the client SHOULD follow the same + steps prescribed in the previous section for a proxy, in order to + both update its routing table and obtain service for the original + request. + +3.3. The Redirect-Realm AVP + + The Redirect-Realm AVP (620) is of type DiameterIdentity. It + specifies a realm to which a node receiving a redirect indication + containing the result code value DIAMETER_REALM_REDIRECT_INDICATION + and the Redirect-Realm AVP SHOULD route the original request. + +3.4. DIAMETER_REALM_REDIRECT_INDICATION Protocol Error Code + + The DIAMETER_REALM_REDIRECT_INDICATION (3011) Protocol error code + indicates that a server has determined that the request within an + application supporting realm-based redirection could not be satisfied + locally, and the initiator of the request SHOULD direct the request + directly to a peer within a realm that has been identified in the + response. When set, the Redirect-Realm AVP MUST be present. + + + + + +Tsou, et al. Standards Track [Page 7] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +4. Security Considerations + + The general recommendations given in Section 13 of the Diameter base + protocol [RFC6733] apply. Specific security recommendations related + to the realm-based redirection defined in this document are described + below. + + Realm-based redirection implies a change in the business relationship + between organizations. Before redirecting a request towards a realm + different from the initial realm, the client or proxy MUST ensure + that the authorization checks have been performed at each connection + along the path toward the realm identified in the realm-based + redirect indication. Details on Diameter authorization path set-up + are given in Section 2.9 of [RFC6733]. Section 13 of [RFC6733] + provides recommendations on how to authenticate and secure each peer- + to-peer connection (using TLS, DTLS, or IPsec) along the way, thus + permitting the necessary hop-by-hop authorization checks. + + Although it is assumed that the administrative domains are secure, a + compromised Diameter node acting as a Realm-based Redirect Server + would be able to redirect a large number of Diameter requests towards + a victim domain that would then be flooded with undesired Diameter + requests. Such an attack is nevertheless discouraged by the use of + secure Diameter peer-to-peer connections and authorization checks, + since these would enable a potential victim domain to discover from + where an attack is coming. That in itself, however, does not prevent + such a DoS attack. + + Because realm-based redirection defined in this document implies that + the Destination-Realm AVP in a client-initiated request can be + changed by a Diameter proxy in the path between the client and the + server, any cryptographic algorithm that would use the Destination- + Realm AVP as input to the calculation performed by the client and the + server would be broken by this form of redirection. Application + specifications that would rely on such cryptographic algorithms + SHOULD NOT incorporate this realm-based redirection. + +5. IANA Considerations + + This specification allocates a new AVP code Redirect-Realm (620) in + the "AVP Codes" registry under "Authentication, Authorization, and + Accounting (AAA) Parameters". + + This specification allocates a new Result-Code value + DIAMETER_REALM_REDIRECT_INDICATION (3011) in the "Result-Code AVP + Values (code 268) - Protocol Errors" registry under "Authentication, + Authorization, and Accounting (AAA) Parameters". + + + + +Tsou, et al. Standards Track [Page 8] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +6. Acknowledgements + + Glen Zorn, Sebastien Decugis, Wolfgang Steigerwald, Mark Jones, + Victor Fajardo, Jouni Korhonen, Avi Lior, and Lionel Morand + contributed comments that helped to shape this document. As + shepherd, Lionel contributed a second set of comments that added + polish to the document before it was submitted to the IESG. Benoit + Claise picked up additional points that were quickly resolved with + Lionel's help. During IETF Last Call Review, Enrico Marocco picked + up some important editorial corrections. Stefan Winter contributed + text on the use of S-NAPTR as an alternative method of realm-based + redirection already specified in [RFC6733]. Derek Atkins performed a + review on behalf of the Security Directorate. Lionel noted one more + correction. + + Finally, this document benefited from comments and discussion raised + by IESG members Stewart Bryant, Stephen Farrell, Barry Leiba, Pete + Resnick, Jari Arkko, and Sean Turner during IESG review. + + The authors are very grateful to Lionel Morand for his active role as + document shepherd. At each stage, he worked to summarize and resolve + comments, making the editor's role easy. Thank you. + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC6733] Fajardo, V., Arkko, J., Loughney, J., and G. Zorn, + "Diameter Base Protocol", RFC 6733, October 2012. + +7.2. Informative References + + [RFC3958] Daigle, L. and A. Newton, "Domain-Based Application + Service Location Using SRV RRs and the Dynamic Delegation + Discovery Service (DDDS)", RFC 3958, January 2005. + + + + + + + + + + + + + +Tsou, et al. Standards Track [Page 9] + +RFC 7075 Realm-Based Redirection In Diameter November 2013 + + +Authors' Addresses + + Tina Tsou + Huawei Technologies (USA) + 2330 Central Expressway + Santa Clara, CA 95050 + USA + + Phone: +1 408 330 4424 + EMail: [email protected] + URI: http://tinatsou.weebly.com/contact.html + + + Ruibing Hao + Comcast Cable + One Comcast Center + Philadelphia, PA 19103 + USA + + Phone: +1 215 286 3991(O) + EMail: [email protected] + + + Tom Taylor (editor) + Huawei Technologies + Ottawa + Canada + + EMail: [email protected] + + + + + + + + + + + + + + + + + + + + + + +Tsou, et al. Standards Track [Page 10] + |