bionic (5) diameter_dict.5.gz

Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug

NAME

       diameter_dict - Dictionary interface of the diameter application.

DESCRIPTION

       A diameter service, as configured with diameter:start_service/2, specifies one or more supported Diameter
       applications. Each Diameter application specifies a dictionary module that knows how to encode and decode
       its messages and AVPs. The dictionary module is in turn generated from a file that defines these messages
       and AVPs. The format of such a file is defined in FILE FORMAT below. Users add support for their specific
       applications  by creating dictionary files, compiling them to Erlang modules using either diameterc(1) or
       diameter_make(3erl) and configuring the resulting dictionaries modules on a service.

       Dictionary module generation also results in a hrl file that defines records for the messages and Grouped
       AVPs  defined  by  the  dictionary, these records being what a user of the diameter application sends and
       receives, modulo other possible formats  as  discussed  in  diameter_app(3erl).  These  records  and  the
       underlying  Erlang data types corresponding to Diameter data formats are discussed in MESSAGE RECORDS and
       DATA TYPES respectively. The generated hrl also contains macro definitions for  the  possible  values  of
       AVPs of type Enumerated.

       The  diameter  application  includes  five  dictionary  modules  corresponding to applications defined in
       section 2.4 of RFC 6733: diameter_gen_base_rfc3588 and diameter_gen_base_rfc6733 for the Diameter  Common
       Messages   application  with  application  identifier  0,  diameter_gen_accounting  (for  RFC  3588)  and
       diameter_gen_acct_rfc6733 for the Diameter Base Accounting application with application identifier 3  and
       diameter_gen_relay the Relay application with application identifier 0xFFFFFFFF.

       The Common Message and Relay applications are the only applications that diameter itself has any specific
       knowledge of. The Common Message application is used for messages that diameter itself handles:  CER/CEA,
       DWR/DWA  and DPR/DPA. The Relay application is given special treatment with regard to encode/decode since
       the messages and AVPs it handles are not specifically defined.

