diff options
Diffstat (limited to 'lib/diameter/doc')
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 116 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 34 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_compile.xml | 32 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 5 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_make.xml | 38 | ||||
| -rw-r--r-- | lib/diameter/doc/src/notes.xml | 37 |
6 files changed, 220 insertions, 42 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 379e9f0738..7ea93d480b 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1,5 +1,7 @@ <?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY nodes + '<seealso marker="erts:erlang#nodes-0">erlang:nodes/0</seealso>'> <!ENTITY make_ref '<seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>'> <!ENTITY transport_module @@ -41,7 +43,7 @@ under the License. <approved></approved> <checked></checked> <date></date> -<rev>%VSN%</rev> +<rev></rev> <file>diameter.xml</file> </header> @@ -772,8 +774,8 @@ Application-Id AVP's in particular.</p> | evaluable()}</c></tag> <item> <p> -Specifies the degree to which multiple transport connections to the -same peer are accepted by the service.</p> +Specifies the degree to which the service allows multiple transport +connections to the same peer.</p> <p> If type <c>[node()]</c> then a connection is rejected if another already @@ -819,6 +821,88 @@ non-negative integer less than <c>1 bsl (32-N)</c>.</p> <p> Defaults to <c>{0,32}</c>.</p> + +<warning> +<p> +Multiple Erlang nodes implementing the same Diameter node should +be configured with different sequence masks to ensure that each node +uses a unique range of End-to-End and Hop-by-Hop identifiers for +outgoing requests.</p> +</warning> +</item> + +<tag><c>{share_peers, boolean() | [node()] | evaluable()}</c></tag> +<item> +<p> +Specifies nodes to which peer connections established on the local +Erlang node are communicated. +Shared peers become available in the remote candidates list passed to +&app_pick_peer; callbacks on remote nodes whose services are +configured to use them: see <c>use_shared_peers</c> below.</p> + +<p> +If <c>false</c> then peers are not shared. +If <c>[node()]</c> then peers are shared with the specified list of +nodes. +If <c>evaluable()</c> then peers are shared with the nodes returned +by the specified function, evaluated whenever a peer connection +becomes available or a remote service requests information about local +connections. +The value <c>true</c> is equivalent to <c>fun &nodes;</c>. +The value <c>node()</c> in a node list is ignored, so a collection of +services can all be configured to share with the same list of +nodes.</p> + +<p> +Defaults to <c>false</c>.</p> + +<note> +<p> +Peers are only shared with services of the same name for the purpose +of sending outgoing requests. +Since the value of the &application_opt; <c>alias</c>, passed to +&call;, is the handle for identifying a peer as a suitable +candidate, services that share peers must use the same aliases to +identify their supported applications. +They should typically also configure identical &capabilities;, since +by sharing peer connections they are distributing the implementation +of a single Diameter node across multiple Erlang nodes.</p> +</note> +</item> + +<tag><c>{use_shared_peers, boolean() | [node()] | evaluable()}</c></tag> +<item> +<p> +Specifies nodes from which communicated peers are made available in +the remote candidates list of &app_pick_peer; callbacks.</p> + +<p> +If <c>false</c> then remote peers are not used. +If <c>[node()]</c> then only peers from the specified list of nodes +are used. +If <c>evaluable()</c> then only peers returned by the specified +function are used, evaluated whenever a remote service communicates +information about an available peer connection. +The value <c>true</c> is equivalent to <c>fun &nodes;</c>. +The value <c>node()</c> in a node list is ignored.</p> + +<p> +Defaults to <c>false</c>.</p> + +<note> +<p> +A service that does not use shared peers will always pass the empty +list as the second argument of &app_pick_peer; callbacks.</p> +</note> + +<warning> +<p> +Sending a request over a peer connection on a remote node is less +efficient than sending it over a local connection. +It may be preferable to make use of the &service_opt; +<c>restrict_connections</c> and maintain a dedicated connection on +each node from which requests are sent.</p> +</warning> </item> </taglist> @@ -1078,7 +1162,7 @@ transport.</p> <marker id="transport_config"/> <tag><c>{transport_config, term()}</c></tag> -<tag><c>{transport_config, term(), &dict_Unsigned32;}</c></tag> +<tag><c>{transport_config, term(), &dict_Unsigned32; | infinity}</c></tag> <item> <p> A term passed as the third argument to the &transport_start; function of @@ -1125,6 +1209,30 @@ modules in order until one establishes a connection within the corresponding timeout (see below) or all fail.</p> </item> +<marker id="watchdog_config"/> +<tag><c>{watchdog_config, [{okay|suspect, non_neg_integer()}]}</c></tag> +<item> +<p> +Specifies configuration that alters the behaviour of the watchdog +state machine. +On key <c>okay</c>, the non-negative number of answered DWR +messages before transitioning from REOPEN to OKAY. +On key <c>suspect</c>, the number of watchdog timeouts before +transitioning from OKAY to SUSPECT when DWR is unanswered, or 0 to +not make the transition.</p> + +<p> +Defaults to <c>[{okay, 3}, {suspect, 1}]</c>. +Not specifying a key is equivalent to specifying +the default value for that key.</p> +<warning> +<p> +The default value is as required by RFC 3539: changing it results +in non-standard behaviour that should only be used to simulate +misbehaving nodes during test.</p> +</warning> +</item> + <marker id="watchdog_timer"/> <tag><c>{watchdog_timer, TwInit}</c></tag> <item> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index d0f1b22ebd..d4fb792787 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -37,7 +37,7 @@ under the License. <approved></approved> <checked></checked> <date></date> -<rev>%REV%</rev> +<rev></rev> <file>diameter_app.xml</file> </header> @@ -196,7 +196,8 @@ process.</p> </type> <desc> <p> -Invoked to signal the availability of a peer connection. +Invoked to signal the availability of a peer connection on the local +Erlang node. In particular, capabilities exchange with the peer has indicated support for the application in question, the RFC 3539 watchdog state machine for the connection has reached state <c>OKAY</c> and Diameter @@ -230,8 +231,8 @@ handled independently of &peer_up; and &peer_down;.</p> </type> <desc> <p> -Invoked to signal that a peer connection is no longer available -following a previous call to &peer_up;. +Invoked to signal that a peer connection on the local Erlang node is +no longer available following a previous call to &peer_up;. In particular, that the RFC 3539 watchdog state machine for the connection has left state <c>OKAY</c> and the peer will no longer be a candidate in &pick_peer; callbacks.</p> @@ -240,11 +241,11 @@ candidate in &pick_peer; callbacks.</p> </func> <func> -<name>Mod:pick_peer(Candidates, _Reserved, SvcName, State) +<name>Mod:pick_peer(LocalCandidates, RemoteCandidates, SvcName, State) -> Selection | false</name> <fsummary>Select a target peer for an outgoing request.</fsummary> <type> -<v>Candidates = [&peer;]</v> +<v>LocalCandidates = RemoteCandidates = [&peer;]</v> <v>SvcName = &mod_service_name;</v> <v>State = NewState = &state;</v> <v>Selection = {ok, Peer} | {Peer, NewState}</v> @@ -257,7 +258,7 @@ peer for an outgoing request. The return value indicates the selected peer.</p> <p> -The candidate list contains only those peers that have advertised +The candidate lists contain only those peers that have advertised support for the Diameter application in question during capabilities exchange, that have not be excluded by a <c>filter</c> option in the call to &mod_call; @@ -266,7 +267,11 @@ The order of the elements is unspecified except that any peers whose Origin-Host and Origin-Realm matches that of the outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c> option to &mod_call;) -will be placed at the head of the list.</p> +will be placed at the head of the list. +<c>LocalCandidates</c> contains peers whose transport process resides +on the local Erlang node while +<c>RemoteCandidates</c> contains peers that have been communicated +from other nodes by services of the same name.</p> <p> A callback that returns a peer() will be followed by a @@ -286,16 +291,19 @@ retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.</p> <p> -Returning <c>false</c> or <c>{false, NewState}</c> causes <c>{error, -no_connection}</c> to be returned from &mod_call;.</p> - -<p> The return values <c>false</c> and <c>{false, State}</c> (that is, <c>NewState = State</c>) are equivalent, as are <c>{ok, Peer}</c> and <c>{Peer, State}</c>.</p> <note> <p> +The &mod_service_opt; <c>use_shared_peers</c> determines whether or +not a service uses peers shared from other nodes. +If not then <c>RemoteCandidates</c> is the empty list.</p> +</note> + +<warning> +<p> 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>. @@ -303,7 +311,7 @@ Otherwise, the <c>State</c> argument is always the intial value as configured on the application, not any subsequent value returned by a &peer_up; or &peer_down; callback.</p> -</note> +</warning> </desc> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml index 0bd7ad1789..fc81e4efed 100644 --- a/lib/diameter/doc/src/diameter_compile.xml +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -11,7 +11,7 @@ <comref> <header> <copyright> -<year>2011</year><year>2012</year> +<year>2011</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -59,6 +59,7 @@ The module &man_make; provides an alternate compilation interface.</p> Compile a single dictionary file to Erlang source. Valid options are as follows.</p> +<taglist> <tag><![CDATA[-i <dir>]]></tag> <item> <p> @@ -71,7 +72,6 @@ dependency, not an erl/hrl dependency.</p> Multiple <c>-i</c> options can be specified.</p> </item> -<taglist> <tag><![CDATA[-o <dir>]]></tag> <item> <p> @@ -90,18 +90,30 @@ Supress erl and hrl generation, respectively.</p> <tag><![CDATA[--prefix <prefix>]]></tag> <item> <p> -Set <c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified -string. -Overrides any setting in the file itself.</p> +Transform the input dictionary before compilation, setting +<c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified +string.</p> </item> -<tag><![CDATA[--inherits <dict>]]></tag> +<tag><![CDATA[--inherits <arg>]]></tag> <item> <p> -Append &dict_inherits; of the specified module. -Specifying <c>"-"</c> has the effect of discarding clearing any -previous inherits, both in the dictionary file and on the options -list.</p> +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> + +<pre> +--inherits - +--inherits Prev/Mod +</pre> + +<p> +The first has the effect of clearing any previous inherits, the second +of replacing a previous inherits of <c>Prev</c> to one of <c>Mod</c>. +This allows the semantics of the input dictionary to be changed without +modifying the file itself.</p> <p> Multiple <c>--inherits</c> options can be specified.</p> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 1034781ff2..419dc143af 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -263,15 +263,14 @@ dictionary's definitions but the former makes for easier reuse.</p> <p> All dictionaries should typically inherit &the_rfc; AVPs from -<c>diameter_gen_base_rfc3588</c>.</p> +<c>diameter_gen_base_rfc6733</c>.</p> <p> Example:</p> <pre> -@inherits diameter_gen_base_rfc3588 +@inherits diameter_gen_base_rfc6733 </pre> - </item> <marker id="avp_types"/> diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml index da6124310e..ec71251be1 100644 --- a/lib/diameter/doc/src/diameter_make.xml +++ b/lib/diameter/doc/src/diameter_make.xml @@ -14,6 +14,7 @@ <header> <copyright> <year>2012</year> +<year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -73,7 +74,7 @@ Compile a single dictionary file to Erlang source. <taglist> -<tag><c>{include, Dir::string()}</c></tag> +<tag><c>{include, string()}</c></tag> <item> <p> Prepend the specified directory to the code path. @@ -85,7 +86,7 @@ dependency, not an erl/hrl dependency.</p> Multiple <c>include</c> options can be specified.</p> </item> -<tag><c>{outdir, Dir::string()}</c></tag> +<tag><c>{outdir, string()}</c></tag> <item> <p> Write generated source to the specified directory. @@ -95,18 +96,30 @@ Defaults to the current working directory.</p> <tag><c>{name|prefix, string()}</c></tag> <item> <p> -Set <c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified -string. -Overrides any setting in the file itself.</p> +Transform the input dictionary before compilation, setting +<c>&dict_name;</c> or <c>&dict_prefix;</c> to the specified +string.</p> </item> -<tag><c>{inherits, Mod::string()}</c></tag> +<tag><c>{inherits, string()}</c></tag> <item> <p> -Append &dict_inherits; of the specified module. -Specifying <c>"-"</c> has the effect of discarding clearing any -previous inherits, both in the dictionary file and on the options -list.</p> +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> + +<pre> +{inherits, "-"} +{inherits, "Prev/Mod"} +</pre> + +<p> +The first has the effect of clearing any previous inherits, the second +of replacing a previous inherits of <c>Prev</c> to one of <c>Mod</c>. +This allows the semantics of the input dictionary to be changed without +modifying the file itself.</p> <p> Multiple <c>inherits</c> options can be specified.</p> @@ -126,8 +139,9 @@ Multiple <c>inherits</c> options can be specified.</p> <p> All options are string-valued. -In particular, it is not currently possible to -an &dict_inherits; module as an atom() or a path as a &filename;</p> +In particular, it is not currently possible to specify +an &dict_inherits; module as an atom(), or a path as an arbitrary +&filename;</p> </section> diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index d63e2021c8..2daf84b0d4 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -42,6 +42,43 @@ first.</p> <!-- ===================================================================== --> +<section><title>Diameter 1.4.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix broken Vendor-Specific-Application-Id configuration.</p> + <p> + RFC 6733 changed the definition of this Grouped AVP, + changing the arity of Vendor-Id from 1* to 1. A component + Vendor-Id can now be either list- or integer-valued in + service and transport configuration, allowing it to be + used with both RFC 3588 and RFC 6733 dictionaries.</p> + <p> + Own Id: OTP-10942</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add transport_opt() watchdog_config to allow non-standard + behaviour of the watchdog state machine.</p> + <p> + This can be useful during test but should not be used on + nodes that must conform to RFC 3539.</p> + <p> + Own Id: OTP-10898</p> + </item> + </list> + </section> + +</section> + <section><title>Diameter 1.4.1</title> <section><title>Fixed Bugs and Malfunctions</title> |