1diameter_tcp(3) Erlang Module Definition diameter_tcp(3)
2
6 diameter_tcp - Diameter transport over TCP.
7
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 Note that the ssl application is required for TLS and must be started
16 before configuring TLS capability on diameter transports.
17
19 start({Type, Ref}, Svc, [Opt]) -> {ok, Pid} | {ok, Pid, [LAddr]} | {er‐
20 ror, Reason}
21 Types:
23 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 The start function required by diameter_transport(3).
40 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 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 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 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 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 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 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 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 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
122 diameter(3), diameter_transport(3), gen_tcp(3), inet(3), ssl(3)
123Ericsson AB diameter 2.3 diameter_tcp(3)