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.
In this section:
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:
- Configure Service Discovery for trap target destinations
- Configure Service Discovery for EMS registration
- 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
- Ribbon recommends configuring Service Discovery first, before setting the EMS and trap configurations.
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
The Service Discovery for EMS Registration is only available in the SWe environment.
- The SBC must be rebooted in order for either of these actions to take effect:
- 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.)
- To override an EMS FQDN with static addresses, you must reboot the SBC.
- 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.
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
- Ribbon recommends configuring Service Discovery first, before setting the EMS and trap configurations.
- 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 ""
Overview
Content Tools