TRA Virtual Server Reference

TRA Virtual Server General Elements

When you apply TRA configuration using a configuration source, you create the required virtual servers in <virtual-server> elements and their corresponding ports, protocols, and pool entries.

Each VS you configure has these attributes:

• name — A descriptive name for the VS.
• vip — The name of the TRA VIP (the VIP name, for example, vip2). If no VIP is specified for a VS for a stand-alone TRA, a VIP with the predefined name any is used by default, which allows connections to all interfaces.
  Note: The any, any4, and any6 VIPs are applicable only to deployments where TRA is running in stand-alone mode, not as part of a high availability (HA) pair.

  For more information about the VIP any, see the discussion about VIPs that accept connections from all available interfaces.

• port — The port number assigned to the VS in the tra_config_network_topology.xml file. See the discussion about site configuration for the default port numbers.
• protocol — The network connection protocol accepted by the VS. Can be one of:
  • evs
  • tcp
  • udp
  • diameter
  • snmp
  • mdc
  • route-cache
  • http2_mdc
  • ssl (Equivalent to the tcp protocol with secured set to true, even if secured is explicitly set to false.)
  The default is tcp for all virtual servers except the SNMP virtual server. The protocol for SNMP traffic is udp. VSs that use the udp protocol must also use the single-node pool balance-method. The tcp, udp, diameter, and snmp options are for their respective industry-standard protocols. mdc and evs are used for MATRIXX data container and MATRIXX Event Streaming Framework communication, respectively. The route-cache protocol is used for synchronizing route caches in sub-domains using the TRA network for transferring route-cache protocol messages. The http2_mdc protocol uses HTTP/2 as a wrapper protocol for incoming MATRIXX Data Container (MDC) messages for interoperability with other components that support HTTP/2.

  The evs protocol is unique in that it only routes sub-domain traffic for the optional Event Streaming Framework feature. It does not do any load balancing, and the protocol defines the destination peer.

• pool — The pool name assigned to the engine or engine chain (DR engine pair) being monitored (the pool of engine nodes providing service). This value must match the name defined for the <pool name> element where you defined your pools.
• secured — Boolean. Applicable to the diameter protocol. Specifies (if set to true) that the VS uses Transport Layer Security (TLS), known before as Secure Sockets Layer (SSL), when communicating with an upstream Diameter client. The default value is false. The supported TLS protocol versions are TLSv1.3 and TLSv1.2.

  You can also use the secured option with the TCP and MDC protocols by setting the security-allow-any-tcp-traffic parameter in the <virtual-servers-options> section for the VS. For more information about the available security configuration options, see the discussion about TRA security in MATRIXX Security.

  Note: If one or more VSs are defined as secured, you must disable TRA memory locking by setting the lock-process-memory parameter to off in the tra_config.xml configuration file. For more information, see the discussion about configuring TRA tra_config.xml parameters.
• (Optional) downstream-port port_number — A port number to use instead of the VS default port specified in the tra_config.xml file. This allows you to separate the upstream and downstream service ports.
• (Optional) preferred-fqdn FQDN_name — Allows you to manually control the CER/CEA host name selection for Diameter traffic. You can override the default FQDN returned by the operating system for a VIP associated with a VS. Enter a valid FQDN name to select that specific FQDN instead of using the default selection.
  Note: If you use /etc/hosts for name management, the aliasing feature is not supported.
• (Optional) stub-flag — Boolean. Used with Google Cloud Platform and TCP traffic only. Specifies that the VS accepts and closes incoming TCP connections. stub-flag VSs are used by Google Load Balancers (GLBs) to monitor TRA health by serving as a connect pinging point. For more information, see the discussion about configuring Cloud GLBs for MATRIXX in Implementing MATRIXX in a Cloud.
• (Optional) vsopt name=config_options_name — Specifies a set of protcol-specific configuration options, identified by a unique name. For details about the options, see TRA Virtual Server Protocol Elements.

Optionally for TRA-RT configurations, a Diameter VS can define multiple Diameter AVP subscriber sub-type rules for sub-domain routing using the <diameter-avp-subscriber-subtype-route-pattern-rules> element and <rule> sub-element. The <rule> sub-element has the following parameters:

• sub-type — Inbound Diameter subscription ID type. Valid values are 2 (SIP), 3 (NAI), and 4 (private). The values 0 and 1 are reserved for MSISDN and IMSI, respectively.
• key-pattern — A regular expression to find the inbound subscription ID and remember the match as a capture group. The pattern to capture must be inside parentheses ().
• capturing-group — A reference to the capture group defined in the key-pattern.
  Note: If you do not specify an appropriate capture group, a configuration error is reported. For information about capture groups and how to use them, see the regex documentation.
• route-cache-key-type — The cache type from which the translated key can be looked up.

<vs name="Ro" vsopt="RoOpt" vip="vipExtern" port="13868" protocol="diameter" pool="allPool" downstream-port="3868" preferred-fqdn="3gppnetwork.org" fqdn-validate="false" >
    <diameter-avp-subscriber-subtype-route-pattern-rules>
      <rule  capturing-group="1" sub-type="4" key-pattern="(.+)" route-cache-key-type="6" />
    </diameter-avp-subscriber-subtype-route-pattern-rules>
</vs>

sip:[\+]([0-9]+).*

sip:+((0|1|2|3|4|5|6|7|8|9)+)

The tra_create_config.info VS settings are referenced in the VIPs, IP addresses, ports, and pools that you configure in the tra_config_network_topology.xml file. For more information about VSs and TRA configuration, see the discussions about VS configurations, site configuration, and TRA configuration examples.

TRA Virtual Server Protocol Elements

The syntax is:

<virtual-servers-options>
      <vsopt
		name=config_options_name
             parameter=parameter_value
	/>
