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

NAME

6       diameter_tcp - Diameter transport over TCP.
7

DESCRIPTION

9       This module implements diameter transport over TCP using gen_tcp(3). It
10       can be specified as the value of a transport_module  option  to  diame‐
11       ter:add_transport/2  and  implements the behaviour documented in diame‐
12       ter_transport(3). TLS security is supported, either as an upgrade  fol‐
13       lowing capabilities exchange or at connection establishment.
14
15       Note  that  the ssl application is required for TLS and must be started
16       before configuring TLS capability on diameter transports.
17

EXPORTS

19       start({Type, Ref}, Svc, [Opt]) -> {ok, Pid} | {ok, Pid, [LAddr]} | {er‐
20       ror, Reason}
21
22              Types:
23
24                 Type = connect | accept
25                 Ref = diameter:transport_ref()
26                 Svc = #diameter_service{}
27                 Opt = OwnOpt | SslOpt | TcpOpt
28                 Pid = pid()
29                 LAddr = inet:ip_address()
30                 Reason = term()
31                 OwnOpt  =  {raddr,  inet:ip_address()} | {rport, integer()} |
32                 {accept, Match} | {port, integer()} | {fragment_timer, infin‐
33                 ity  |  0..16#FFFFFFFF}  |  {message_cb,  diameter:eval()}  |
34                 {sender, boolean()}
35                 SslOpt = {ssl_options, true | list()}
36                 TcpOpt = term()
37                 Match = inet:ip_address() | string() | [Match]
38
39              The start function required by diameter_transport(3).
40
41              Options raddr and rport specify the remote address and port  for
42              a  connecting transport and are not valid for a listening trans‐
43              port.
44
45              Option accept specifies remote addresses for a listening  trans‐
46              port  and is not valid for a connecting transport. If specified,
47              a remote address that does not match one of  the  specified  ad‐
48              dresses causes the connection to be aborted. Multiple accept op‐
49              tions can be specified. A  string-valued  Match  that  does  not
50              parse as an address is interpreted as a regular expression.
51
52              Option ssl_options must be specified for a transport that should
53              support TLS: a value of true results in a TLS handshake  immedi‐
54              ately  upon  connection establishment while list() specifies op‐
55              tions to be passed to ssl:connect/2 or ssl:handshake/2 after ca‐
56              pabilities exchange if TLS is negotiated.
57
58              Option fragment_timer specifies the timeout, in milliseconds, of
59              a timer used to flush messages from  the  incoming  byte  stream
60              even  if  the  number  of  bytes indicated in the Message Length
61              field of its Diameter Header have not yet been accumulated: such
62              a  message  is  received  over the transport interface after two
63              successive timeouts without the reception of  additional  bytes.
64              Defaults to 1000.
65
66              Option  sender  specifies  whether  or  not  to  use a dedicated
67              process for sending outgoing messages, which avoids  the  possi‐
68              bility  of send blocking reception. Defaults to false. If set to
69              true then a message_cb that avoids the possibility  of  messages
70              being  queued in the sender process without bound should be con‐
71              figured.
72
73              Option message_cb specifies a callback that is invoked on incom‐
74              ing  and  outgoing  messages, that can be used to implement flow
75              control. It is applied to two arguments: an atom indicating  the
76              reason  for  the  callback (send, recv, or ack after a completed
77              send), and the message in question (binary() on  recv,  binary()
78              or  diameter_packet  record on send or ack, or false on ack when
79              an incoming request has been discarded). It should return a list
80              of  actions  and  a new callback as tail; eg. [fun cb/3, State].
81              Valid actions are the atoms send or recv, to cause  a  following
82              message-valued action to be sent/received, a message to send/re‐
83              ceive (binary() or diameter_packet record), or  a  boolean()  to
84              enable/disable   reading   on   the   socket.   More   than  one
85              send/recv/message sequence can be returned from the  same  call‐
86              back, and an initial send/recv can be omitted if the same as the
87              value passed as the callback's first argument. Reading  is  ini‐
88              tially  enabled, and returning false does not imply there cannot
89              be subsequent recv callbacks since  messages  may  already  have
90              been  read.  An empty tail is equivalent to the prevailing call‐
91              back. Defaults to a callback equivalent to fun(ack,  _)  ->  [];
92              (_, Msg) -> [Msg] end.
93
94              Remaining   options   are   any  accepted  by  ssl:connect/3  or
95              gen_tcp:connect/3 for a connecting transport, or ssl:listen/2 or
96              gen_tcp:listen/2 for a listening transport, depending on whether
97              or not {ssl_options, true} has been specified.  Options  binary,
98              packet  and active cannot be specified. Also, option port can be
99              specified for a listening transport to specify the local listen‐
100              ing port, the default being the standardized 3868. Note that the
101              option ip specifies the local address.
102
103              An ssl_options list must be specified if and only if the  trans‐
104              port in question has set Inband-Security-Id to 1 (TLS), as spec‐
105              ified to either diameter:start_service/2 or  diameter:add_trans‐
106              port/2,  so that the transport process will receive notification
107              of whether or not to commence with a TLS handshake following ca‐
108              pabilities  exchange.  Failing  to  specify an options list on a
109              TLS-capable transport for which TLS is negotiated will cause TLS
110              handshake  to  fail.  Failing  to  specify  TLS  capability when
111              ssl_options has been specified will cause the transport  process
112              to  wait  for a notification that will not be forthcoming, which
113              will eventually cause the RFC 3539 watchdog  to  take  down  the
114              connection.
115
116              The  first  element  of  a non-empty Host-IP-Address list in Svc
117              provides the local IP address if an ip option is not  specified.
118              The  local address is either returned fromstart/3 or passed in a
119              connected message over the transport interface.
120

SEE ALSO

122       diameter(3), diameter_transport(3), gen_tcp(3), inet(3), ssl(3)
123
124
125
126Ericsson AB                      diameter 2.3                  diameter_tcp(3)
Impressum