aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc/src/notes.xml
blob: aad86b966baaf7230c93c54f45cc70980d34959f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd" [
  <!ENTITY % also SYSTEM "seealso.ent" >
  <!ENTITY % here SYSTEM "seehere.ent" >
  %also;
  %here;
]>

<chapter>

<header>
<copyright>
<year>2011</year>
<year>2012</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.

Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.

</legalnotice>

<title>Release Notes</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>notes.xml</file>
</header>

<p>
Releases are listed in reverse chronological order, most recent
first.</p>

<!-- ===================================================================== -->

<section><title>Diameter 1.2</title>

    <section><title>Fixed Bugs and Malfunctions</title>
      <list>
        <item>
          <p>
	    Fix broken Result-Code setting and Destination-Host/Realm
	    extraction.</p>
          <p>
	    Result-Code was assumed to have arity 1 when setting this
	    value in an answer to a request containing AVP decode
	    errors. Destination-Host/Realm were only correctly
	    extracted from messages in the common application.</p>
          <p>
	    Own Id: OTP-10202</p>
        </item>
        <item>
          <p>
	    Handle insufficient capabilities configuration more
	    gracefully.</p>
          <p>
	    A transport that does not have sufficient capabilities
	    configuration in order to encode CER/CEA will now emit an
	    error report noting the configuration error and exit
	    instead of failing. The error is not detected at
	    diameter:add_transport/2 since there is no requirement
	    that a service be configured before its transports.</p>
          <p>
	    Own Id: OTP-10203</p>
        </item>
        <item>
          <p>
	    Ensure a failing peer_up/down callback does not affect
	    transport connections to other peers.</p>
          <p>
	    Such a failure would previously have taken down all of a
	    service's connections.</p>
          <p>
	    Own Id: OTP-10215</p>
        </item>
      </list>
    </section>


    <section><title>Improvements and New Features</title>
      <list>
        <item>
          <p>
	    Statistics related to Diameter messages can be retrieved
	    using diameter:service_info/2.</p>
          <p>
	    Both Diameter and socket-level statistics are available,
	    for both incoming and outgoing messages.</p>
          <p>
	    Own Id: OTP-9608</p>
        </item>
        <item>
          <p>
	    Allow multiple transport_module/config to
	    diameter:add_transport/2.</p>
          <p>
	    Multiple values are attempted in sequence until one
	    results in an established connection. This provides a way
	    for a connecting transport to specify configuration in
	    order of preference. (For example, SCTP before TCP.)</p>
          <p>
	    Own Id: OTP-9885</p>
        </item>
        <item>
          <p>
	    Add events for state transitions in the RFC 3539 watchdog
	    state machine.</p>
          <p>
	    The watchdog state is also available through
	    diameter:service_info/2.</p>
          <p>
	    Own Id: OTP-10212</p>
        </item>
        <item>
          <p>
	    Add diameter:service_info(SvcName, connections).</p>
          <p>
	    This provides an alternative to
	    diameter:service_info(SvcName, transport) that presents
	    information per established connection instead of per
	    transport reference.</p>
          <p>
	    Own Id: OTP-10213</p>
        </item>
        <item>
          <p>
	    Assorted documentation corrections/improvements.</p>
          <p>
	    Own Id: OTP-10216</p>
        </item>
      </list>
    </section>

</section>

