1diameter(3)                Erlang Module Definition                diameter(3)
2
3
4

NAME

6       diameter - Main API of the diameter application.
7

DESCRIPTION

9       This  module  provides  the interface with which a user can implement a
10       Diameter node that sends and receives messages using the Diameter  pro‐
11       tocol as defined in RFC 6733.
12
13       Basic  usage  consists of creating a representation of a locally imple‐
14       mented Diameter node and its capabilities with start_service/2,  adding
15       transport   capability   using  add_transport/2  and  sending  Diameter
16       requests and receiving Diameter answers with call/4. Incoming  Diameter
17       requests  are  communicated  as callbacks to a diameter_app(3) callback
18       modules as specified in the service configuration.
19
20       Beware the difference between diameter (not capitalized)  and  Diameter
21       (capitalized). The former refers to the Erlang application named diame‐
22       ter whose main api is defined here, the latter to Diameter protocol  in
23       the sense of RFC 6733.
24
25       The  diameter application must be started before calling most functions
26       in this module.
27

DATA TYPES

29         Address():
30
31
32         DiameterIdentity():
33
34
35         Grouped():
36
37
38         OctetString():
39
40
41         Time():
42
43
44         Unsigned32():
45
46
47         UTF8String():
48           Types corresponding to RFC 6733 AVP Data Formats. Defined in diame‐
49           ter_dict(4).
50
51         application_alias() = term():
52           Name  identifying  a Diameter application in service configuration.
53           Passed to call/4 when sending requests defined by the application.
54
55         application_module() = Mod |  [Mod  |  ExtraArgs]  |  #diameter_call‐
56         back{}:
57
58
59         Mod = atom()
60         ExtraArgs = list()
61
62
63           Module  implementing  the  callback  interface  defined  in  diame‐
64           ter_app(3), along with any extra arguments to be appended to  those
65           documented.  Note  that  extra  arguments  specific  to an outgoing
66           request can be  specified  to  call/4,  in  which  case  those  are
67           appended to any module-specific extra arguments.
68
69           Specifying  a  #diameter_callback{}  record allows individual func‐
70           tions to be configured in place of the usual diameter_app(3)  call‐
71           backs. See diameter_callback.erl for details.
72
73         application_opt():
74           Options  defining  a Diameter application. Has one of the following
75           types.
76
77           {alias, application_alias()}:
78             Unique identifier for the application in the scope  of  the  ser‐
79             vice. Defaults to the value of the dictionary option.
80
81           {dictionary, atom()}:
82             Name of an encode/decode module for the Diameter messages defined
83             by the application. These modules are generated from files  whose
84             format is documented in diameter_dict(4).
85
86           {module, application_module()}:
87             Callback module in which messages of the Diameter application are
88             handled. See  diameter_app(3)  for  the  required  interface  and
89             semantics.
90
91           {state, term()}:
92             Initial  callback  state.  The prevailing state is passed to some
93             diameter_app(3) callbacks, which can then  return  a  new  state.
94             Defaults to the value of the alias option.
95
96           {call_mutates_state, true|false}:
97             Whether  or  not  the pick_peer/4 application callback can modify
98             the application state. Defaults to false.
99
100       Warning:
101           pick_peer/4 callbacks are serialized  when  this  option  is  true,
102           which  is  a  potential  performance  bottleneck. A simple Diameter
103           client may suffer no ill effects from using  mutable  state  but  a
104           server  or  agent that responds to incoming request should probably
105           avoid it.
106
107
108           {answer_errors, callback|report|discard}:
109             Manner in which incoming answer messages containing decode errors
110             are handled.
111
112             If  callback  then errors result in a handle_answer/4 callback in
113             the same fashion as for handle_request/3,  with  errors  communi‐
114             cated in the errors field of the #diameter_packet{} passed to the
115             callback. If report then an answer containing errors is discarded
116             without a callback and a warning report is written to the log. If
117             discard then an answer containing errors  is  silently  discarded
118             without  a  callback.  In  both  the report and discard cases the
119             return value for the call/4 invocation in question  is  as  if  a
120             callback had taken place and returned {error, failure}.
121
122             Defaults to discard.
123
124           {request_errors, answer_3xxx|answer|callback}:
125             Manner in which incoming requests are handled when an error other
126             than  3007  (DIAMETER_APPLICATION_UNSUPPORTED,  which  cannot  be
127             associated with an application callback module), is detected.
128
129             If   answer_3xxx  then  requests  are  answered  without  a  han‐
130             dle_request/3 callback taking place. If  answer  then  even  5xxx
131             errors  are  answered without a callback unless the connection in
132             question has configured the RFC 3588 common dictionary  as  noted
133             below.  If callback then a handle_request/3 callback always takes
134             place and its return value determines  the  answer  sent  to  the
135             peer, if any.
136
137             Defaults to answer_3xxx.
138
139       Note:
140           Answers  sent  by  diameter  set  the E-bit in the Diameter Header.
141           Since RFC 3588 allows only 3xxx result codes in an  answer-message,
142           answer  has the same semantics as answer_3xxx when the transport in
143           question has been configured with diameter_gen_base_rfc3588 as  its
144           common  dictionary. Since RFC 6733 allows both 3xxx and 5xxx result
145           codes   in   an   answer-message,   a   transport    with    diame‐
146           ter_gen_base_rfc6733  as  its  common  dictionary  does distinguish
147           between answer_3xxx and answer.
148
149
150         call_opt():
151           Options available to  call/4  when  sending  an  outgoing  Diameter
152           request. Has one of the following types.
153
154           {extra, list()}:
155             Extra  arguments to append to callbacks to the callback module in
156             question. These are appended to any extra arguments configured on
157             the  callback  itself.  Multiple  options  append to the argument
158             list.
159
160           {filter, peer_filter()}:
161             Filter to apply to the list of available peers before passing  it
162             to the pick_peer/4 callback for the application in question. Mul‐
163             tiple options are equivalent a single all filter  on  the  corre‐
164             sponding list of filters. Defaults to none.
165
166           {peer, diameter_app:peer_ref()}:
167             Peer to which the request in question can be sent, preempting the
168             selection of peers having advertised  support  for  the  Diameter
169             application  in  question. Multiple options can be specified, and
170             their order is respected in the candidate lists passed to a  sub‐
171             sequent pick_peer/4 callback.
172
173           {timeout, Unsigned32()}:
174             Number  of  milliseconds  after which the request should timeout.
175             Defaults to 5000.
176
177           detach:
178             Cause call/4 to return ok as soon as the request in question  has
179             been  encoded,  instead  of  waiting for and returning the result
180             from a subsequent handle_answer/4 or handle_error/4 callback.
181
182           An invalid option will cause call/4 to fail.
183
184         capability():
185           AVP values sent in outgoing CER or CEA messages during capabilities
186           exchange. Can be configured both on a service and a transport, val‐
187           ues on the latter taking  precedence.  Has  one  of  the  following
188           types.
189
190           {'Origin-Host', DiameterIdentity()}:
191
192
193           {'Origin-Realm', DiameterIdentity()}:
194
195
196           {'Host-IP-Address', [Address()]}:
197             An address list is available to the start function of a transport
198             module, which can return a new list for use in the subsequent CER
199             or  CEA.  Host-IP-Address  need not be specified if the transport
200             module in question communicates an address list as  described  in
201             diameter_transport(3)
202
203           {'Vendor-Id', Unsigned32()}:
204
205
206           {'Product-Name', UTF8String()}:
207
208
209           {'Origin-State-Id', Unsigned32()}:
210             Origin-State-Id  is optional but, if configured, will be included
211             in outgoing CER/CEA and DWR/DWA messages. Setting a  value  of  0
212             (zero) is equivalent to not setting a value, as documented in RFC
213             6733. The function origin_state_id/0 can be used as to retrieve a
214             value that is computed when the diameter application is started.
215
216           {'Supported-Vendor-Id', [Unsigned32()]}:
217
218
219           {'Auth-Application-Id', [Unsigned32()]}:
220
221
222           {'Inband-Security-Id', [Unsigned32()]}:
223             Inband-Security-Id  defaults  to the empty list, which is equiva‐
224             lent to a list containing only 0 (NO_INBAND_SECURITY). If 1 (TLS)
225             is  specified  then  TLS is selected if the CER/CEA received from
226             the peer offers it.
227
228           {'Acct-Application-Id', [Unsigned32()]}:
229
230
231           {'Vendor-Specific-Application-Id', [Grouped()]}:
232
233
234           {'Firmware-Revision', Unsigned32()}:
235
236
237           Note that each tuple communicates one or more AVP values. It is  an
238           error to specify duplicate tuples.
239
240         eval() = {M,F,A} | fun() | [eval() | A]:
241           An  expression that can be evaluated as a function in the following
242           sense.
243
244         eval([{M,F,A} | T]) ->
245             apply(M, F, T ++ A);
246         eval([[F|A] | T]) ->
247             eval([F | T ++ A]);
248         eval([F|A]) ->
249             apply(F, A);
250         eval(F) ->
251             eval([F]).
252
253
254           Applying an eval() E to an argument list A is meant in the sense of
255           eval([E|A]).
256
257     Warning:
258         Beware  of using fun expressions of the form fun Name/Arity in situa‐
259         tions in which the fun is not short-lived and code is to be  upgraded
260         at  runtime since any processes retaining such a fun will have a ref‐
261         erence to old code. In particular, such a value is typically inappro‐
262         priate in configuration passed to start_service/2 or add_transport/2.
263
264
265         peer_filter() = term():
266           Filter  passed  to  call/4 in order to select candidate peers for a
267           pick_peer/4 callback. Has one of the following types.
268
269           none:
270             Matches any peer. This is a convenience that  provides  a  filter
271             equivalent to no filter.
272
273           host:
274             Matches  only those peers whose Origin-Host has the same value as
275             Destination-Host in the outgoing request in question, or any peer
276             if the request does not contain a Destination-Host AVP.
277
278           realm:
279             Matches only those peers whose Origin-Realm has the same value as
280             Destination-Realm in the outgoing request  in  question,  or  any
281             peer if the request does not contain a Destination-Realm AVP.
282
283           {host, any|DiameterIdentity()}:
284             Matches  only  those  peers  whose  Origin-Host has the specified
285             value, or all peers if the atom any.
286
287           {realm, any|DiameterIdentity()}:
288             Matches only those peers whose  Origin-Realm  has  the  specified
289             value, or all peers if the atom any.
290
291           {eval, eval()}:
292             Matches  only  those peers for which the specified eval() returns
293             true when applied to the connection's diameter_caps  record.  Any
294             other return value or exception is equivalent to false.
295
296           {neg, peer_filter()}:
297             Matches only those peers not matched by the specified filter.
298
299           {all, [peer_filter()]}:
300             Matches  only those peers matched by each filter in the specified
301             list.
302
303           {any, [peer_filter()]}:
304             Matches only those peers matched by at least one  filter  in  the
305             specified  list. The resulting list will be in match order, peers
306             matching the first  filter  of  the  list  sorting  before  those
307             matched by the second, and so on.
308
309           {first, [peer_filter()]}:
310             Like  any,  but  stops  at  the  first filter for which there are
311             matches, which can be much more efficient  when  there  are  many
312             peers.  For  example, the following filter causes only peers best
313             matching both the host and realm filters to be presented.
314
315           {first, [{all, [host, realm]}, realm]}
316
317
318           An invalid filter is equivalent to {any,[]}, a filter that  matches
319           no peer.
320
321     Note:
322         The  host  and  realm filters cause the Destination-Host and Destina‐
323         tion-Realm AVPs to be extracted from the outgoing  request,  assuming
324         it  to  be  a  record-  or  list-valued diameter_codec:message(), and
325         assuming at most one of each AVP. If this is not the  case  then  the
326         {host|realm,  DiameterIdentity()} filters must be used to achieve the
327         desired result. An empty DiameterIdentity() (which should not be typ‐
328         ical) matches all hosts/realms for the purposes of filtering.
329
330
331     Warning:
332         A  host  filter  is not typically desirable when setting Destination-
333         Host since it will remove peer agents from the candidates list.
334
335
336         service_event() = #diameter_event{service =  service_name(),  info  =
337         service_event_info()}:
338           An  event  message  sent to processes that have subscribed to these
339           using subscribe/1.
340
341         service_event_info() = term():
342           The info field of a service_event() record. Can  have  one  of  the
343           following types.
344
345           start:
346
347
348           stop:
349             The  service  is  being  started  or stopped. No event precedes a
350             start event. No event  follows  a  stop  event,  and  this  event
351             implies the termination of all transport processes.
352
353           {up, Ref, Peer, Config, Pkt}:
354
355
356           {up, Ref, Peer, Config}:
357
358
359           {down, Ref, Peer, Config}:
360
361
362           Ref    = transport_ref()
363           Peer   = diameter_app:peer()
364           Config = {connect|listen, [transport_opt()]}
365           Pkt    = #diameter_packet{}
366
367
368             The RFC 3539 watchdog state machine has transitioned into (up) or
369             out of (down) the OKAY state. If a #diameter_packet{} is  present
370             in  an  up event then there has been a capabilities exchange on a
371             newly established transport connection and  the  record  contains
372             the received CER or CEA.
373
374             Note  that a single up or down event for a given peer corresponds
375             to multiple peer_up/3 or peer_down/3 callbacks, one for  each  of
376             the   Diameter   applications   negotiated   during  capabilities
377             exchange. That is, the event communicates connectivity  with  the
378             peer as a whole while the callbacks communicate connectivity with
379             respect to individual Diameter applications.
380
381           {reconnect, Ref, Opts}:
382
383
384           Ref  = transport_ref()
385           Opts = [transport_opt()]
386
387
388             A connecting transport is attempting to  establish/reestablish  a
389             transport  connection  with  a  peer  following  connect_timer or
390             watchdog_timer expiry.
391
392           {closed, Ref, Reason, Config}:
393
394
395           Ref = transport_ref()
396           Config = {connect|listen, [transport_opt()]}
397
398
399             Capabilities exchange has failed. Reason can have one of the fol‐
400             lowing types.
401
402             {'CER', Result, Caps, Pkt}:
403
404
405             Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
406             Caps = #diameter_caps{}
407             Pkt  = #diameter_packet{}
408             ResultCode = integer()
409             CB = eval()
410
411
412               An  incoming  CER  has  been answered with the indicated result
413               code, or discarded. Caps contains  pairs  of  values,  for  the
414               local  node  and remote peer respectively. Pkt contains the CER
415               in question. In the case of rejection by a  capabilities  call‐
416               back, the tuple contains the rejecting callback.
417
418             {'CER', Caps, {ResultCode, Pkt}}:
419
420
421             ResultCode = integer()
422             Caps = #diameter_caps{}
423             Pkt  = #diameter_packet{}
424
425
426               An incoming CER contained errors and has been answered with the
427               indicated result code. Caps contains values for the local  node
428               only. Pkt contains the CER in question.
429
430             {'CER', timeout}:
431               An expected CER was not received within capx_timeout of connec‐
432               tion establishment.
433
434             {'CEA', Result, Caps, Pkt}:
435
436
437             Result = ResultCode | atom() | {capabilities_cb, CB, ResultCode|discard}
438             Caps = #diameter_caps{}
439             Pkt  = #diameter_packet{}
440             ResultCode = integer()
441
442
443               An incoming CEA has been rejected for the indicated reason.  An
444               integer-valued  Result  indicates  the  result code sent by the
445               peer. Caps contains pairs of values  for  the  local  node  and
446               remote  peer.  Pkt contains the CEA in question. In the case of
447               rejection by a capabilities callback, the  tuple  contains  the
448               rejecting callback.
449
450             {'CEA', Caps, Pkt}:
451
452
453             Caps = #diameter_caps{}
454             Pkt  = #diameter_packet{}
455
456
457               An  incoming  CEA  contained errors and has been rejected. Caps
458               contains only values for the local node. Pkt contains  the  CEA
459               in question.
460
461             {'CEA', timeout}:
462               An expected CEA was not received within capx_timeout of connec‐
463               tion establishment.
464
465           {watchdog, Ref, PeerRef, {From, To}, Config}:
466
467
468           Ref = transport_ref()
469           PeerRef = diameter_app:peer_ref()
470           From, To = initial | okay | suspect | down | reopen
471           Config = {connect|listen, [transport_opt()]}
472
473
474             An RFC 3539 watchdog state machine has changed state.
475
476           any():
477             For forward compatibility, a subscriber  should  be  prepared  to
478             receive info fields of forms other than the above.
479
480         service_name() = term():
481           Name  of  a service as passed to start_service/2 and with which the
482           service is identified. There can be at  most  one  service  with  a
483           given name on a given node. Note that erlang:make_ref/0 can be used
484           to generate a service name that is somewhat unique.
485
486         service_opt():
487           Option passed to start_service/2. Can be any capability()  as  well
488           as the following.
489
490           {application, [application_opt()]}:
491             A Diameter application supported by the service.
492
493             A  service must configure one tuple for each Diameter application
494             it intends to support. For  an  outgoing  request,  the  relevant
495             application_alias()  is  passed  to call/4, while for an incoming
496             request the application identifier in the message  header  deter‐
497             mines  the  application,  the  identifier  being specified in the
498             application's dictionary file.
499
500       Warning:
501           The capabilities advertised by a node  must  match  its  configured
502           applications.  In  particular,  application  configuration  must be
503           matched by corresponding capability() configuration, of  *-Applica‐
504           tion-Id AVPs in particular.
505
506
507           {decode_format, record | list | map | none}:
508             The  format of decoded messages and grouped AVPs in the msg field
509             of  diameter_packet  records  and  value  field  of  diameter_avp
510             records respectively. If record then a record whose definition is
511             generated from the dictionary file in question. If  list  or  map
512             then a [Name | Avps] pair where Avps is a list of AVP name/values
513             pairs or a map keyed on AVP names respectively. If none then  the
514             atom-value message name, or undefined for a Grouped AVP. See also
515             diameter_codec:message().
516
517             Defaults to record.
518
519       Note:
520           AVPs are decoded into a list of diameter_avp records in avps  field
521           of diameter_packet records independently of decode_format.
522
523
524           {restrict_connections, false | node | nodes | [node()] | eval()}:
525             The degree to which the service allows multiple transport connec‐
526             tions to the same peer, as identified by its Origin-Host at capa‐
527             bilities exchange.
528
529             If  [node()]  then  a  connection  is rejected if another already
530             exists on any of the specified nodes. Types  false,  node,  nodes
531             and  eval()  are equivalent to [], [node()], [node()|nodes()] and
532             the evaluated value respectively, evaluation of  each  expression
533             taking place whenever a new connection is to be established. Note
534             that false allows an unlimited number of connections to be estab‐
535             lished with the same peer.
536
537             Multiple  connections  are  independent and governed by their own
538             peer and watchdog state machines.
539
540             Defaults to nodes.
541
542           {sequence, {H,N} | eval()}:
543             A constant value H for the topmost 32-N bits of of 32-bit End-to-
544             End  and  Hop-by-Hop Identifiers generated by the service, either
545             explicitly or as a return value of a function to be evaluated  at
546             start_service/2.  In  particular, an identifier Id is mapped to a
547             new identifier as follows.
548
549           (H bsl N) bor (Id band ((1 bsl N) - 1))
550
551
552             Note that RFC 6733 requires that  End-to-End  Identifiers  remain
553             unique  for  a period of at least 4 minutes and that this and the
554             call rate places a lower bound on appropriate values of N:  at  a
555             rate  of R requests per second, an N-bit counter traverses all of
556             its values in (1 bsl N) div  (R*60)  minutes,  so  the  bound  is
557             4*R*60 =< 1 bsl N.
558
559             N  must lie in the range 0..32 and H must be a non-negative inte‐
560             ger less than 1 bsl (32-N).
561
562             Defaults to {0,32}.
563
564       Warning:
565           Multiple Erlang nodes implementing the same Diameter node should be
566           configured  with  different sequence masks to ensure that each node
567           uses a unique range of End-to-End and  Hop-by-Hop  Identifiers  for
568           outgoing requests.
569
570
571           {share_peers, boolean() | [node()] | eval()}:
572             Nodes  to  which peer connections established on the local Erlang
573             node are communicated.  Shared  peers  become  available  in  the
574             remote  candidates list passed to pick_peer/4 callbacks on remote
575             nodes  whose  services  are   configured   to   use   them:   see
576             use_shared_peers below.
577
578             If  false  then  peers are not shared. If [node()] then peers are
579             shared with the specified list of nodes. If eval() then peers are
580             shared  with the nodes returned by the specified function, evalu‐
581             ated whenever a peer connection becomes  available  or  a  remote
582             service  requests  information about local connections. The value
583             true is equivalent to fun erlang:nodes/0. The value node()  in  a
584             list  is  ignored, so a collection of services can all be config‐
585             ured to share with the same list of nodes.
586
587             Defaults to false.
588
589       Note:
590           Peers are only shared with services of the same name for  the  pur‐
591           pose  of sending outgoing requests. Since the value of the applica‐
592           tion_opt() alias, passed to call/4, is the handle for identifying a
593           peer  as  a  suitable candidate, services that share peers must use
594           the same aliases to identify  their  supported  applications.  They
595           should  typically also configure identical capabilities(), since by
596           sharing peer connections they are distributing  the  implementation
597           of a single Diameter node across multiple Erlang nodes.
598
599
600           {strict_arities, boolean() | encode | decode}:
601             Whether or not to require that the number of AVPs in a message or
602             grouped AVP agree with those specified in the dictionary in ques‐
603             tion  when passing messages to diameter_app(3) callbacks. If true
604             then mismatches in an outgoing messages cause message encoding to
605             fail,  while  mismatches  in  an incoming message are reported as
606             5005/5009 errors in  the  errors  field  of  the  diameter_packet
607             record  passed  to handle_request/3 or handle_answer/4 callbacks.
608             If false then neither error is enforced/detected.  If  encode  or
609             decode  then  errors  are  only  enforced/detected on outgoing or
610             incoming messages respectively.
611
612             Defaults to true.
613
614       Note:
615           Disabling  arity  checks  affects   the   form   of   messages   at
616           encode/decode. In particular, decoded AVPs are represented as lists
617           of values, regardless of the AVP's arity (ie.  expected  number  in
618           the message/AVP grammar in question), and values are expected to be
619           supplied as lists at encode. This differs from the historic  decode
620           behaviour  of  representing  AVPs  of  arity  1 as bare values, not
621           wrapped in a list.
622
623
624           {string_decode, boolean()}:
625             Whether or not to decode  AVPs  of  type  OctetString()  and  its
626             derived  types DiameterIdentity(), DiameterURI(), IPFilterRule(),
627             QoSFilterRule(), and UTF8String(). If true  then  AVPs  of  these
628             types  are decoded to string(). If false then values are retained
629             as binary().
630
631             Defaults to true.
632
633       Warning:
634           This option should be set to false since a  sufficiently  malicious
635           peer  can  otherwise  cause  large amounts of memory to be consumed
636           when decoded Diameter messages are passed  between  processes.  The
637           default value is for backwards compatibility.
638
639
640           {traffic_counters, boolean()}:
641             Whether  or not to count application-specific messages; those for
642             which diameter_app(3) callbacks take place. If  false  then  only
643             messages   handled  by  diameter  itself  are  counted:  CER/CEA,
644             DWR/DWA, DPR/DPA.
645
646             Defaults to true.
647
648       Note:
649           Disabling counters is a performance improvement, but means that the
650           omitted counters are not returned by service_info/2.
651
652
653           {use_shared_peers, boolean() | [node()] | eval()}:
654             Nodes  from  which  communicated  peers are made available in the
655             remote candidates list of pick_peer/4 callbacks.
656
657             If false then remote peers are not used. If  [node()]  then  only
658             peers  from  the specified list of nodes are used. If eval() then
659             only peers returned by the specified function are used, evaluated
660             whenever  a  remote  service  communicates  information  about an
661             available peer connection. The value true is  equivalent  to  fun
662             erlang:nodes/0. The value node() in a list is ignored.
663
664             Defaults to false.
665
666       Note:
667           A service that does not use shared peers will always pass the empty
668           list as the second argument of pick_peer/4 callbacks.
669
670
671       Warning:
672           Sending a request over a peer connection on a remote node  is  less
673           efficient  than  sending  it  over  a  local  connection. It may be
674           preferable to make use of  the  service_opt()  restrict_connections
675           and  maintain  a  dedicated  connection  on  each  node  from which
676           requests are sent.
677
678
679           transport_opt():
680             Any transport option except  applications,  capabilities,  trans‐
681             port_config, and transport_module. Used as defaults for transport
682             configuration, values passed to add_transport/2 overriding values
683             configured on the service.
684
685         transport_opt():
686           Option passed to add_transport/2. Has one of the following types.
687
688           {applications, [application_alias()]}:
689             Diameter   applications   to   which   the  transport  should  be
690             restricted. Defaults to all applications configured on  the  ser‐
691             vice  in  question. Applications not configured on the service in
692             question are ignored.
693
694       Warning:
695           The capabilities advertised by a node  must  match  its  configured
696           applications.  In  particular,  setting applications on a transport
697           typically implies having to set matching *-Application-Id AVPs in a
698           capabilities() tuple.
699
700
701           {avp_dictionaries, [module()]}:
702             A   list   of   alternate   dictionary   modules  with  which  to
703             encode/decode AVPs that are not defined by the dictionary of  the
704             application  in question. At decode, such AVPs are represented as
705             diameter_avp records in the 'AVP' field of a decoded  message  or
706             Grouped  AVP,  the  first alternate that succeeds in decoding the
707             AVP setting the record's value field. At  encode,  values  in  an
708             'AVP' list can be passed as AVP name/value 2-tuples, and it is an
709             encode error for no alternate to define the AVP of such a tuple.
710
711             Defaults to the empty list.
712
713       Note:
714           The motivation for alternate dictionaries  is  RFC  7683,  Diameter
715           Overload  Indication  Conveyance  (DOIC),  which defines AVPs to be
716           piggybacked onto existing application messages rather than defining
717           an  application  of its own. The DOIC dictionary is provided by the
718           diameter  application,  as  module  diameter_gen_doic_rfc7683,  but
719           alternate dictionaries can be used to encode/decode any set of AVPs
720           not known to an application dictionary.
721
722
723           {capabilities, [capability()]}:
724             AVPs used to construct outgoing  CER/CEA  messages.  Values  take
725             precedence over any specified on the service in question.
726
727             Specifying a capability as a transport option may be particularly
728             appropriate for Inband-Security-Id, in case TLS is  desired  over
729             TCP as implemented by diameter_tcp(3).
730
731           {capabilities_cb, eval()}:
732             Callback  invoked  upon  reception of CER/CEA during capabilities
733             exchange in order to ask whether or not the connection should  be
734             accepted.  Applied  to  the  transport_ref() and #diameter_caps{}
735             record of the connection.
736
737             The return value can have one of the following types.
738
739             ok:
740               Accept the connection.
741
742             integer():
743               Causes an incoming  CER  to  be  answered  with  the  specified
744               Result-Code.
745
746             discard:
747               Causes an incoming CER to be discarded without CEA being sent.
748
749             unknown:
750               Equivalent to returning 3010, DIAMETER_UNKNOWN_PEER.
751
752             Returning anything but ok or a 2xxx series result code causes the
753             transport  connection  to  be  broken.  Multiple  capabilities_cb
754             options  can  be specified, in which case the corresponding call‐
755             backs are applied until either all return ok or one does not.
756
757           {capx_timeout, Unsigned32()}:
758             Number of milliseconds after which a transport process having  an
759             established  transport  connection  will  be  terminated  if  the
760             expected capabilities  exchange  message  (CER  or  CEA)  is  not
761             received from the peer. For a connecting transport, the timing of
762             connection  attempts  is  governed  by  connect_timer  or  watch‐
763             dog_timer  expiry. For a listening transport, the peer determines
764             the timing.
765
766             Defaults to 10000.
767
768           {connect_timer, Tc}:
769
770
771           Tc = Unsigned32()
772
773
774             For a connecting transport, the RFC 6733 Tc timer,  in  millisec‐
775             onds.  This timer determines the frequency with which a transport
776             attempts to establish an initial connection with its peer follow‐
777             ing  transport configuration. Once an initial connection has been
778             established, watchdog_timer determines the frequency of reconnec‐
779             tion attempts, as required by RFC 3539.
780
781             For  a  listening  transport,  the timer specifies the time after
782             which a previously connected peer will be forgotten: a connection
783             after  this time is regarded as an initial connection rather than
784             reestablishment, causing the RFC 3539 state machine  to  pass  to
785             state  OKAY rather than REOPEN. Note that these semantics are not
786             governed by  the  RFC  and  that  a  listening  transport's  con‐
787             nect_timer should be greater than its peer's Tw plus jitter.
788
789             Defaults to 30000 for a connecting transport and 60000 for a lis‐
790             tening transport.
791
792           {disconnect_cb, eval()}:
793             Callback invoked prior to terminating the transport process of  a
794             transport  connection  having  watchdog  state  OKAY.  Applied to
795             application|service|transport and the transport_ref() and  diame‐
796             ter_app:peer() in question: application indicates that the diame‐
797             ter application is being stopped, service  that  the  service  in
798             question  is  being stopped by stop_service/1, and transport that
799             the transport in question is being removed by remove_transport/2.
800
801             The return value can have one of the following types.
802
803             {dpr, [option()]}:
804               Send Disconnect-Peer-Request to the peer, the transport process
805               being  terminated following reception of Disconnect-Peer-Answer
806               or timeout. An option() can be one of the following.
807
808               {cause, 0|rebooting|1|busy|2|goaway}:
809                 Disconnect-Cause    to    send,    REBOOTING,    BUSY     and
810                 DO_NOT_WANT_TO_TALK_TO_YOU  respectively. Defaults to reboot‐
811                 ing  for  Reason=service|application  and  goaway  for   Rea‐
812                 son=transport.
813
814               {timeout, Unsigned32()}:
815                 Number  of  milliseconds after which the transport process is
816                 terminated if DPA has not  been  received.  Defaults  to  the
817                 value of dpa_timeout.
818
819             dpr:
820               Equivalent to {dpr, []}.
821
822             close:
823               Terminate the transport process without Disconnect-Peer-Request
824               being sent to the peer.
825
826             ignore:
827               Equivalent to not having configured the callback.
828
829             Multiple disconnect_cb options can be specified,  in  which  case
830             the corresponding callbacks are applied until one of them returns
831             a value other than ignore.  All  callbacks  returning  ignore  is
832             equivalent to not having configured them.
833
834             Defaults to a single callback returning dpr.
835
836           {dpa_timeout, Unsigned32()}:
837             Number of milliseconds after which a transport connection is ter‐
838             minated following an outgoing DPR if DPA is not received.
839
840             Defaults to 1000.
841
842           {dpr_timeout, Unsigned32()}:
843             Number of milliseconds after which a transport connection is ter‐
844             minated  following an incoming DPR if the peer does not close the
845             connection.
846
847             Defaults to 5000.
848
849           {incoming_maxlen, 0..16777215}:
850             Bound on the expected size of incoming  Diameter  messages.  Mes‐
851             sages larger than the specified number of bytes are discarded.
852
853             Defaults  to  16777215,  the  maximum value of the 24-bit Message
854             Length field in a Diameter Header.
855
856           {length_errors, exit|handle|discard}:
857             How to deal with errors in the Message Length field of the Diame‐
858             ter  Header  in  an incoming message. An error in this context is
859             that the length is not  at  least  20  bytes  (the  length  of  a
860             Header),  is  not  a multiple of 4 (a valid length) or is not the
861             length of the message in question, as received over the transport
862             interface documented in diameter_transport(3).
863
864             If  exit  then the transport process in question exits. If handle
865             then  the  message  is  processed  as  usual,  a  resulting  han‐
866             dle_request/3  or  handle_answer/4  callback (if one takes place)
867             indicating the 5015 error  (DIAMETER_INVALID_MESSAGE_LENGTH).  If
868             discard then the message in question is silently discarded.
869
870             Defaults to exit.
871
872       Note:
873           The  default  value reflects the fact that a transport module for a
874           stream-oriented transport like TCP may not be able to recover  from
875           a  message length error since such a transport must use the Message
876           Length header to divide the incoming byte  stream  into  individual
877           Diameter messages. An invalid length leaves it with no reliable way
878           to rediscover message boundaries, which may result in  the  failure
879           of  subsequent  messages.  See diameter_tcp(3) for the behaviour of
880           that module.
881
882
883           {pool_size, pos_integer()}:
884             Number of transport processes to start. For  a  listening  trans‐
885             port, determines the size of the pool of accepting transport pro‐
886             cesses, a larger number being desirable for  processing  multiple
887             concurrent  peer connection attempts. For a connecting transport,
888             determines the number of connections to the peer in question that
889             will   be   attempted   to   be  establshed:  the  service_opt():
890             restrict_connections should also be configured on the service  in
891             question to allow multiple connections to the same peer.
892
893           {spawn_opt, [term()] | {M,F,A}}:
894             An  options  list passed to erlang:spawn_opt/2 to spawn a handler
895             process for an incoming Diameter request on the local node, or an
896             MFA that returns the pid of a handler process.
897
898             Options  monitor and link are ignored in the list-valued case. An
899             MFA is applied with an additional term prepended to its  argument
900             list,  and  should  return  either the pid of the handler process
901             that invokes diameter_traffic:request/1 on the argument in  order
902             to  process the request, or the atom discard. The handler process
903             need not be local, and diameter need not be started on the remote
904             node,  but diameter and relevant application callbacks must be on
905             the code path.
906
907             Defaults to the empty list.
908
909           {strict_capx, boolean()]}:
910             Whether or not to enforce the RFC 6733 requirement that any  mes‐
911             sage  before  capabilities exchange should close the peer connec‐
912             tion. If false then unexpected messages are discarded.
913
914             Defaults to true. Changing this results  in  non-standard  behav‐
915             iour,  but  can  be  useful  in case peers are known to be behave
916             badly.
917
918           {strict_mbit, boolean()}:
919             Whether or not to regard an AVP setting the  M-bit  as  erroneous
920             when  the  command  grammar in question does not explicitly allow
921             the AVP. If true then such AVPs  are  regarded  as  5001  errors,
922             DIAMETER_AVP_UNSUPPORTED.  If false then the M-bit is ignored and
923             policing it becomes the receiver's responsibility.
924
925             Defaults to true.
926
927       Warning:
928           RFC 6733 is unclear about the semantics of the M-bit. One  the  one
929           hand,  the CCF specification in section 3.2 documents AVP in a com‐
930           mand grammar as meaning any arbitrary AVP; on the other hand, 1.3.4
931           states  that  AVPs setting the M-bit cannot be added to an existing
932           command: the modified command must instead be placed in a new Diam‐
933           eter application.
934
935           The  reason for the latter is presumably interoperability: allowing
936           arbitrary AVPs setting the M-bit in a command makes its interpreta‐
937           tion  implementation-dependent, since there's no guarantee that all
938           implementations will understand the same set of arbitrary  AVPs  in
939           the context of a given command. However, interpreting AVP in a com‐
940           mand grammar as any AVP, regardless of M-bit, renders  1.3.4  mean‐
941           ingless,  since  the  receiver  can simply ignore any AVP it thinks
942           isn't relevant, regardless of the sender's intent.
943
944           Beware of confusing mandatory in the sense of the M-bit with manda‐
945           tory  in the sense of the command grammar. The former is a semantic
946           requirement: that the receiver understand the semantics of the  AVP
947           in  the context in question. The latter is a syntactic requirement:
948           whether or not the AVP must occur in the message in question.
949
950
951           {transport_config, term()}:
952
953
954           {transport_config, term(), Unsigned32() | infinity}:
955             Term passed as the third argument to the start/3 function of  the
956             relevant  transport module in order to start a transport process.
957             Defaults to the empty list.
958
959             The 3-tuple form additionally specifies an interval, in millisec‐
960             onds,  after  which  a started transport process should be termi‐
961             nated if it has not yet established a  connection.  For  example,
962             the following options on a connecting transport request a connec‐
963             tion with one peer over SCTP or another (typically the same) over
964             TCP.
965
966           {transport_module, diameter_sctp}
967           {transport_config, SctpOpts, 5000}
968           {transport_module, diameter_tcp}
969           {transport_config, TcpOpts}
970
971
972             To listen on both SCTP and TCP, define one transport for each.
973
974           {transport_module, atom()}:
975             Module  implementing  a  transport  process  as defined in diame‐
976             ter_transport(3). Defaults to diameter_tcp.
977
978             Multiple  transport_module  and  transport_config   options   are
979             allowed. The order of these is significant in this case (and only
980             in this case), a transport_module being  paired  with  the  first
981             transport_config following it in the options list, or the default
982             value for trailing modules. Transport starts  will  be  attempted
983             with each of the modules in order until one establishes a connec‐
984             tion within the corresponding timeout (see below) or all fail.
985
986           {watchdog_config, [{okay|suspect, non_neg_integer()}]}:
987             Configuration that alters the behaviour  of  the  watchdog  state
988             machine.  On  key  okay,  the non-negative number of answered DWR
989             messages before transitioning from REOPEN to OKAY.  On  key  sus‐
990             pect,  the  number of watchdog timeouts before transitioning from
991             OKAY to SUSPECT when DWR is unanswered, or  0  to  not  make  the
992             transition.
993
994             Defaults  to  [{okay,  3}, {suspect, 1}]. Not specifying a key is
995             equivalent to specifying the default value for that key.
996
997       Warning:
998           The default value is as required by RFC 3539: changing  it  results
999           in non-standard behaviour that should only be used to simulate mis‐
1000           behaving nodes during test.
1001
1002
1003           {watchdog_timer, TwInit}:
1004
1005
1006           TwInit = Unsigned32()
1007                  | {M,F,A}
1008
1009
1010             The RFC 3539 watchdog timer. An integer value is  interpreted  as
1011             the RFC's TwInit in milliseconds, a jitter of +/- 2 seconds being
1012             added at each rearming of the timer to compute the RFC's  Tw.  An
1013             MFA  is  expected  to  return  the RFC's Tw directly, with jitter
1014             applied, allowing the jitter calculation to be performed  by  the
1015             callback.
1016
1017             An  integer  value must be at least 6000 as required by RFC 3539.
1018             Defaults to 30000.
1019
1020           Unrecognized options are silently ignored but are returned  unmodi‐
1021           fied  by  service_info/2  and can be referred to in predicate func‐
1022           tions passed to remove_transport/2.
1023
1024         transport_ref() = reference():
1025           Reference returned by add_transport/2 that identifies the  configu‐
1026           ration.
1027

