From 2ba65b0d81b6a047bed3babf5371e500c1a72541 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 5 Oct 2012 03:09:07 +0200 Subject: Document sequence masks Allow 32-bit Hop-by-Hop and End-to-End identifiers to be modified by replacing the topmost bits with a constant value. This allow services on different nodes to generate globally unique identifiers by having each node mask in its own constant. --- lib/diameter/doc/src/diameter.xml | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index b8652a7482..161fd94d5a 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -699,6 +699,35 @@ the application's dictionary file.

+{sequence, {H,N} | diameter:evaluable()} + +

+Specifies a constant value H for the topmost 32-N 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 +to be evaluated at diameter:start_service/2. +In particular, an identifier Id is mapped to a new identifier +as follows.

+ +(H bsl N) bor (Id band ((1 bsl N) - 1)) + +

+Note that RFC 3588 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 N: +at a rate of R requests per second an N-bit counter +traverses all of its values in (1 bsl N) div (R*60) minutes so +the bound is 4*R*60 =< 1 bsl N.

+ +

N must lie in the range 0..32 and H must be a +non-negative integer less than 1 bsl (32-N).

+ +

+Defaults to {0,32}.

+ + -- cgit v1.2.3 From 0e0d9466b7425f22dc3996bf02229cba01babd12 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Sat, 6 Oct 2012 13:49:36 +0200 Subject: Remove pre-OTP configure support It's neither used nor maintained. --- lib/diameter/doc/.gitignore | 4 ++++ lib/diameter/doc/src/Makefile | 10 +--------- 2 files changed, 5 insertions(+), 9 deletions(-) create mode 100644 lib/diameter/doc/.gitignore (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/.gitignore b/lib/diameter/doc/.gitignore new file mode 100644 index 0000000000..b634bdd7ba --- /dev/null +++ b/lib/diameter/doc/.gitignore @@ -0,0 +1,4 @@ + +/html/ +/man*/ +/pdf/ diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile index 59ca660797..d1d5e8f869 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -16,13 +16,8 @@ # # %CopyrightEnd% -ifneq ($(ERL_TOP),) include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk -else -include $(DIAMETER_TOP)/make/target.mk -include $(DIAMETER_TOP)/make/$(TARGET)/rules.mk -endif include ../../vsn.mk @@ -155,11 +150,8 @@ info: # ---------------------------------------------------- # Release Target # ---------------------------------------------------- -ifneq ($(ERL_TOP),) + include $(ERL_TOP)/make/otp_release_targets.mk -else -include $(DIAMETER_TOP)/make/release_targets.mk -endif release_docs_spec: $(LOCAL)docs $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" -- cgit v1.2.3 From 50b4c459cd99fc2a0dad76741da99d8e1cc1f7f2 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Sat, 6 Oct 2012 19:14:36 +0200 Subject: Clarify diameter_transport doc --- lib/diameter/doc/src/diameter_transport.xml | 42 +++++++++++++++++------------ 1 file changed, 25 insertions(+), 17 deletions(-) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index 9ab750e560..d9b36a1e09 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -54,14 +54,14 @@ parent).

-Mod:start({Type, Ref}, Svc, Opts) +Mod:start({Type, Ref}, Svc, Config) -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason} Start a transport process. Type = connect | accept Ref = diameter:transport_ref() Svc = #diameter_service{} -Opts = term() +Config = term() Pid = pid() LAddrs = [inet:ip_address()] Reason = term() @@ -75,38 +75,46 @@ order to establish or accept a transport connection respectively. A transport process maintains a connection with a single remote peer.

-The first argument indicates whether the transport process in question +Type indicates whether the transport process in question is being started for a connecting (connect) or listening (accept) transport. In the latter case, transport processes are started as required to -accept connections from multiple peers. -Ref is in each case the same value that was returned from the -call to diameter:add_transport/2 -that has lead to starting of a transport process.

+accept connections from multiple peers.

-A transport process must implement the message interface documented below. -It should retain the pid of its parent, monitor the parent and terminate if -it dies. -It should not link to the parent. -It should exit if its transport connection with its peer is lost.

+Ref is the value that was returned from the call to diameter:add_transport/2 +that has lead to starting of a transport process.