<section><title>Diameter 1.0</title>

    <section><title>Fixed Bugs and Malfunctions</title>
      <list>
        <item>
          <p>
	    Fix faulty cleanup after diameter:remove_transport/2.</p>
          <p>
	    Removing a transport removed the configuration but did
	    not prevent the transport process from being restarted.</p>
          <p>
	    Own Id: OTP-9756</p>
        </item>
      </list>
    </section>


    <section><title>Improvements and New Features</title>
      <list>
        <item>
          <p>
	    Add support for TLS over TCP.</p>
          <p>
	    RFC 3588 requires that a Diameter server support TLS. In
	    practice this seems to mean TLS over SCTP since there are
	    limitations with running over SCTP: see RFC 6083 (DTLS
	    over SCTP), which is a response to RFC 3436 (TLS over
	    SCTP). The current RFC 3588 draft acknowledges this by
	    equating TLS with TLS/TCP and DTLS/SCTP.</p>
          <p>
	    TLS handshaking can take place either following a CER/CEA
	    that negotiates TLS using the Inband-Security-Id AVP (the
	    method documented in RFC 3588) or immediately following
	    connection establishment (the method added to the current
	    draft).</p>
          <p>
	    Own Id: OTP-9605</p>
        </item>
        <item>
          <p>
	    Improvements to the dictionary parser.</p>
          <p>
	    The dictionary parser now emits useful error messages in
	    case of faults in the input file, also identifying the
	    line number at which the fault was detected. There are
	    semantic checks that were missing in the previous parser,
	    a fault in the interpretation of vendor id's in
	    combination with @inherits has been fixed and @end can be
	    used to terminate parsing explicitly instead of always
	    parsing to end of file.</p>
          <p>
	    Own Id: OTP-9639</p>
        </item>
        <item>
          <p>
	    Improve dictionary reusability.</p>
          <p>
	    Reusing a dictionary just to get a different generated
	    module name or prefix previously required taking a copy
	    of the source, which may consist of several files if
	    inheritance is used, just to edit a couple of lines which
	    don't affect the semantics of the Diameter application
	    being defined. Options --name, --prefix and --inherits
	    have been added to diameterc to allow corresponding
	    values to be set at compile time.</p>
          <p>
	    Own Id: OTP-9641</p>
        </item>
        <item>
          <p>
	    Add capabilities_cb transport option.</p>
          <p>
	    Its value is a function that's applied to the transport
	    reference and capabilities record after capabilities
	    exchange. If a callback returns anything but 'ok' then
	    the connection is closed. In the case of an incoming CER,
	    the callback can return a result code with which to
	    answer. Multiple callbacks can be specified and are
	    applied until either all return 'ok' or one doesn't.</p>
          <p>
	    This provides a way to reject a peer connection.</p>
          <p>
	    Own Id: OTP-9654</p>
        </item>
        <item>
          <p>
	    Add @codecs to dictionary format.</p>
          <p>
	    The semantics are similar to @custom_types but results in
	    codec functions of the form TypeName(encode|decode,
	    AvpName, Data) rather than AvpName(encode|decode,
	    TypeName, Data). That is, the role of the AVP name and
	    Diameter type name are reversed. This eliminates the need
	    for exporting one function for each AVP sharing a common
	    specialized encode/decode.</p>
          <p>
	    Own Id: OTP-9708 Aux Id: OTP-9639 </p>
        </item>
        <item>
          <p>
	    Add #diameter_callback{} for more flexible callback
	    configuration.</p>
          <p>
	    The record allows individual functions to be configured
	    for each of the diameter_app(3) callbacks, as well as a
	    default callback.</p>
          <p>
	    Own Id: OTP-9777</p>
        </item>
      </list>
    </section>

</section>

