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 or capabilities. Used as
681             defaults for transport configuration, values passed to add_trans‐
682             port/2 overriding values configured on the service.
683
684         transport_opt():
685           Option passed to add_transport/2. Has one of the following types.
686
687           {applications, [application_alias()]}:
688             Diameter  applications  to  which   the   transport   should   be
689             restricted.  Defaults  to all applications configured on the ser‐
690             vice in question. Applications not configured on the  service  in
691             question are ignored.
692
693       Warning:
694           The  capabilities  advertised  by  a node must match its configured
695           applications. In particular, setting applications  on  a  transport
696           typically implies having to set matching *-Application-Id AVPs in a
697           capabilities() tuple.
698
699
700           {avp_dictionaries, [module()]}:
701             A  list  of  alternate   dictionary   modules   with   which   to
702             encode/decode  AVPs that are not defined by the dictionary of the
703             application in question. At decode, such AVPs are represented  as
704             diameter_avp  records  in the 'AVP' field of a decoded message or
705             Grouped AVP, the first alternate that succeeds  in  decoding  the
706             AVP  setting  the  record's  value field. At encode, values in an
707             'AVP' list can be passed as AVP name/value 2-tuples, and it is an
708             encode error for no alternate to define the AVP of such a tuple.
709
710             Defaults to the empty list.
711
712       Note:
713           The  motivation  for  alternate  dictionaries is RFC 7683, Diameter
714           Overload Indication Conveyance (DOIC), which  defines  AVPs  to  be
715           piggybacked onto existing application messages rather than defining
716           an application of its own. The DOIC dictionary is provided  by  the
717           diameter  application,  as  module  diameter_gen_doic_rfc7683,  but
718           alternate dictionaries can be used to encode/decode any set of AVPs
719           not known to an application dictionary.
720
721
722           {capabilities, [capability()]}:
723             AVPs  used  to  construct  outgoing CER/CEA messages. Values take
724             precedence over any specified on the service in question.
725
726             Specifying a capability as a transport option may be particularly
727             appropriate  for  Inband-Security-Id, in case TLS is desired over
728             TCP as implemented by diameter_tcp(3).
729
730           {capabilities_cb, eval()}:
731             Callback invoked upon reception of  CER/CEA  during  capabilities
732             exchange  in order to ask whether or not the connection should be
733             accepted. Applied to  the  transport_ref()  and  #diameter_caps{}
734             record of the connection.
735
736             The return value can have one of the following types.
737
738             ok:
739               Accept the connection.
740
741             integer():
742               Causes  an  incoming  CER  to  be  answered  with the specified
743               Result-Code.
744
745             discard:
746               Causes an incoming CER to be discarded without CEA being sent.
747
748             unknown:
749               Equivalent to returning 3010, DIAMETER_UNKNOWN_PEER.
750
751             Returning anything but ok or a 2xxx series result code causes the
752             transport  connection  to  be  broken.  Multiple  capabilities_cb
753             options can be specified, in which case the  corresponding  call‐
754             backs are applied until either all return ok or one does not.
755
756           {capx_timeout, Unsigned32()}:
757             Number  of milliseconds after which a transport process having an
758             established  transport  connection  will  be  terminated  if  the
759             expected  capabilities  exchange  message  (CER  or  CEA)  is not
760             received from the peer. For a connecting transport, the timing of
761             connection  attempts  is  governed  by  connect_timer  or  watch‐
762             dog_timer expiry. For a listening transport, the peer  determines
763             the timing.
764
765             Defaults to 10000.
766
767           {connect_timer, Tc}:
768
769
770           Tc = Unsigned32()
771
772
773             For  a  connecting transport, the RFC 6733 Tc timer, in millisec‐
774             onds. This timer determines the frequency with which a  transport
775             attempts to establish an initial connection with its peer follow‐
776             ing transport configuration. Once an initial connection has  been
777             established, watchdog_timer determines the frequency of reconnec‐
778             tion attempts, as required by RFC 3539.
779
780             For a listening transport, the timer  specifies  the  time  after
781             which a previously connected peer will be forgotten: a connection
782             after this time is regarded as an initial connection rather  than
783             reestablishment,  causing  the  RFC 3539 state machine to pass to
784             state OKAY rather than REOPEN. Note that these semantics are  not
785             governed  by  the  RFC  and  that  a  listening  transport's con‐
786             nect_timer should be greater than its peer's Tw plus jitter.
787
788             Defaults to 30000 for a connecting transport and 60000 for a lis‐
789             tening transport.
790
791           {disconnect_cb, eval()}:
792             Callback  invoked prior to terminating the transport process of a
793             transport connection  having  watchdog  state  OKAY.  Applied  to
794             application|service|transport  and the transport_ref() and diame‐
795             ter_app:peer() in question: application indicates that the diame‐
796             ter  application  is  being  stopped, service that the service in
797             question is being stopped by stop_service/1, and  transport  that
798             the transport in question is being removed by remove_transport/2.
799
800             The return value can have one of the following types.
801
802             {dpr, [option()]}:
803               Send Disconnect-Peer-Request to the peer, the transport process
804               being terminated following reception of  Disconnect-Peer-Answer
805               or timeout. An option() can be one of the following.
806
807               {cause, 0|rebooting|1|busy|2|goaway}:
808                 Disconnect-Cause     to    send,    REBOOTING,    BUSY    and
809                 DO_NOT_WANT_TO_TALK_TO_YOU respectively. Defaults to  reboot‐
810                 ing   for  Reason=service|application  and  goaway  for  Rea‐
811                 son=transport.
812
813               {timeout, Unsigned32()}:
814                 Number of milliseconds after which the transport  process  is
815                 terminated  if  DPA  has  not  been received. Defaults to the
816                 value of dpa_timeout.
817
818             dpr:
819               Equivalent to {dpr, []}.
820
821             close:
822               Terminate the transport process without Disconnect-Peer-Request
823               being sent to the peer.
824
825             ignore:
826               Equivalent to not having configured the callback.
827
828             Multiple  disconnect_cb  options  can be specified, in which case
829             the corresponding callbacks are applied until one of them returns
830             a  value  other  than  ignore.  All callbacks returning ignore is
831             equivalent to not having configured them.
832
833             Defaults to a single callback returning dpr.
834
835           {dpa_timeout, Unsigned32()}:
836             Number of milliseconds after which a transport connection is ter‐
837             minated following an outgoing DPR if DPA is not received.
838
839             Defaults to 1000.
840
841           {dpr_timeout, Unsigned32()}:
842             Number of milliseconds after which a transport connection is ter‐
843             minated following an incoming DPR if the peer does not close  the
844             connection.
845
846             Defaults to 5000.
847
848           {incoming_maxlen, 0..16777215}:
849             Bound  on  the  expected size of incoming Diameter messages. Mes‐
850             sages larger than the specified number of bytes are discarded.
851
852             Defaults to 16777215, the maximum value  of  the  24-bit  Message
853             Length field in a Diameter Header.
854
855           {length_errors, exit|handle|discard}:
856             How to deal with errors in the Message Length field of the Diame‐
857             ter Header in an incoming message. An error in  this  context  is
858             that  the  length  is  not  at  least  20  bytes (the length of a
859             Header), is not a multiple of 4 (a valid length) or  is  not  the
860             length of the message in question, as received over the transport
861             interface documented in diameter_transport(3).
862
863             If exit then the transport process in question exits.  If  handle
864             then  the  message  is  processed  as  usual,  a  resulting  han‐
865             dle_request/3 or handle_answer/4 callback (if  one  takes  place)
866             indicating  the  5015 error (DIAMETER_INVALID_MESSAGE_LENGTH). If
867             discard then the message in question is silently discarded.
868
869             Defaults to exit.
870
871       Note:
872           The default value reflects the fact that a transport module  for  a
873           stream-oriented  transport like TCP may not be able to recover from
874           a message length error since such a transport must use the  Message
875           Length  header  to  divide the incoming byte stream into individual
876           Diameter messages. An invalid length leaves it with no reliable way
877           to  rediscover  message boundaries, which may result in the failure
878           of subsequent messages. See diameter_tcp(3) for  the  behaviour  of
879           that module.
880
881
882           {pool_size, pos_integer()}:
883             Number  of  transport  processes to start. For a listening trans‐
884             port, determines the size of the pool of accepting transport pro‐
885             cesses,  a  larger number being desirable for processing multiple
886             concurrent peer connection attempts. For a connecting  transport,
887             determines the number of connections to the peer in question that
888             will  be  attempted  to   be   establshed:   the   service_opt():
889             restrict_connections  should also be configured on the service in
890             question to allow multiple connections to the same peer.
891
892           {spawn_opt, [term()] | {M,F,A}}:
893             An options list passed to erlang:spawn_opt/2 to spawn  a  handler
894             process for an incoming Diameter request on the local node, or an
895             MFA that returns the pid of a handler process.
896
897             Options monitor and link are ignored in the list-valued case.  An
898             MFA  is applied with an additional term prepended to its argument
899             list, and should return either the pid  of  the  handler  process
900             that  invokes  diameter_traffic:request/1 on the term in order to
901             process the request, or the atom  discard.  The  handler  process
902             need  not  be  local,  but diameter must be started on the remote
903             node.
904
905             Defaults to the empty list.
906
907           {strict_capx, boolean()]}:
908             Whether or not to enforce the RFC 6733 requirement that any  mes‐
909             sage  before  capabilities exchange should close the peer connec‐
910             tion. If false then unexpected messages are discarded.
911
912             Defaults to true. Changing this results  in  non-standard  behav‐
913             iour,  but  can  be  useful  in case peers are known to be behave
914             badly.
915
916           {strict_mbit, boolean()}:
917             Whether or not to regard an AVP setting the  M-bit  as  erroneous
918             when  the  command  grammar in question does not explicitly allow
919             the AVP. If true then such AVPs  are  regarded  as  5001  errors,
920             DIAMETER_AVP_UNSUPPORTED.  If false then the M-bit is ignored and
921             policing it becomes the receiver's responsibility.
922
923             Defaults to true.
924
925       Warning:
926           RFC 6733 is unclear about the semantics of the M-bit. One  the  one
927           hand,  the CCF specification in section 3.2 documents AVP in a com‐
928           mand grammar as meaning any arbitrary AVP; on the other hand, 1.3.4
929           states  that  AVPs setting the M-bit cannot be added to an existing
930           command: the modified command must instead be placed in a new Diam‐
931           eter application.
932
933           The  reason for the latter is presumably interoperability: allowing
934           arbitrary AVPs setting the M-bit in a command makes its interpreta‐
935           tion  implementation-dependent, since there's no guarantee that all
936           implementations will understand the same set of arbitrary  AVPs  in
937           the context of a given command. However, interpreting AVP in a com‐
938           mand grammar as any AVP, regardless of M-bit, renders  1.3.4  mean‐
939           ingless,  since  the  receiver  can simply ignore any AVP it thinks
940           isn't relevant, regardless of the sender's intent.
941
942           Beware of confusing mandatory in the sense of the M-bit with manda‐
943           tory  in the sense of the command grammar. The former is a semantic
944           requirement: that the receiver understand the semantics of the  AVP
945           in  the context in question. The latter is a syntactic requirement:
946           whether or not the AVP must occur in the message in question.
947
948
949           {transport_config, term()}:
950
951
952           {transport_config, term(), Unsigned32() | infinity}:
953             Term passed as the third argument to the start/3 function of  the
954             relevant  transport module in order to start a transport process.
955             Defaults to the empty list.
956
957             The 3-tuple form additionally specifies an interval, in millisec‐
958             onds,  after  which  a started transport process should be termi‐
959             nated if it has not yet established a  connection.  For  example,
960             the following options on a connecting transport request a connec‐
961             tion with one peer over SCTP or another (typically the same) over
962             TCP.
963
964           {transport_module, diameter_sctp}
965           {transport_config, SctpOpts, 5000}
966           {transport_module, diameter_tcp}
967           {transport_config, TcpOpts}
968
969
970             To listen on both SCTP and TCP, define one transport for each.
971
972           {transport_module, atom()}:
973             Module  implementing  a  transport  process  as defined in diame‐
974             ter_transport(3). Defaults to diameter_tcp.
975
976             Multiple  transport_module  and  transport_config   options   are
977             allowed. The order of these is significant in this case (and only
978             in this case), a transport_module being  paired  with  the  first
979             transport_config following it in the options list, or the default
980             value for trailing modules. Transport starts  will  be  attempted
981             with each of the modules in order until one establishes a connec‐
982             tion within the corresponding timeout (see below) or all fail.
983
984           {watchdog_config, [{okay|suspect, non_neg_integer()}]}:
985             Configuration that alters the behaviour  of  the  watchdog  state
986             machine.  On  key  okay,  the non-negative number of answered DWR
987             messages before transitioning from REOPEN to OKAY.  On  key  sus‐
988             pect,  the  number of watchdog timeouts before transitioning from
989             OKAY to SUSPECT when DWR is unanswered, or  0  to  not  make  the
990             transition.
991
992             Defaults  to  [{okay,  3}, {suspect, 1}]. Not specifying a key is
993             equivalent to specifying the default value for that key.
994
995       Warning:
996           The default value is as required by RFC 3539: changing  it  results
997           in non-standard behaviour that should only be used to simulate mis‐
998           behaving nodes during test.
999
1000
1001           {watchdog_timer, TwInit}:
1002
1003
1004           TwInit = Unsigned32()
1005                  | {M,F,A}
1006
1007
1008             The RFC 3539 watchdog timer. An integer value is  interpreted  as
1009             the RFC's TwInit in milliseconds, a jitter of +/- 2 seconds being
1010             added at each rearming of the timer to compute the RFC's  Tw.  An
1011             MFA  is  expected  to  return  the RFC's Tw directly, with jitter
1012             applied, allowing the jitter calculation to be performed  by  the
1013             callback.
1014
1015             An  integer  value must be at least 6000 as required by RFC 3539.
1016             Defaults to 30000.
1017
1018           Unrecognized options are silently ignored but are returned  unmodi‐
1019           fied  by  service_info/2  and can be referred to in predicate func‐
1020           tions passed to remove_transport/2.
1021
1022         transport_ref() = reference():
1023           Reference returned by add_transport/2 that identifies the  configu‐
1024           ration.
1025

EXPORTS

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

SEE ALSO

1563       diameter_app(3), diameter_transport(3), diameter_dict(4)
1564
1565
1566
1567Ericsson AB                     diameter 2.2.1                     diameter(3)
Impressum