-The capabilities in the #diameter_service{} record are as -passed to Svc contains the capabilities passed to diameter:start_service/2 and diameter:add_transport/2, -values passed to the latter overriding those passed to the former. +values passed to the latter overriding those passed to the former.

+ +

+Config is as passed in transport_config tuple in the +diameter:transport_opt() +list passed to diameter:add_transport/2.

+ +

The start function should use the Host-IP-Address list and/or -Opts to select an appropriate list of local IP addresses, +Config to select an appropriate list of local IP addresses, and should return this list if different from the #diameter_service{} addresses. The returned list is used to populate Host-IP-Address AVPs in outgoing capabilities exchange messages, the #diameter_service{} addresses being used otherwise.

+

+A transport process must implement the message interface documented below. +It should retain the pid of its parent, monitor the parent and terminate if +it dies. +It should not link to the parent. +It should exit if its transport connection with its peer is lost.

+ -- cgit v1.2.3 From f3ea0395506e7e80f9efb53d8c96c28bd288a066 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Mon, 1 Oct 2012 09:52:49 +0200 Subject: Document service_opt() restrict_connections Configuration will allow relaxation of the guard against multiple transport connections to the same peer. --- lib/diameter/doc/src/diameter.xml | 42 +++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 161fd94d5a..b7936dbacc 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -375,10 +375,15 @@ is meant in the sense of eval([E|A]).

-Beware of using fun expressions of the form fun Name/Arity (not -fun Mod:Name/Arity) in situations in which the fun is not short-lived +Beware of using fun expressions of the form fun Name/Arity in +situations in which the fun is not short-lived and code is to be upgraded at runtime since any processes retaining -such a fun will have a reference to old code.

+such a fun will have a reference to old code. +In particular, such a value is typically inappropriate in +configuration passed to start_service/2 or +add_transport/2.

 @@ -699,6 +704,35 @@ the application's dictionary file.

+{restrict_connections, false + | node + | nodes + | [node()] + | diameter:evaluable()} + +

+Specifies the degree to which multiple transport connections to the +same peer are accepted by the service.

+ +

+If type [node()] then a connection is rejected if another already +exists on any of the specified nodes. +Values of type false, node, nodes or +diameter:evaluable() are equivalent to values [], +[node()], [node()|nodes()] and the evaluated value, +respectively, evaluation of each expression taking place whenever a +new connection is to be established. +Note that false allows an unlimited number of connections to be +established with the same peer.

+ +

+Multiple connections are independent and governed +by their own peer and watchdog state machines.

+ +

+Defaults to nodes.

+ + {sequence, {H,N} | diameter:evaluable()} @@ -879,7 +913,7 @@ reconnection attempts, as required by RFC 3539.

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 OPEN rather than +causing the RFC 3539 state machine to pass to state OKAY rather than REOPEN. Note that these semantics are not goverened by the RFC and that a listening transport's reconnect_timer should be greater -- cgit v1.2.3 From e18806dce4e043837efb1ddd5e6e31b4237e618a Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 11 Oct 2012 02:07:00 +0200 Subject: Document peer_ref() service_info --- lib/diameter/doc/src/diameter.xml | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) (limited to 'lib/diameter/doc') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index b7936dbacc..80863f8eff 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1212,6 +1212,12 @@ DPA or timeout.

Return information about a started service. +Requesting info for an unknown service causes undefined to be +returned. +Requesting a list of items causes a tagged list to be +returned.

+ +

Item can be one of the following.

@@ -1482,13 +1488,27 @@ The Diameter-level statistics returned by transport and connections info are based upon these entries.

 - - +diameter_app:peer_ref() +

-Requesting info for an unknown service causes undefined to be -returned. -Requesting a list of items causes a tagged list to be -returned.

+Return transport configuration associated with a single peer, as +passed to add_transport/2. +The returned list is empty if the peer is unknown. +Otherwise it contains the ref, type and options +tuples as in transport and connections info above. +For example:

+ + +[{ref,#Ref<0.0.0.61>}, + {type,accept}, + {options,[{transport_module,diameter_tcp}, + {transport_config,[{reuseaddr,true}, + {ip,{127,0,0,1}}, + {port,3868}]}]}] + + + + -- cgit v1.2.3