FILE FORMAT

       A dictionary file consists of distinct sections. Each section starts with a tag followed by zero or  more
       arguments  and  ends  at  the  the start of the next section or end of file. Tags consist of an ampersand
       character followed by a keyword  and  are  separated  from  their  arguments  by  whitespace.  Whitespace
       separates individual tokens but is otherwise insignificant.

       The tags, their arguments and the contents of each corresponding section are as follows. Each section can
       occur multiple  times  unless  otherwise  specified.  The  order  in  which  sections  are  specified  is
       unimportant.

         @id Number:
           Defines  the  integer Number as the Diameter Application Id of the application in question. Can occur
           at most once and is required if the dictionary defines @messages. The section has empty content.

           The Application Id is set in the Diameter Header of outgoing messages of  the  application,  and  the
           value in the header of an incoming message is used to identify the relevant dictionary module.

           Example:

         @id 16777231

         @name Mod:
           Defines  the name of the generated dictionary module. Can occur at most once and defaults to the name
           of the dictionary file minus any extension. The section has empty content.

           Note that a dictionary module should have a unique name so as not collide with  existing  modules  in
           the system.

           Example:

         @name etsi_e2

         @prefix Name:
           Defines  Name as the prefix to be added to record and constant names (followed by a '_' character) in
           the generated dictionary module and hrl. Can occur at most once. The section has empty content.

           A prefix is optional but can be be used to disambiguate between record and constant  names  resulting
           from similarly named messages and AVPs in different Diameter applications.

           Example:

         @prefix etsi_e2

         @vendor Number Name:
           Defines  the  integer  Number  as the the default Vendor-Id of AVPs for which the V flag is set. Name
           documents the owner of the application but is otherwise  unused.  Can  occur  at  most  once  and  is
           required  if  an AVP sets the V flag and is not otherwise assigned a Vendor-Id. The section has empty
           content.

           Example:

         @vendor 13019 ETSI

         @avp_vendor_id Number:
           Defines the integer Number as the Vendor-Id of the AVPs listed in the section content, overriding the
           @vendor default. The section content consists of AVP names.

           Example:

         @avp_vendor_id 2937

         WWW-Auth
         Domain-Index
         Region-Set

         @inherits Mod:
           Defines  the  name of a dictionary module containing AVP definitions that should be imported into the
           current dictionary. The section content consists of the names of those AVPs whose definitions  should
           be  imported  from the dictionary, an empty list causing all to be imported. Any listed AVPs must not
           be defined in the current dictionary and it is an error to inherit the same AVP from  more  than  one
           dictionary.

           Note that an inherited AVP that sets the V flag takes its Vendor-Id from either @avp_vendor_id in the
           inheriting dictionary or @vendor in the inherited dictionary. In particular,  @avp_vendor_id  in  the
           inherited  dictionary is ignored. Inheriting from a dictionary that specifies the required @vendor is
           equivalent to using @avp_vendor_id with a copy of the dictionary's definitions but the  former  makes
           for easier reuse.

           All dictionaries should typically inherit RFC 6733 AVPs from diameter_gen_base_rfc6733.

           Example:

         @inherits diameter_gen_base_rfc6733

         @avp_types:
           Defines the name, code, type and flags of individual AVPs. The section consists of definitions of the
           form

           Name Code Type Flags

           where Code is the integer AVP code, Type identifies an AVP Data Format as  defined  in  section  DATA
           TYPES  below,  and  Flags  is  a string of V, M and P characters indicating the flags to be set on an
           outgoing AVP or a single '-' (minus) character if none are to be set.

           Example:

         @avp_types

         Location-Information   350  Grouped     MV
         Requested-Information  353  Enumerated   V

     Warning:
         The P flag has been deprecated by RFC 6733.

         @custom_types Mod:
           Specifies AVPs for which module Mod provides encode/decode functions. The section  contents  consists
           of  AVP  names.  For each such name, Mod:Name(encode|decode, Type, Data, Opts) is expected to provide
           encode/decode for values of the AVP, where Name is the name of the AVP, Type is it's type as declared
           in  the  @avp_types section of the dictionary, Data is the value to encode/decode, and Opts is a term
           that is passed through encode/decode.

           Example:

         @custom_types rfc4005_avps

         Framed-IP-Address

         @codecs Mod:
           Like @custom_types but requires the specified module to export  Mod:Type(encode|decode,  Name,  Data,
           Opts) rather than Mod:Name(encode|decode, Type, Data, Opts).

           Example:

         @codecs rfc4005_avps

         Framed-IP-Address

         @messages:
           Defines  the  messages  of  the  application. The section content consists of definitions of the form
           specified in section 3.2 of RFC 6733, "Command Code Format Specification".

         @messages

         RTR ::= < Diameter Header: 287, REQ, PXY >
                 < Session-Id >
                 { Auth-Application-Id }
                 { Auth-Session-State }
                 { Origin-Host }
                 { Origin-Realm }
                 { Destination-Host }
                 { SIP-Deregistration-Reason }
                 [ Destination-Realm ]
                 [ User-Name ]
               * [ SIP-AOR ]
               * [ Proxy-Info ]
               * [ Route-Record ]
               * [ AVP ]

         RTA ::= < Diameter Header: 287, PXY >
                 < Session-Id >
                 { Auth-Application-Id }
                 { Result-Code }
                 { Auth-Session-State }
                 { Origin-Host }
                 { Origin-Realm }
                 [ Authorization-Lifetime ]
                 [ Auth-Grace-Period ]
                 [ Redirect-Host ]
                 [ Redirect-Host-Usage ]
                 [ Redirect-Max-Cache-Time ]
               * [ Proxy-Info ]
               * [ Route-Record ]
               * [ AVP ]

         @grouped:
           Defines the contents of the AVPs of the application having type Grouped. The section content consists
           of definitions of the form specified in section 4.4 of RFC 6733, "Grouped AVP Values".

           Example:

         @grouped

         SIP-Deregistration-Reason ::= < AVP Header: 383 >
                                       { SIP-Reason-Code }
                                       [ SIP-Reason-Info ]
                                     * [ AVP ]

           Specifying  a  Vendor-Id  in  the  definition  of  a  grouped AVP is equivalent to specifying it with
           @avp_vendor_id.

         @enum Name:
           Defines  values  of  AVP  Name  having  type  Enumerated.  Section  content  consists  of  names  and
           corresponding  integer  values.  Integer  values  can  be  prefixed  with  0x  to  be  interpreted as
           hexadecimal.

           Note that the AVP in question can be defined  in  an  inherited  dictionary  in  order  to  introduce
           additional values to an enumeration otherwise defined in another dictionary.

           Example:

         @enum SIP-Reason-Code

         PERMANENT_TERMINATION    0
         NEW_SIP_SERVER_ASSIGNED  1
         SIP_SERVER_CHANGE        2
         REMOVE_SIP_SERVER        3

         @end:
           Causes parsing of the dictionary to terminate: any remaining content is ignored.

       Comments can be included in a dictionary file using semicolon: characters from a semicolon to end of line
       are ignored.

