DO NOT SHARE THESE DOCS WITH CUSTOMERS!

This is an LA release that will only be provided to a select number of PLM-sanctioned customers (PDFs only). Contact PLM for details.


Overview

Service Discovery allows you to specify FQDNs instead of static IP addresses for services whose IP addresses occasionally change. The following topics explain how to configure the SBC for DNS-based Service Discovery (DNS-SD) and how to define FQDNs for Service Discovery following standard DNS-SD naming conventions.

Configuration Steps

To configure Service Discovery for trap target destinations and EMS registration, perform the following three steps:

  1. Configure Service Discovery for trap target destinations
  2. Configure Service Discovery for EMS registration
  3. Configure SBC Service Discovery

The sections below explain how to perform each step. For complete explanations of individual commands, refer to the appropriate command descriptions in the CLI Reference Guide.

Notes
  1. Ribbon recommends configuring Service Discovery first, before setting the EMS and trap configurations.
  2. When defining an FQDN, use the following naming convention for the three parts – Instance, Service and Domain – of the FQDN:

    • The <Instance> part clearly and unambiguously describes the nature of the instance offering the service.

    • The <Service> part identifies what the service does and what application protocol it uses to do it. The service name consists of a pair of DNS labels:

      • The first label of the pair is an underscore character followed by the Service Name (e.g. “_ems”, “_mrfp”,”_snmp-trap”).

      • The second label is either "_udp" or "_tcp", where "_tcp" is used for application protocols that run over TCP and "_udp"is used for all other protocols, even if not UDP (e.g. SCTP).

    • The <Domain> part specifies the DNS subdomain within which those names are subscribed to. You can also break down the domain into subdomains whenever it is appropriate to subdivide the logical service boundaries (split per geographical areas, per the type of security policies applied to the services, etc.).

    For example, a valid FQDN for a trap target, group1._snmp-trap._udp.test.sd.rbbn.com, is subdivided into:

    • Instance = group1 

    • Service (and protocol) = _snmp-trap._udp

    • Domain = test.sd.rbbn.com

    Important: You must also enter the FQDNs and their associated IP addresses into the Service Registry (DNS Server) in order for FQDNs to be resolved. See the topic  Standard FQDN Naming Conventions below for a more complete discussion of the naming convention and structure of FQDNs and examples showing the entries in the DNS Server that may be used for DNS-based Service Discovery.

Configuring Service Discovery for Trap Target Destinations

If you wish to use Service Discovery instead of a static IP address to determine a trap target , define an FQDN for the trap target:

set oam snmp trapTarget <name of target> fqdn <FQDN of the trap target>

Example command:

set oam snmp trapTarget trapX fqdn group1._snmp-trap._udp.test.sd.rbbn.com

You may also define an IP address for the trap target.

Example command:

set oam snmp trapTarget trapX ipAddress 10.0.0.1 port 162

If an IP address and FQDN are both specified for a particular trap target, the SBC uses the resolved addresses from the FQDN first. If no resolved IP addresses are available,  then the trap target falls back to the IP address specified by the ipAddress value.

For a complete explanation of the set oam snmp command, refer to SNMP - CLI in the CLI Reference Guide.

Configuring Service Discovery for EMS Registration

Here is a brief explanation of how Service Discovery and an FQDN work to accomplish EMS registration:

The SBC first learns the location of available EMS IPs through the metadata with an added field for an FQDN. The SBC then learns about changes to the EMS IPs by subscribing the proper Service Name (FQDN) and updating its list of available EMS IP addresses based on the queries executed by the Service Discovery for that service. The SBC then examines its list to select which EMS to register to. The SBC also uses the Service Discovery framework to detect any future changes and perform registration to a new EMS when needed.

If you wish to use Service Discovery instead of a static IP address to perform EMS registration, define an FQDN using the following command, and then reboot the SBC:

set system ems emsFqdn <FQDN of the EMS server>

Example command:

set system ems emsFqdn dev1._ems._tcp.test.sd.rbbn.com