</virtual-servers-options>

The parameters are:

• name — Specifies the unique name for a set of protocol configuration options to apply to the VS.
• diam-cea-host-ip-addr — Overrides the Diameter CEA host IP AVP with the specified IP address.
• diam-origin-realm — Overrides the content of the Diameter Origin-Realm AVP with the specified string.
• diam-route-remove-imsi-leading-str — For IMSIs that begin with these characters, specifies the leading characters to strip from the IMSI before doing a Route Cache lookup. Otherwise, the IMSI is unchanged.
• diam-route-remove-msisdn-leading-str — For MSISDNs that begin with these characters, specifies the leading characters to strip from the MSISDN before doing a Route Cache lookup. Otherwise, the MSISDN is unchanged.
• diam-use-custom-aar-route — When set to false, specifies whether to use the default behavior for routing AARs based on a framed IP address, framed IPv6 address, or session ID in PDU order. When set to true, the lookup behavior is ordered as follows: subscription ID, session ID, framed IP address, framed IP v6 address. This ensures that subscription ID is looked up first. If the subscription ID is not present, the session ID is looked up. If the session ID is not present, the framed IP address is looked up, and lastly the framed IP v6 address.
• pool-usage-throttle-profile-name — Applies the named pool usage throttle profile to a given diameter or mdc protocol VS. For more information, see the discussion about health-based monitoring and throttling.
• upstream-retention-in-millis — Specifies, in milliseconds, the amount of time to pause before upstream Diameter and MDC connections are dropped when the TRA is switching engines during failover. When a VS is configured with this timer and all downstream nodes are disconnected, the timer is started, and the upstream channel is maintained. If the timer expires before a connection is made to a downstream engine, the upstream connections are terminated, and Diameter and MDC clients must re-establish connections to the newly-active engine when one is available.
• http2-response-timeout-in-millis — Specifies, in milliseconds, the amount of time before an HTTP/2 client receives a 500 error response if no response is received from the downstream connection.
• tcp-dn-dns-resolution-refresh — Applies to TRA nodes that resolve IP addresses from DNS lookup tables using the domain-name option (instead of address). The default setting is 1, which resolves DNS lookups for a given VS again each time a connection is attempted. Set this to 0 resolve the DNS lookup only once and use the result for each subsequent reconnection. This is useful for implementing MATRIXX in a cloud environment with pods that use a fixed cluster-wide DNS name.
• route-to-default-node-skip-rc-lookup — When set to true, a default route must be specified for domain ID-based routing. Inbound traffic is not looked up in the route cache. Instead, the traffic is sent to the default route node. If the default route node is down, standard route cache lookup behavior is employed. The default value is false.
• security-own-certificate-path — The path to the directory containing the security certificate, including the private key and (potentially) the PEM file, (with DH parameters if Diffie-Hellman is used), for the VS. The default value is /opt/tra/custom/tra_certificate.
• security-require-client-certificate — When set to true, a valid client certificate is required from the client over a TLS connection. Validity of the client certificate is determined by the server according to a set of trusted CAs found in the server directory specified in security-trusted-certificates-path.
• security-trusted-certificates-path — The path to the directory containing the root certificate authorities (CAs) for the VS. Defaults to /opt/tra/custom/trusted_certificates/.
• security-disallowed-ssl-versions — Comma-separated list of TLS versions that the VS does not accept for TLS connections.
• security-raw-cipher-list — The TLS ciphers that the VS uses for TLS connections, for example: CAMELLIA128-SHA. Defaults to an empty string.
• security-force-quiet-shutdown — By default (false) the standard TLS shutdown behavior is used, where the parties send out close notify alert messages for a clean shutdown when a TLS connection finishes. When set to true, the TLS connection is considered to be shutdown on connection closure, and a close notify alert message is not sent to the peer.
• security-allow-any-tcp-traffic — By default (false) only TLS connections using the Diameter protocol are supported. When set to true, upstream MDC and TCP protocols can also be secured using the TLS security level.
• security-check-cert-only-for-reload — When set to true, only the certificate file is checked for modification. If it has been modified, SSL/TLS related files (certificate, private key, and PEM file) are reloaded. When set to false, all files are checked for modifications. If any are modified, they are all reloaded. The default value is false.
• security-minimum-interval-for-stat-in-millis — The minimum time interval, in milliseconds, that must pass before checking if SSL/TLS related files (certificate, private key, and PEM) have changed. If set to 0, files are checked before each connection. The default value is 250.
• security-reject-self-signed-certificate — When set to 0, detection of a self-signed certificate does not stop processing in this VS. The default value is 1. for more information, see the discussion about self-signed certificate detection and handling in MATRIXX Security.

<virtual-servers-options>
    <vsopt name="TrimVsOpt" diam-route-remove-misisdn-leading-str="1111" diam-route-remove-imsi-leading-str="2222"/>
</virtual-servers-options>

<virtual-servers>
    <vs name="vsDiamSubDomains" vip="vip-ext" port="3868" vsopt="TrimVsOpt" protocol="diameter" pool="diamSubDomains" preferred-fqdn="ThePreferred.abc" fqdn-validate="false">
</virtual-servers>

<pools>
      <pool name="tcpPool" monitor="tcp-connect" balance-method="single-node" monitor-port="25999">
            <node name="example-tcp-1" id="1" domain-name4="example.com"/>
      </pool>
</pools>

<virtual-servers-options>
      <vsopt name="options"
             tcp_dn_dns_resultion-refresh="0"
      />
</virtual-servers-options>

<virtual-servers>
      <vs name="vsGenTcp" vsopt="options" vip="vip-ext" port="4444" protocol="tcp" pool="tcpPool"/>
</virtual-servers>