MESSAGE RECORDS

       The hrl generated from a dictionary specification defines records  for  the  messages  and  grouped  AVPs
       defined  in  @messages  and  @grouped  sections.  For each message or grouped AVP definition, a record is
       defined whose name is the message or AVP name, prefixed with any dictionary prefix defined with  @prefix,
       and whose fields are the names of the AVPs contained in the message or grouped AVP in the order specified
       in the definition in question. For example, the grouped AVP

       SIP-Deregistration-Reason ::= < AVP Header: 383 >
                                     { SIP-Reason-Code }
                                     [ SIP-Reason-Info ]
                                   * [ AVP ]

       will result in the following record definition given an empty prefix.

       -record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
                                            'SIP-Reason-Info',
                                            'AVP'}).

       The values encoded in the fields of generated records depends on the type and number of times the AVP can
       occur.  In  particular,  an AVP which is specified as occurring exactly once is encoded as a value of the
       AVP's type while an AVP with any other specification is encoded as a list of values of  the  AVP's  type.
       The AVP's type is as specified in the AVP definition, the RFC 6733 types being described below.

DATA TYPES

       The  data formats defined in sections 4.2 ("Basic AVP Data Formats") and 4.3 ("Derived AVP Data Formats")
       of RFC 6733 are encoded as values of the types defined here. Values are passed to  diameter:call/4  in  a
       request  record  when  sending  a  request,  returned  in  a  resulting  answer  record  and  passed to a
       handle_request/3 callback upon reception of an incoming request.

       In cases in which there is a choice between string() and binary() types  for  OctetString()  and  derived
       types, the representation is determined by the value of diameter:service_opt() string_decode.

       Basic AVP Data Formats

       OctetString() = string() | binary()
       Integer32()   = -2147483647..2147483647
       Integer64()   = -9223372036854775807..9223372036854775807
       Unsigned32()  = 0..4294967295
       Unsigned64()  = 0..18446744073709551615
       Float32()     = '-infinity' | float() | infinity
       Float64()     = '-infinity' | float() | infinity
       Grouped()     = record()

       On encode, an OctetString() can be specified as an iolist(), excessively large floats (in absolute value)
       are equivalent to infinity or '-infinity' and excessively large integers result in  encode  failure.  The
       records for grouped AVPs are as discussed in the previous section.

       Derived AVP Data Formats

       Address() = OctetString()
                 | tuple()

       On  encode,  an OctetString() IPv4 address is parsed in the usual x.x.x.x format while an IPv6 address is
       parsed in any of the formats specified by section 2.2 of RFC 2373, "Text Representation of Addresses". An
       IPv4  tuple()  has length 4 and contains values of type 0..255. An IPv6 tuple() has length 8 and contains
       values of type 0..65535. The tuple representation is used on decode.

       Time() = {date(), time()}

       where

         date() = {Year, Month, Day}
         time() = {Hour, Minute, Second}

         Year   = integer()
         Month  = 1..12
         Day    = 1..31
         Hour   = 0..23
         Minute = 0..59
         Second = 0..59

       Additionally, values that can be encoded are limited by way of their encoding as four octets as  required
       by   RFC   6733  with  the  required  extension  from  RFC  2030.  In  particular,  only  values  between
       {{1968,1,20},{3,14,8}} and {{2104,2,26},{9,42,23}} (both inclusive) can be encoded.

       UTF8String() = [integer()] | binary()

       List elements are the UTF-8 encodings of the individual characters in the string. Invalid codepoints will
       result  in  encode/decode failure. On encode, a UTF8String() can be specified as a binary, or as a nested
       list of binaries and codepoints.

       DiameterIdentity() = OctetString()

       A value must have length at least 1.

       DiameterURI() = OctetString()
                     | #diameter_URI{type = Type,
                                     fqdn = FQDN,
                                     port = Port,
                                     transport = Transport,
                                     protocol  = Protocol}

       where

         Type = aaa | aaas
         FQDN = OctetString()
         Port = integer()
         Transport = sctp | tcp
         Protocol  = diameter | radius | 'tacacs+'

       On encode, fields port, transport and protocol default to  3868,  sctp  and  diameter  respectively.  The
       grammar  of  an  OctetString-valued  DiameterURI() is as specified in section 4.3 of RFC 6733. The record
       representation is used on decode.

       Enumerated() = Integer32()

       On encode, values can be specified using the macros defined in a dictionary's hrl file.

       IPFilterRule()  = OctetString()
       QoSFilterRule() = OctetString()

       Values of these types are not currently parsed by diameter.

SEE ALSO

       diameterc(1), diameter(3erl), diameter_app(3erl), diameter_codec(3erl), diameter_make(3erl)