<section><title>Diameter 0.10</title>

    <section><title>Fixed Bugs and Malfunctions</title>
      <list>
        <item>
          <p>
	    Handle #sctp_paddr_change and #sctp_pdapi_event from
	    gen_sctp.</p>
          <p>
	    The events are enabled by default but diameter_sctp
	    neither disabled nor dealt with them. Reception of such
	    an event caused a transport process to crash.</p>
          <p>
	    Own Id: OTP-9538</p>
        </item>
        <item>
          <p>
	    Fix header folding bug.</p>
          <p>
	    A prepare_request callback from diameter can return a
	    diameter_header record in order to set values in the
	    header of an outgoing request. A fault in
	    diameter_lib:fold_tuple/3 caused the subsequent encode of
	    the outgoing request to fail.</p>
          <p>
	    Own Id: OTP-9577</p>
        </item>
        <item>
          <p>
	    Fix bugs in sending of answer-message replies.</p>
          <p>
	    3001 (DIAMETER_COMMAND_UNSUPPORTED) was not sent since
	    the decode placed the AVP list in the wrong field of the
	    diameter_packet, causing the subsequent encode to fail.
	    Session-Id was also set improperly, causing encode to
	    fail even in this case.</p>
          <p>
	    Own Id: OTP-9578</p>
        </item>
        <item>
          <p>
	    Fix improper use of error_logger:info_report/2.</p>
          <p>
	    Function doesn't take a format string and arguments as it
	    was called. Instead use error_logger:info_report/1 and
	    use the same report format as used for warning and error
	    reports.</p>
          <p>
	    Own Id: OTP-9579</p>
        </item>
        <item>
          <p>
	    Fix and clarify semantics of peer filters.</p>
          <p>
	    An eval filter returning a non-true value caused the call
	    process to fail and the doc was vague on how an exception
	    was treated. Clarify that the non-tuple host/realm
	    filters assume messages of a certain form.</p>
          <p>
	    Own Id: OTP-9580</p>
        </item>
        <item>
          <p>
	    Fix and clarify relay behaviour.</p>
          <p>
	    Implicit filtering of the sending peer in relaying a
	    request could cause loop detection to be preempted in a
	    manner not specified by RFC3588. Reply with 3002
	    (DIAMETER_UNABLE_TO_DELIVER) on anything but an answer to
	    a relayed request.</p>
          <p>
	    Own Id: OTP-9583</p>
        </item>
      </list>
    </section>


    <section><title>Improvements and New Features</title>
      <list>
        <item>
          <p>
	    @id required in dictionary files only when @messages is
	    specified.</p>
          <p>
	    @id defines an application identifier and this is used
	    only when sending or receiving messages. A dictionary can
	    define only AVP's however, to be included by other
	    dictionaries using @inherits, in which case it makes no
	    sense to require @id.</p>
          <p>
	    Note that message definitions are not inherited with
	    @inherits, only AVP's</p>
          <p>
	    Own Id: OTP-9467</p>
        </item>
        <item>
          <p>
	    Allow @enum when AVP is defined in an inherited
	    dictionary.</p>
          <p>
	    3GPP standards (for one) extend the values allowed for
	    RFC 3588 AVP's of type Enumerated. Previously, extending
	    an AVP was only possible by completely redefining the
	    AVP.</p>
          <p>
	    Own Id: OTP-9469</p>
        </item>
        <item>
          <p>
	    Migrate testsuites to pure common test and add both
	    suites and testcases.</p>
          <p>
	    Own Id: OTP-9553</p>
        </item>
        <item>
          <p>
	    Requests of arbitrary form.</p>
          <p>
	    diameter:call/4 can be passed anything, as long as the
	    subsequent prepare_request callback returns a term that
	    can be encoded.</p>
          <p>
	    Own Id: OTP-9581</p>
        </item>
      </list>
    </section>

</section>

<section>
<title>diameter 0.9</title>

<p>
Initial release of the diameter application.</p>

<p>
Known issues or limitations:</p>

<list>

<item>
<p>
Some agent-related functionality is not entirely complete.
In particular, support for proxy agents, that advertise specific
Diameter applications but otherwise relay messages in much the same
way as relay agents (for which a &handle_request;
callback can return a <c>relay</c> tuple), will be completed in an
upcoming release.
There may also be more explicit support for redirect agents, although
redirect behaviour can be implemented with the current
functionality.</p>

</item>

<item>
<p>
There is some asymmetry in the treatment of messages sent as
<c>diameter_header/avp</c> records and those sent in the "normal"
fashion, and not all of this is documented.
This is related to the previous point since this form of sending a
message was introduced specifically to handle relay agent behaviour
using the same callback interface as for client/server behaviour.</p>
</item>

<item>
<p>
The User's Guide is currently quite thin.
The introductory chapter followed by the examples (in the application
<c>examples</c> subdirectory) may be sufficient
for those having some familiarity with the Diameter protocol but the
intention is to provide more introductory text.
The reference documentation is quite complete, although some points
could likely be expanded upon.</p>
</item>

<item>
<p>
The function &service_info;
can be used to retrieve information about a started service
(statistics, information about connected peers, etc) but
this is not yet documented and both the input and output may change
in the next release.</p>
</item>


</list>

<p>
See <seealso marker="diameter_soc">Standards Compliance</seealso> for
standards-related issues.</p>
</section>

</chapter>