Later if you wish to override an EMS FQDN, you can define one or more (up to eight) EMS override addresses, and then reboot. The SBC will try to register based on the oldest override value first, and will stop once a registration succeeds. The command to define an override address is:

set system ems emsIpAddressOverride <EMS IP addresses to enforce for EMS server registration>

Example command:

set system ems emsIpAddressOverride 10.20.30.40

For a complete explanation of the set system ems command, refer to System - Ems in the CLI Reference Guide.

Notes
  1. The Service Discovery for EMS Registration is only available in the SWe environment.

  2. The SBC must be rebooted in order for either of these actions to take effect:
    1. To change the value of an EMS FQDN, you must reboot the SBC. (If the metadata for a new SBC initialization included an FQDN for the EMS server, changing the FQDN value later with a CLI command requires a reboot.)
    2. To override an EMS FQDN with static addresses, you must reboot the SBC.
  3. The EMS FQDN supports A/AAAA (Address) queries, SRV (Service) queries and PTR (Pointer) queries.

Configuring SBC Service Discovery

To use Service Discovery to resolve trap target destinations and EMS registration, you must define the Service Registry and Name Server for the SBC:

set system serviceDiscovery serviceRegistry <service registry name and options> nameserver <nameserver index> [name server ipAddress and options, or name server host name]

Example command:

set system serviceDiscovery serviceRegistry dns_registry timeout 1000 nameserver 0 ipAddress 172.24.107.44 port 1053

For a complete explanation of the set system serviceDiscovery command, refer to Service Discovery - CLI in the CLI Reference Guide.

Note

Configuring the Service Discovery allows you to customize the name server for a DNS-based Service Registry.

By default, the SBC uses the name server configured for the management interface. Refer to Address Context - DNS Group for a description of the Mgmt Interface (management interface) parameter.

Configuration Examples

The following examples illustrate how to configure trap target destinations and EMS registration for Service Discovery, and how to configure the SBC with a Service Registry and Name Server.

Service Discovery for Trap Target Destinations

% set oam snmp trapTarget trapX fqdn group1._snmp-trap._udp.test.sd.rbbn.com ipAddress 10.20.30.40 port 789

% commit

% show configuration oam snmp trapTarget
trapTarget trapX {
    fqdn      group1._snmp-trap._udp.test.sd.rbbn.com;
    ipAddress 10.20.30.40;  **This is the IP address of the trap target before Service Discovery resolves the FQDN.**
    port      789;
    state     disabled;
}
trapTarget emaTarget {
    ipAddress 127.0.0.1; **This is a local IP address, not going out of the box.**
    port      8162;
    trapType  v2;
    state     enabled;
}

% show status oam snmp trapTarget  **This shows the IP addresses of the trap target after resolution by Service Discovery.**
trapTarget trapX {
    ipAddressEntry trapX-1 {
        trapTargetIpAddress 192.168.0.12;
        trapTargetPort      1234;
    }
    ipAddressEntry trapX-2 {
        trapTargetIpAddress 192.168.0.11;
        trapTargetPort      1234;
    }
    ipAddressEntry trapX-3 {
        trapTargetIpAddress 192.168.0.13;
        trapTargetPort      1234;
    }
}
trapTarget emaTarget {
    ipAddressEntry emaTarget-0 {
        trapTargetIpAddress 127.0.0.1;
        trapTargetPort      8162;
    }
}
																	 
% show table oam snmp trapTarget  ** Example showing FQDN trapX with three IP addresses resolved for FQDN trapX **
                                                                                       TARGET                                         TRAP
                                                    IP                 TRAP  TARGET    SECURITY                         TRAP TARGET   TARGET
NAME       FQDN                                     ADDRESS     PORT   TYPE  USERNAME  LEVEL     STATE     INDEX        IP ADDRESS    PORT
--------------------------------------------------------------------------------------------------------------------------------------------
trapX      group1._snmp-trap._udp.test.sd.rbbn.com  10.20.30.40  789   v2    admin     authPriv  disabled  trapX-1      192.168.0.13  1234
                                                                                                           trapX-2      192.168.0.11  1234
                                                                                                           trapX-3      192.168.0.12  1234