EXPORTS

1029       add_transport(SvcName,  {connect|listen, [Opt]}) -> {ok, Ref} | {error,
1030       Reason}
1031
1032              Types:
1033
1034                 SvcName = service_name()
1035                 Opt = transport_opt()
1036                 Ref = transport_ref()
1037                 Reason = term()
1038
1039              Add transport capability to a service.
1040
1041              The service will start transport processes as required in  order
1042              to establish a connection with the peer, either by connecting to
1043              the peer (connect) or by accepting incoming connection  requests
1044              (listen).  A  connecting transport establishes transport connec‐
1045              tions with at most one peer, an listening transport  potentially
1046              with many.
1047
1048              The  diameter  application  takes  responsibility for exchanging
1049              CER/CEA with the peer. Upon successful completion  of  capabili‐
1050              ties  exchange  the service calls each relevant application mod‐
1051              ule's peer_up/3 callback after which  the  caller  can  exchange
1052              Diameter  messages with the peer over the transport. In addition
1053              to CER/CEA, the service takes responsibility for the handling of
1054              DWR/DWA and required by RFC 3539, as well as for DPR/DPA.
1055
1056              The  returned reference uniquely identifies the transport within
1057              the scope of the service. Note that the function returns  before
1058              a transport connection has been established.
1059
1060          Note:
1061              It  is not an error to add a transport to a service that has not
1062              yet been configured: a service can be started after  configuring
1063              its transports.
1064
1065
1066       call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason}
1067
1068              Types:
1069
1070                 SvcName = service_name()
1071                 App = application_alias()
1072                 Request = diameter_codec:message()
1073                 Answer = term()
1074                 Opt = call_opt()
1075
1076              Send a Diameter request message.
1077
1078              App  specifies  the Diameter application in which the request is
1079              defined and callbacks to the corresponding callback module  will
1080              follow  as  described  below  and in diameter_app(3). Unless the
1081              detach option is specified, the  call  returns  either  when  an
1082              answer  message is received from the peer or an error occurs. In
1083              the answer case, the return value  is  as  returned  by  a  han‐
1084              dle_answer/4  callback.  In  the  error case, whether or not the
1085              error is returned directly by diameter or from a  handle_error/4
1086              callback  depends on whether or not the outgoing request is suc‐
1087              cessfully encoded for transmission to the peer, the cases  being
1088              documented below.
1089
1090              If  there  are no suitable peers, or if pick_peer/4 rejects them
1091              by returning false, then {error,no_connection} is returned. Oth‐
1092              erwise  pick_peer/4 is followed by a prepare_request/3 callback,
1093              the message is encoded and then sent.
1094
1095              There are several error cases which may prevent an  answer  from
1096              being received and passed to a handle_answer/4 callback:
1097
1098                * If  the  initial  encode of the outgoing request fails, then
1099                  the request process fails and {error,encode} is returned.
1100
1101                * If the request is successfully  encoded  and  sent  but  the
1102                  answer  times out then a handle_error/4 callback takes place
1103                  with Reason = timeout.
1104
1105                * If the request is successfully encoded and sent but the ser‐
1106                  vice  in  question  is  stopped before an answer is received
1107                  then a handle_error/4 callback takes  place  with  Reason  =
1108                  cancel.
1109
1110                * If  the  transport  connection with the peer goes down after
1111                  the request has been sent but  before  an  answer  has  been
1112                  received then an attempt is made to resend the request to an
1113                  alternate peer. If no such peer is available, or if the sub‐
1114                  sequent  pick_peer/4 callback rejects the candidates, then a
1115                  handle_error/4 callback takes place with Reason =  failover.
1116                  If  a  peer is selected then a prepare_retransmit/3 callback
1117                  takes place, after which the semantics are the same as  fol‐
1118                  lowing an initial prepare_request/3 callback.
1119
1120                * If  an  encode  error takes place during retransmission then
1121                  the request process fails and {error,failure} is returned.
1122
1123                * If an application callback made in  processing  the  request
1124                  fails  (pick_peer, prepare_request, prepare_retransmit, han‐
1125                  dle_answer or handle_error) then  either  {error,encode}  or
1126                  {error,failure}  is  returned  depending  on  whether or not
1127                  there has been an attempt  to  send  the  request  over  the
1128                  transport.
1129
1130              Note  that {error,encode} is the only return value which guaran‐
1131              tees that the request has not been sent over the transport  con‐
1132              nection.
1133
1134       origin_state_id() -> Unsigned32()
1135
1136              Return a reasonable value for use as Origin-State-Id in outgoing
1137              messages.
1138
1139              The  value   returned   is   the   number   of   seconds   since
1140              19680120T031408Z, the first value that can be encoded as a Diam‐
1141              eter Time(), at the time the diameter application was started.
1142
1143       remove_transport(SvcName, Pred) -> ok | {error, Reason}
1144
1145              Types:
1146
1147                 SvcName = service_name()
1148                 Pred = Fun | MFA | transport_ref() | list() | true | false
1149
1150                 Fun = fun((transport_ref(), connect|listen, list()) ->  bool‐
1151                 ean())
1152                  | fun((transport_ref(), list()) -> boolean())
1153                  | fun((list()) -> boolean())
1154                 MFA = {atom(), atom(), list()}
1155                 Reason = term()
1156
1157              Remove previously added transports.
1158
1159              Pred  determines  which  transports to remove. An arity-3-valued
1160              Pred removes all transports  for  which  Pred(Ref,  Type,  Opts)
1161              returns  true,  where  Type and Opts are as passed to add_trans‐
1162              port/2 and Ref is as returned by it.  The  remaining  forms  are
1163              equivalent to an arity-3 fun as follows.
1164
1165              Pred = fun(transport_ref(), list()):  fun(Ref, _, Opts) -> Pred(Ref, Opts) end
1166              Pred = fun(list()):                   fun(_, _, Opts) -> Pred(Opts) end
1167              Pred = transport_ref():               fun(Ref, _, _)  -> Pred == Ref end
1168              Pred = list():                        fun(_, _, Opts) -> [] == Pred -- Opts end
1169              Pred = true:                          fun(_, _, _) -> true end
1170              Pred = false:                         fun(_, _, _) -> false end
1171              Pred = {M,F,A}:  fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
1172
1173
1174              Removing  a  transport  causes  the corresponding transport pro‐
1175              cesses to be terminated. Whether or not a DPR message is sent to
1176              a peer is controlled by value of disconnect_cb configured on the
1177              transport.
1178
1179       service_info(SvcName, Info) -> term()
1180
1181              Types:
1182
1183                 SvcName = service_name()
1184                 Info = Item | [Info]
1185                 Item = atom()
1186
1187              Return information about a started service. Requesting info  for
1188              an unknown service causes undefined to be returned. Requesting a
1189              list of items causes a tagged list to be returned.
1190
1191              Item can be one of the following.
1192
1193                'Origin-Host':
1194
1195
1196                'Origin-Realm':
1197
1198
1199                'Vendor-Id':
1200
1201
1202                'Product-Name':
1203
1204
1205                'Origin-State-Id':
1206
1207
1208                'Host-IP-Address':
1209
1210
1211                'Supported-Vendor':
1212
1213
1214                'Auth-Application-Id':
1215
1216
1217                'Inband-Security-Id':
1218
1219
1220                'Acct-Application-Id':
1221
1222
1223                'Vendor-Specific-Application-Id':
1224
1225
1226                'Firmware-Revision':
1227                  Return a capability  value  as  configured  with  start_ser‐
1228                  vice/2.
1229
1230                applications:
1231                  Return   the   list   of  applications  as  configured  with
1232                  start_service/2.
1233
1234                capabilities:
1235                  Return a tagged list of all capabilities values  as  config‐
1236                  ured with start_service/2.
1237
1238                transport:
1239                  Return a list containing one entry for each of the service's
1240                  transport as configured with add_transport/2. Each entry  is
1241                  a  tagged list containing both configuration and information
1242                  about established peer connections. An example return  value
1243                  with  for  a  client  service with Origin-Host "client.exam‐
1244                  ple.com" configured with a  single  transport  connected  to
1245                  "server.example.com" might look as follows.
1246
1247                [[{ref,#Ref<0.0.0.93>},
1248                  {type,connect},
1249                  {options,[{transport_module,diameter_tcp},
1250                            {transport_config,[{ip,{127,0,0,1}},
1251                                               {raddr,{127,0,0,1}},
1252                                               {rport,3868},
1253                                               {reuseaddr,true}]}]},
1254                  {watchdog,{<0.66.0>,-576460736368485571,okay}},
1255                  {peer,{<0.67.0>,-576460736357885808}},
1256                  {apps,[{0,common}]},
1257                  {caps,[{origin_host,{"client.example.com","server.example.com"}},
1258                         {origin_realm,{"example.com","example.com"}},
1259                         {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1260                         {vendor_id,{0,193}},
1261                         {product_name,{"Client","Server"}},
1262                         {origin_state_id,{[],[]}},
1263                         {supported_vendor_id,{[],[]}},
1264                         {auth_application_id,{[0],[0]}},
1265                         {inband_security_id,{[],[0]}},
1266                         {acct_application_id,{[],[]}},
1267                         {vendor_specific_application_id,{[],[]}},
1268                         {firmware_revision,{[],[]}},
1269                         {avp,{[],[]}}]},
1270                  {port,[{owner,<0.69.0>},
1271                         {module,diameter_tcp},
1272                         {socket,{{127,0,0,1},48758}},
1273                         {peer,{{127,0,0,1},3868}},
1274                         {statistics,[{recv_oct,656},
1275                                      {recv_cnt,6},
1276                                      {recv_max,148},
1277                                      {recv_avg,109},
1278                                      {recv_dvi,19},
1279                                      {send_oct,836},
1280                                      {send_cnt,6},
1281                                      {send_max,184},
1282                                      {send_avg,139},
1283                                      {send_pend,0}]}]},
1284                  {statistics,[{{{0,258,0},recv},3},
1285                               {{{0,258,1},send},3},
1286                               {{{0,258,0},recv,{'Result-Code',2001}},3},
1287                               {{{0,257,0},recv},1},
1288                               {{{0,257,1},send},1},
1289                               {{{0,257,0},recv,{'Result-Code',2001}},1},
1290                               {{{0,280,1},recv},2},
1291                               {{{0,280,0},send},2},
1292                               {{{0,280,0},send,{'Result-Code',2001}},2}]}]]
1293
1294
1295                  Here  ref is a transport_ref() and options the corresponding
1296                  transport_opt() list passed to add_transport/2. The watchdog
1297                  entry  shows  the  state of a connection's RFC 3539 watchdog
1298                  state  machine.  The  peer  entry  identifies   the   diame‐
1299                  ter_app:peer_ref()  for which there will have been peer_up/3
1300                  callbacks for the Diameter applications  identified  by  the
1301                  apps  entry,  common being the application_alias(). The caps
1302                  entry identifies the capabilities sent by the local node and
1303                  received  from  the  peer  during capabilities exchange. The
1304                  port  entry  displays  socket-level  information  about  the
1305                  transport  connection.  The statistics entry presents Diame‐
1306                  ter-level counters, an entry like {{{0,280,1},recv},2}  say‐
1307                  ing that the client has received 2 DWR messages: {0,280,1} =
1308                  {Application_Id, Command_Code, R_Flag}.
1309
1310                  Note that watchdog, peer, apps, caps and port entries depend
1311                  on  connectivity  with the peer and may not be present. Note
1312                  also that the statistics entry presents  values  accumulated
1313                  during the lifetime of the transport configuration.
1314
1315                  A listening transport presents its information slightly dif‐
1316                  ferently since there may be  multiple  accepted  connections
1317                  for the same transport_ref(). The transport info returned by
1318                  a server with a single client connection might look as  fol‐
1319                  lows.
1320
1321                [[{ref,#Ref<0.0.0.61>},
1322                  {type,listen},
1323                  {options,[{transport_module,diameter_tcp},
1324                            {transport_config,[{reuseaddr,true},
1325                                               {ip,{127,0,0,1}},
1326                                               {port,3868}]}]},
1327                  {accept,[[{watchdog,{<0.56.0>,-576460739249514012,okay}},
1328                            {peer,{<0.58.0>,-576460638229179167}},
1329                            {apps,[{0,common}]},
1330                            {caps,[{origin_host,{"server.example.com","client.example.com"}},
1331                                   {origin_realm,{"example.com","example.com"}},
1332                                   {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1333                                   {vendor_id,{193,0}},
1334                                   {product_name,{"Server","Client"}},
1335                                   {origin_state_id,{[],[]}},
1336                                   {supported_vendor_id,{[],[]}},
1337                                   {auth_application_id,{[0],[0]}},
1338                                   {inband_security_id,{[],[]}},
1339                                   {acct_application_id,{[],[]}},
1340                                   {vendor_specific_application_id,{[],[]}},
1341                                   {firmware_revision,{[],[]}},
1342                                   {avp,{[],[]}}]},
1343                            {port,[{owner,<0.62.0>},
1344                                   {module,diameter_tcp},
1345                                   {socket,{{127,0,0,1},3868}},
1346                                   {peer,{{127,0,0,1},48758}},
1347                                   {statistics,[{recv_oct,1576},
1348                                                {recv_cnt,16},
1349                                                {recv_max,184},
1350                                                {recv_avg,98},
1351                                                {recv_dvi,26},
1352                                                {send_oct,1396},
1353                                                {send_cnt,16},
1354                                                {send_max,148},
1355                                                {send_avg,87},
1356                                                {send_pend,0}]}]}],
1357                           [{watchdog,{<0.72.0>,-576460638229717546,initial}}]]},
1358                  {statistics,[{{{0,280,0},recv},7},
1359                               {{{0,280,1},send},7},
1360                               {{{0,280,0},recv,{'Result-Code',2001}},7},
1361                               {{{0,258,1},recv},3},
1362                               {{{0,258,0},send},3},
1363                               {{{0,258,0},send,{'Result-Code',2001}},3},
1364                               {{{0,280,1},recv},5},
1365                               {{{0,280,0},send},5},
1366                               {{{0,280,0},send,{'Result-Code',2001}},5},
1367                               {{{0,257,1},recv},1},
1368                               {{{0,257,0},send},1},
1369                               {{{0,257,0},send,{'Result-Code',2001}},1}]}]]
1370
1371
1372                  The  information  presented  here  is as in the connect case
1373                  except that the client  connections  are  grouped  under  an
1374                  accept tuple.
1375
1376                  Whether  or  not the transport_opt() pool_size has been con‐
1377                  figured affects the format of the listing in the case  of  a
1378                  connecting  transport,  since a value greater than 1 implies
1379                  multiple transport processes for the  same  transport_ref(),
1380                  as in the listening case. The format in this case is similar
1381                  to the listening case, with a pool  tuple  in  place  of  an
1382                  accept tuple.
1383
1384                connections:
1385                  Return  a  list  containing  one entry for every established
1386                  transport connection whose watchdog state machine is not  in
1387                  the  down state. This is a flat view of transport info which
1388                  lists only active connections and for  which  Diameter-level
1389                  statistics  are  accumulated  only  for  the lifetime of the
1390                  transport connection. A return value for  the  server  above
1391                  might look as follows.
1392
1393                [[{ref,#Ref<0.0.0.61>},
1394                  {type,accept},
1395                  {options,[{transport_module,diameter_tcp},
1396                            {transport_config,[{reuseaddr,true},
1397                                               {ip,{127,0,0,1}},
1398                                               {port,3868}]}]},
1399                  {watchdog,{<0.56.0>,-576460739249514012,okay}},
1400                  {peer,{<0.58.0>,-576460638229179167}},
1401                  {apps,[{0,common}]},
1402                  {caps,[{origin_host,{"server.example.com","client.example.com"}},
1403                         {origin_realm,{"example.com","example.com"}},
1404                         {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
1405                         {vendor_id,{193,0}},
1406                         {product_name,{"Server","Client"}},
1407                         {origin_state_id,{[],[]}},
1408                         {supported_vendor_id,{[],[]}},
1409                         {auth_application_id,{[0],[0]}},
1410                         {inband_security_id,{[],[]}},
1411                         {acct_application_id,{[],[]}},
1412                         {vendor_specific_application_id,{[],[]}},
1413                         {firmware_revision,{[],[]}},
1414                         {avp,{[],[]}}]},
1415                  {port,[{owner,<0.62.0>},
1416                         {module,diameter_tcp},
1417                         {socket,{{127,0,0,1},3868}},
1418                         {peer,{{127,0,0,1},48758}},
1419                         {statistics,[{recv_oct,10124},
1420                                      {recv_cnt,132},
1421                                      {recv_max,184},
1422                                      {recv_avg,76},
1423                                      {recv_dvi,9},
1424                                      {send_oct,10016},
1425                                      {send_cnt,132},
1426                                      {send_max,148},
1427                                      {send_avg,75},
1428                                      {send_pend,0}]}]},
1429                  {statistics,[{{{0,280,0},recv},62},
1430                               {{{0,280,1},send},62},
1431                               {{{0,280,0},recv,{'Result-Code',2001}},62},
1432                               {{{0,258,1},recv},3},
1433                               {{{0,258,0},send},3},
1434                               {{{0,258,0},send,{'Result-Code',2001}},3},
1435                               {{{0,280,1},recv},66},
1436                               {{{0,280,0},send},66},
1437                               {{{0,280,0},send,{'Result-Code',2001}},66},
1438                               {{{0,257,1},recv},1},
1439                               {{{0,257,0},send},1},
1440                               {{{0,257,0},send,{'Result-Code',2001}},1}]}]]
1441
1442
1443                  Note  that  there may be multiple entries with the same ref,
1444                  in contrast to transport info.
1445
1446                statistics:
1447                  Return a {{Counter, Ref}, non_neg_integer()} list of counter
1448                  values.  Ref  can  be  either  a transport_ref() or a diame‐
1449                  ter_app:peer_ref(). Entries for the latter are  folded  into
1450                  corresponding  entries for the former as peer connections go
1451                  down. Entries for both are  removed  at  remove_transport/2.
1452                  The Diameter-level statistics returned by transport and con‐
1453                  nections info are based upon these entries.
1454
1455                diameter_app:peer_ref():
1456                  Return transport  configuration  associated  with  a  single
1457                  peer,  as  passed  to  add_transport/2. The returned list is
1458                  empty if the peer is unknown. Otherwise it contains the ref,
1459                  type and options tuples as in transport and connections info
1460                  above. For example:
1461
1462                [{ref,#Ref<0.0.0.61>},
1463                 {type,accept},
1464                 {options,[{transport_module,diameter_tcp},
1465                           {transport_config,[{reuseaddr,true},
1466                                              {ip,{127,0,0,1}},
1467                                              {port,3868}]}]}]
1468
1469
1470       services() -> [SvcName]
1471
1472              Types:
1473
1474                 SvcName = service_name()
1475
1476              Return the list of started services.
1477
1478       session_id(Ident) -> OctetString()
1479
1480              Types:
1481
1482                 Ident = DiameterIdentity()
1483
1484              Return a value for a Session-Id AVP.
1485
1486              The value has the form required by  section  8.8  of  RFC  6733.
1487              Ident  should be the Origin-Host of the peer from which the mes‐
1488              sage containing the returned value will be sent.
1489
1490       start() -> ok | {error, Reason}
1491
1492              Start the diameter application.
1493
1494              The diameter application must be started before starting a  ser‐
1495              vice. In a production system this is typically accomplished by a
1496              boot file, not by calling start/0 explicitly.
1497
1498       start_service(SvcName, Options) -> ok | {error, Reason}
1499
1500              Types:
1501
1502                 SvcName = service_name()
1503                 Options = [service_opt()]
1504                 Reason = term()
1505
1506              Start a diameter service.
1507
1508              A service defines a locally-implemented Diameter node,  specify‐
1509              ing  the  capabilities  to  be  advertised  during  capabilities
1510              exchange. Transports are added to  a  service  using  add_trans‐
1511              port/2.
1512
1513          Note:
1514              A  transport  can  both  override its service's capabilities and
1515              restrict its supported Diameter applications so "service = Diam‐
1516              eter  node  as identified by Origin-Host" is not necessarily the
1517              case.
1518
1519
1520       stop() -> ok | {error, Reason}
1521
1522              Stop the diameter application.
1523
1524       stop_service(SvcName) -> ok | {error, Reason}
1525
1526              Types:
1527
1528                 SvcName = service_name()
1529                 Reason = term()
1530
1531              Stop a diameter service.
1532
1533              Stopping a service causes all associated  transport  connections
1534              to  be  broken.  A  DPR  message  will be sent as in the case of
1535              remove_transport/2.
1536
1537          Note:
1538              Stopping a service does not remove  any  associated  transports:
1539              remove_transport/2 must be called to remove transport configura‐
1540              tion.
1541
1542
1543       subscribe(SvcName) -> true
1544
1545              Types:
1546
1547                 SvcName = service_name()
1548
1549              Subscribe to service_event() messages from a service.
1550
1551              It is not an error to subscribe to events from  a  service  that
1552              does  not  yet  exist.  Doing  so  before  adding  transports is
1553              required to guarantee the  reception  of  all  transport-related
1554              events.
1555
1556       unsubscribe(SvcName) -> true
1557
1558              Types:
1559
1560                 SvcName = service_name()
1561
1562              Unsubscribe to event messages from a service.
1563

SEE ALSO

1565       diameter_app(3), diameter_transport(3), diameter_dict(4)
1566
1567
1568
1569Ericsson AB                     diameter 2.2.3                     diameter(3)
Impressum