<?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>2013</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.4.1</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Fix erroneous watchdog transition from DOWN to INITIAL.</p>
<p>
This transition took place when a peer connection was
reestablished following a failed capabilities exchange.
RFC 3539 requires DOWN to transition into REOPEN.</p>
<p>
Own Id: OTP-10692</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Add application_opt() request_errors to make the handling
of incoming requests containing decode errors
configurable.</p>
<p>
The value 'callback' ensures that a handle_request
callback takes place for all such requests, the default
being for diameter to answer 3xxx series errors itself.</p>
<p>
Own Id: OTP-10686</p>
</item>
<item>
<p>
Add transport_opt() length_errors.</p>
<p>
The value determines how messages received over the
transport interface with an incorrect Message Length are
dealt with.</p>
<p>
Own Id: OTP-10687</p>
</item>
<item>
<p>
Add commentary on RFC 6733 to Standards Compliance
chapter of the User's Guide.</p>
<p>
Own Id: OTP-10688</p>
</item>
<item>
<p>
Allow a 5xxx result code in an answer-message on peer
connections using the RFC 6733 common dictionary.</p>
<p>
RFC 6733 allows this while RFC 3588 does not. A
handle_request callback can return {answer_message,
3000..3999|5000..5999} in the simplest case.</p>
<p>
Own Id: OTP-10759</p>
</item>
<item>
<p>
Add dictionaries for RFC 6733.</p>
<p>
Both the common and accounting dictionaries differ from
their RFC 3588 counterparts, which is reflected in
generated record definitions. Application configuration
on a service or transport determines the dictionary that
will be used on a given peer connection.</p>
<p>
Own Id: OTP-10760</p>
</item>
<item>
<p>
Allow a handle_request callback to control diameter's
setting of Result-Code and Failed-AVP.</p>
<p>
Setting errors = false in a returned #diameter_packet{}
disables the setting.</p>
<p>
Own Id: OTP-10761</p>
</item>
</list>
</section>
</section>
<section><title>Diameter 1.4</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Add registered server names to the app file.</p>
<p>
Own Id: OTP-10442</p>
</item>
<item>
<p>
Fix #diameter_header{} handling broken by OTP-10445.</p>
<p>
The fault caused the the header of a [Header | Avps]
request to be ignored if both end_to_end_id and
hop_by_hop_id were undefined.</p>
<p>
Own Id: OTP-10609</p>
</item>
<item>
<p>
Fix error handling for handle_request callback.</p>
<p>
A callback that returned a #diameter_packet{} would fail
if the incoming request had decode errors.</p>
<p>
Own Id: OTP-10614</p>
</item>
<item>
<p>
Fix timing of service start event.</p>
<p>
The event did not necessarily precede other events as
documented.</p>
<p>
Own Id: OTP-10618</p>
</item>
<item>
<p>
Fix setting of header T flag at peer failover.</p>
<p>
The flag is now set in the diameter_header record passed
to a prepare_retransmit callback.</p>
<p>
Own Id: OTP-10619</p>
</item>
<item>
<p>
Fix sending of CER/CEA timeout event at capx_timeout.</p>
<p>
The event was not sent as documented.</p>
<p>
Own Id: OTP-10628</p>
</item>
<item>
<p>
Fix improper setting of Application-ID in the Diameter
header of an answer message whose E flag is set.</p>
<p>
The value should be that of the request in question. The
fault caused it always to be 0.</p>
<p>
Own Id: OTP-10655</p>
</item>
<item>
<p>
Fix faulty handling of AVP length errors.</p>
<p>
An incorrect AVP length but no other errors caused an
incoming request to fail.</p>
<p>
Own Id: OTP-10693</p>
</item>
</list>
</section>
</section>
<section><title>Diameter 1.3.1</title>
<section><title>Known Bugs and Problems</title>
<list>
<item>
<p>
Fix function clause resulting from use of an eval
callback.</p>
<p>
Own Id: OTP-10685</p>
</item>
</list>
</section>
</section>
<section><title>Diameter 1.3</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Fix faulty handling of Origin-State-Id and faulty config
values.</p>
<p>
The former was expected in a list despite the
documentation requiring (correctly) an integer. A bare
value for a list-valued capability was not handled.</p>
<p>
Own Id: OTP-10440</p>
</item>
<item>
<p>
Fix timing of up/down events.</p>
<p>
Previously, a call to diameter:call/4 following a peer_up
callback might incorrectly return {error, no_connection},
depending on timing. Both events now follow the
corresponding callbacks.</p>
<p>
Own Id: OTP-10459</p>
</item>
<item>
<p>
Make diameter:service_info/2 usable in peer_up, peer_down
and pick_peer callbacks.</p>
<p>
Except for in pick_peer when {call_mutates_state, false},
it would previously hang indefinitely.</p>
<p>
Own Id: OTP-10460</p>
</item>
<item>
<p>
Verify that End-to-End and Hop-by-Hop Identifiers in an
incoming CEA/DPA match those sent in the corresponding
CER/DPR.</p>
<p>
The values were previously ignored. Answers whose
identifiers do not match are handled as unexpected.</p>
<p>
Own Id: OTP-10565</p>
</item>
<item>
<p>
Fix formatting problems in PDF documentation.</p>
<p>
In particular, text corresponding to links in HTML was
omitted in preformatted blocks. There are still issues
with indentation but this is not diameter-specific.</p>
<p>
Own Id: OTP-10583</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Let prepare_request, prepare_retransmit and
handle_request callbacks return a function to be invoked
on outgoing messages after encode.</p>
<p>
This allows encoded messages to be logged for example.</p>
<p>
Own Id: OTP-10441</p>
</item>
<item>
<p>
Add service_opt() 'restrict_connections' to allow
multiple transport connections with the same peer.</p>
<p>
Own Id: OTP-10443</p>
</item>
<item>
<p>
Add service_opt() 'sequence' to allow the masking of a
constant onto the topmost bits of End-to-End and
Hop-by-Hop identifiers.</p>
<p>
This allows the same service on different nodes to use
distinct values in outgoing request messages.</p>
<p>
Own Id: OTP-10445</p>
</item>
<item>
<p>
Add diameter:service_info(PeerRef) to return the
transport_ref() and transport_opt() list of the
corresponding transport.</p>
<p>
This allows easy access to these from diameter_app
callbacks that only get peer_ref() as an argument.</p>
<p>
Own Id: OTP-10470</p>
</item>
<item>
<p>
Add reference pages diameter_codec(3) and
diameter_make(3).</p>
<p>
Own Id: OTP-10471</p>
</item>
<item>
<p>
Add events for service start and stop.</p>
<p>
Own Id: OTP-10492</p>
</item>
<item>
<p>
Add transport_opt() 'disconnect_cb' to make the sending
of DPR configurable.</p>
<p>
Whether or not DPR should be sent at application stop,
service stop or transport removal is determined by the
value returned by the callback, as is the
Disconnect-Cause and timeout if DPA is not received.</p>
<p>
Own Id: OTP-10493</p>
</item>
<item>
<p>
Add transport_opt() 'capx_timeout' for the timeout
associated with non-reception of CER/CEA.</p>
<p>
Own Id: OTP-10554</p>
</item>
<item>
<p>
Allow a handle_request callback to return a
#diameter_packet{}.</p>
<p>
This allows an answer to set transport_data and header
fields.</p>
<p>
Own Id: OTP-10566</p>
</item>
<item>
<p>
Update documentation for RFC 6733.</p>
<p>
RFC 3588 is now obsolete.</p>
<p>
Own Id: OTP-10568</p>
</item>
</list>
</section>
</section>
<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.1</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Fix fault in sending of 'closed' events.</p>
<p>
The fault made it possible for the 'closed' event not to
be sent following a failed capabilities exchange.</p>
<p>
Own Id: OTP-9824</p>
</item>
<item>
<p>
Fix faulty diameterc -name/-prefix.</p>
<p>
A minor blunder when introducing the new dictionary
parser in diameter-1.0 broke these options.</p>
<p>
Own Id: OTP-9826</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 diameter:service_info/2
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>