emaTarget  -                                        127.0.0.1   8162   v2    admin     authPriv  enabled   emaTarget-0  127.0.0.1     8162


% show table oam snmp trapTarget  ** Example showing the display if FQDN trapX does not resolve to any IP addresses **
                                                                                       TARGET                                         TRAP
                                                    IP                 TRAP  TARGET    SECURITY                         TRAP TARGET   TARGET
NAME       FQDN                                     ADDRESS     PORT   TYPE  USERNAME  LEVEL     STATE     INDEX        IP ADDRESS    PORT
--------------------------------------------------------------------------------------------------------------------------------------------
trapX      group1._snmp-trap._udp.test.sd.rbbn.com  10.20.30.40  789   v2    admin     authPriv  disabled  trapX-0      10.20.30.40    789

emaTarget  -                                        127.0.0.1   8162   v2    admin     authPriv  enabled   emaTarget-0  127.0.0.1     8162

In the above example, the default trap target 'emaTarget' provides an IP address and port to create a trap target entry. The ipAddressEntry does not exist in the CDB (Configuration Data Base); it is a mapping to /SNMP-TARGET-MIB/snmpTargetAddrTable/snmpTargetAddrEntry and it is not configurable -- it is only possible to read the current status. The CPX (the name of the application that interprets and executes the CLI command) is responsible to do the mapping by using maapi callback to run user code when a CLI command is run.

The trap target 'trapX' in the above example uses an FQDN and a default IP address and port. When configured, a trap target entry is created with an IP address and port until the FQDN is resolved. At the same time it is created, the CPX application asks the Service Discovery Interface to subscribe for a resolution update for the FQDN. When an update is available, all existing trap target entries for this trap target name are replaced by trap target entries corresponding to the IP addresses and ports resolved by the Service Discovery.

Also in the above example, the second show table command shows the response when the FQDN does not resolve. Notice that in this case index 0 (trapX-0) appears, with the trap target IP address and port taken from the address and port assigned in the original set oam snmp trapTarget trapX command.

Service Discovery for EMS Registration

% show status system ems emsIpAddress
emsIpAddress 11.12.13.14

% set system ems emsIpAddressOverride 11.12.13.10 

% commit

***reboot the SBC

% show status system ems emsIpAddress
emsIpAddress 11.12.13.10

The above example shows an EMS IP address of "1.12.13.14”, sets an IP address override value of “11.12.13.10”, reboots the SBC, and shows a new value of “11.12.13.10”.

SBC Service Discovery

% set system serviceDiscovery serviceRegistry SDR_primary nameserver 1 ipAddress 21.22.23.24 port 22 priority 1 weight 10

% set system serviceDiscovery serviceRegistry SDR_primary transport tcp attempts 10 timeout 100 

% set system serviceDiscovery serviceRegistry SDR_primary resolve recurse true roundRobin true ttl 2 

% commit

% show configuration system serviceDiscovery 

serviceRegistry SDR_primary {
    nameserver 1 {
        ipAddress 21.22.23.24;
        port      22;
        priority  1;
        weight    10;
    }
    transport tcp;
    attempts  10;
    timeout    100;

    resolve {
        recurse    true;
        roundRobin true;
        ttl        2;
    }
} 

The above example sets the name of the registry to SDR_primary, the Name Server index to 1, the IP address to 21.22.23.24, the port to 22, the priority to 1, the weight to 10, the transport type to tcp, the number of retry attempts to 10, the timeout value to 100 ms, recursive resolution to be on, the Name Server order to be round robin, and the maximum time to live to be 2 seconds. Note: The parameters are entered in separate commands because once you enter a subset (such as nameserver or resolve), you cannot issue the other parameters in the same command.

Also in the above example, the show command displays the parameters that are set.

Standard FQDN Naming Conventions

DNS-based Service Discovery (RFC6763), or DNS-SD, specifies how to name and structure DNS resource records to facilitate Service Discovery. Given a type of service that a client is looking for, and a domain in which the client is looking for that service, this structure allows clients to discover a list of named instances of that desired service, using standard DNS queries.

Notes
  1. Ribbon recommends configuring Service Discovery first, before setting the EMS and trap configurations.
  2. If the Service Registry and Name Server are not configured, by default the SBC resolves the trap target and EMS registration FQDNs using the Name Server configured for the management interface. Refer to Address Context - DNS Group for a description of the Management Interface parameter.

DNS-SD specifies the use of a DNS Service (SRV) [RFC2782] record and DNS Text (TXT) [RFC1035] record to describe a particular service instance. The SRV record has a name of the form:

"<Instance>.<Service>.<Domain>"

where:

  • The <Instance> name consists of arbitrary Net-Unicode text (RFC5198). It must not contain ASCII control characters (byte values 0x00-0x1F and 0x7F). Punctuation (especially dots) must not be used; only letters, digits, and hyphens must be used. Due to constraints in the DNS labels size, the maximum length for the instance name is 63 octets. A simple, explicit and short label is best.

  • The <Service> name is limited to 15 characters in length or less (including the mandatory underscore), and must consist of only letters, digits, and hyphens. The service name must begin and end with a letter or digit, must not contain consecutive hyphens, and must contain at least one letter. If a sub-type is specified, the sub-type must also be limited to 15 characters in length or less (including the mandatory underscore), and may contain only letters, digits, and hyphens.

  • The <Domain> name is a conventional Unicast DNS domain name and is limited to 100 octets in length or less. Allowed characters are letters, digits, hyphens ("-") and periods (".") .

The SRV record gives the target host and port where the service instance is reached. A client discovers the list of available instances of a given service type using a query for a DNS Pointer (PTR) [RFC1035] record with a name of the form "<Service>.<Domain>", which returns a set of zero or more names, which are the names of the aforementioned DNS SRV/TXT record pairs.

The following examples illustrate the naming conventions and structure used for Service Discovery of the trap target destination and EMS registration cases.

Trap Target Destination Example

/etc/named/example.com.zone

example.com.  IN SOA nameserver1.example.com.  (

...

; Name servers for the zone 

example.com.        IN  NS nameserver1.example.com.

; server host definitions

Host1.example.com.  IN  AAAA     2019:db8:0:1::1    ;this is SNMP server  IP E1

Host2.example.com.  IN  A     192.168.0.2 ;this is SNMP server IP E2

Host3.example.com.  IN  A     192.168.0.3  ;this is SNMP server IP E3

; mapping service and instances of that service

_snmp-trap._udp.example.com.  IN  PTR GroupA._snmp-trap._udp.example.com.   ; the SBC can point to either trap destination to get its services (e.g. to send SNMP traps)

_snmp-trap._udp.example.com.  IN  PTR GroupB._snmp-trap._udp.example.com.   ; 2nd group

; mapping service and instances of that service (assuming port 9999), and shown format is: instance Class SRV Priority Weight Port Target

GroupA._snmp-trap._udp.example.com.   IN   SRV  0 0 9999 Host1.example.com.    ; this would be the host of one of the initial SNMP server

GroupA._snmp-trap._udp.example.com.   IN   SRV  0 0 9999 Host2.example.com.    ; this would be the host of the other SNMP server

GroupA._snmp-trap._udp.example.com.   IN   TXT   ""

GroupB._snmp-trap._udp.example.com.   IN   SRV  0 0 9999 Host3.example.com.    ; host part on group B

GroupB._snmp-trap._udp.example.com.   IN   TXT   ""

EMS Registration Example

/etc/named/example.com.zone

example.com.  IN SOA nameserver1.example.com.  (

...

; Name servers for the zone 

example.com.        IN  NS nameserver1.example.com.

; server host definitions

Host1.example.com.  IN  AAAA     2019:db8:0:1::1  ;this is EMS IP E1

; mapping service and instances of that service

_ems._tcp.example.com.  IN  PTR dev1._ems._tcp.example.com.

; mapping service and instances of that service, and shown format is: instance Class SRV Priority Weight Port Target

 dev1._ems._tcp.example.com.   IN   SRV  0 0 443 Host1.example.com.    ; this would be the host of initial active EMS

dev1._ems._tcp.example.com.   IN   TXT   ""