4. The Vortex Link service¶

4.1. Vortex Link capabilities¶

Vortex Link is able to:

discover DDS applications over UDP multicast, UDP unicast and TCP
route the DDS traffic between DDS applications it discovered and that can’t communicate directly with each other
route the DDS traffic between a DDS application and another Vortex Link service, that will itself route the traffic to another DDS application.
act as an intermediate routing point between 2 Vortex Link services

4.2. Running a Vortex Link service¶

The Vortex Link service is a single executable jar:

link-service.jar

You can simply run it like this:

java -jar link-service.jar

4.3. Configuring the Vortex Link service¶

The Vortex Link service is configured through java properties. You may define those java properties on the command line with the help of -D flags. You may also use a java properties file somewhere in the classpath.

By default the Vortex Link service will look for a file named vortex_link.properties, but you can point to any file like this:

-Dvortex_link.properties=myfile

Note that the value of this configuration property can be any file location as specified in Files locations.

The most usual configuration properties that may be configured for a Vortex Link service (depending on the use case) are the following:

link.domainid : Specifies the DDS domain on which the Vortex Link service should discover UDP multicast user applications.
link.tcp.port : Specifies the TCP port on which the Vortex Link service should listen for incomming connections from user applications and other services.
link.tcp.peers : Specifies the list of Vortex Link services that this service must try to connect to. Note that with discovery propagation each service does not need to be configured with all remote services as peers. Only some bootstrap peers are sufficient.
link.serviceLevel : In hierarchical deployments this property specifies the level of the configured service in the services hierarchy. This property is also necessary when using Vortex Link in Indirect LAN to LAN deployments.
link.externalNetworkAddresses : When the Vortex Link service is deployed behind a NAT, this property should be set with the public IP of the NAT, or to ‘none’ in case of symetric NAT (i.e. the host can’t be contacted from outside).

4.4. Vortex Link service configuration properties¶

4.4.1. link.domainid¶

Valid values:

0 - 230

Default value:

0

Purpose:

This configuration property indicates in which DDS domain the Vortex Link service should discover user applications. This property has an impact only when discovering user applications using UDP-multicast transport.

When discovering UDP-multicast based user applications, only applications participating in the configured DDS domain will be discovered.
When discovering TCP-based user applications, any application that connects to the Vortex Link service will be discovered whichever DDS domain they are participating in.

UDP multicast can also be used for communications between Vortex Link services when possible. In such situations, the several services that are supposed to communicate with each other through UDP multicast must be configured with the same domainid.

4.4.2. link.tcp.port¶

Valid values:

0 - 65535

Default value:

7400

Purpose:

This property indicates which TCP port should be opened to listen for connections from user applications and from other services.

This port number should be used in user applications configuration so that they contact this Vortex Link service.

4.4.3. link.tcp.peers¶

Valid values:

list of locators

Default value:

not defined

Purpose:

This configuration property indicates the locator, or list of locators to which this service should try to connect to in order to communicate with the other services.

If discovery propagation is disabled, each service need to be configured with the locators of all the other services of the system.

If discovery propagation is enabled (default) then each service may be configured with only one or a part of the other services in the system. It is recommended that more than one locator is defined here for fault tolerance purposes.

See Locators & locator list, for more details about locators.

4.4.4. link.externalNetworkAddresses¶

Valid values:

a list of locators (optionally with ports) or ‘local’ or ‘none’

Default value:

local

Purpose:

This configuration property specifies which locator(s) ( address:port ) the Vortex Link service will advertise to applications and to other Vortex Link services in its discovery protocol exchanges. The port is optional (if not specified, the actual opened port will be advertised).

When the value local is configured, then the Vortex Link service will use the local address of the network interface it is bound to.

So if the Vortex Link service is deployed on a host that is reachable from any host of the system then local should be used.

If the Vortex Link service is deployed on a host behind a NAT with port redirection (the local ip address is different from the public ip address), then the public address should be configured here.

See Locators & locator list, for more details about locators.

4.4.5. link.tcp.externalNetworkAddresses¶

Valid values:

a list of locators (optionally with ports) or ‘local’ or ‘none’

Default value:

local

Purpose:

This configuration property specifies which TCP locator(s) ( address:port ) the Vortex Link service will advertise to applications and to other Vortex Link services through TCP in its discovery protocol exchanges. The port is optional (if not specified, the actual opened port will be advertised).

When the value local is configured, then the Vortex Link service will use the local address of the network interface it is bound to.

So if the Vortex Link service is deployed on a host that is reachable from any host of the system then local should be used.

If the Vortex Link service is deployed on a host behind a NAT with port redirection (the local ip address is different from the public ip address), then the public address should be configured here.

See Locators & locator list, for more details about locators.

4.4.6. link.udp.externalNetworkAddresses¶

Valid values:

a list of locators (optionally with ports) or ‘local’ or ‘none’

Default value:

local

Purpose:

This configuration property specifies which UDP locator(s) ( address:port ) the Vortex Link service will advertise to applications and to other Vortex Link services through UDP in its discovery protocol exchanges. The port is optional (if not specified, the actual opened port will be advertised).

When the value local is configured, then the Vortex Link service will use the local address of the network interface it is bound to.

So if the Vortex Link service is deployed on a host that is reachable from any host of the system then local should be used.

If the Vortex Link service is deployed on a host behind a NAT with port redirection (the local ip address is different from the public ip address), then the public address should be configured here.

See Locators & locator list, for more details about locators.

4.4.7. link.network.interface¶

Valid values:

any string

Default value:

auto

Purpose:

This configuration property indicates which network interface should be used to listen for end user applications and other services and to communicate with them for both UDP and TCP transports.

If link.tcp.interface is set, it will override this property for the TCP transport.

If link.udp.interface is set, it will override this property for the UDP transport.

When the default value auto is used, the Vortex Link service will choose the most suitable interface among the available ones. To determine the most suitable network interface, the Vortex Link service ranks the eligible interfaces by quality, and then selects the interface with the highest quality. If multiple interfaces are of the highest quality, it will select the first enumerated one. Only interfaces that are up and have an IPv4 address family are eligible.

Quality is then determined as follows:

interfaces with a non-link-local address are preferred over those with a link-local one;
multicast-capable is preferred, or if none is available
non-multicast capable but neither point-to-point, or if none is available
point-to-point, or if none is available
loopback

4.4.8. link.tcp.interface¶

Valid values:

any string

Default value:

auto

Purpose:

This configuration property indicates which network interface should be used to listen for end user applications and other services and to communicate with them on TCP transport.

When set, this property will override the value of property link.network.interface for TCP transport.

When the default value auto is used, the behavior of this property is equivalent to the behavior of link.network.interface property.

4.4.9. link.udp.interface¶

Valid values:

any string

Default value:

auto

Purpose:

This configuration property indicates which network interface should be used to listen for end user applications and other services and to communicate with them on UDP transport.

When set, this property will override the value of property link.network.interface for UDP transport.

When the default value auto is used, the behavior of this property is equivalent to the behavior of link.network.interface property.

4.4.10. link.serviceLevel¶

Valid values:

0 - 2147483647

Default value:

0

Purpose:

In hierarchical deployments this property specifies the level of the configured service in the services hierarchy. Each discovered service with a higher level will be considered as a ‘parent’ service and each discovered service with a lower level will be considered as a ‘child’ service.

This property is also necessary when using Vortex Link in Indirect LAN to LAN deployments (that actually are hierarchical deployments with only 2 levels). In such deployments, the Vortex Link service is deployed outside of any LAN (typically in a cloud) and thus on the top of all Vortex Link services in LANs. Therefore it must be configured with a higher level value than the Link services.

A ‘parent’ service will route data between it’s ‘child’ services if needed. Note that Vortex Link has the capacity to route between services and can also be deployed at the bottom of hierarchical systems with the lower level values.

4.4.11. link.cluster.id¶

Valid values:

any string , "auto"

Default value:

""

Purpose:

For fault tolerance and load balancing purposes, it is possible to deploy several replicas of a service and to group them in a cluster. Each cluster must be identified with a cluster id and all replicas in the cluster must be configured with the same cluster id (see Clusters & Cluster ID).

When set to "auto", Vortex Link will configure the clusters automatically by setting the same cluster id to all services that are deployed in a same IP subnetwork (see Automatic cluster id).

4.4.12. link.loadBalancing.pluginClass¶

Valid values:

any string

Default value:

vortex.lb.plugins.PerParticipantHashPlugin

Purpose:

This property defines which plugin implementation should be used to balance data flows on the several replicas of the cluster. Two implementations are available :

vortex.lb.plugins.PerParticipantHashPlugin
vortex.lb.plugins.PerWriterHashPlugin

See Load balancing plugins for more details on the plugins and their behavior.

4.4.13. link.directConnection¶

Valid values:

true , false

Default value:

false

Purpose:

As discussed in Routing chapter, routing may not be necessary in all cases but only when concerned end-user applications cannot directly communicate with each other. But the current version of the Vorex Link service is not able to detect if end-user applications can directly communicate or not (except when both applications are deployed on the same LAN and use UDP multicast). So it has two deployment modes:

If the property is set to true (direct connection mode), all end-user applications will always communicate directly with each other.
If the property is set to false (routing mode), all end-user applications will always communicate with each other through a Vortex Link service.

Direct Connection and Routing Modes

4.4.14. link.participantsAdvertisment¶

Valid values:

never , always, otherVendors

Default value:

otherVendors

Purpose:

When active and when the service advertises a Participant of the existence of a matching DataReader or DataWriter (sending a SEDP message), it will also advertise this Participant of the existence of the parent Participant of the matching DataReader or DataWriter, sending a SPDP message before the SEDP message. This SPDP message will contain the newly discovered Participant’s GUID, but the service’s locators and an infinite duration lease (to avoid the sending of periodical SPDP to all Participants, that will affect scalability).

Note that the discovery of DataReaders and DataWriters is usually sufficient for the Vortex DDS implementations, without the discovery of their parent Participant. But some other implementations require to discover the parent Participant before to consider the discovery of DataReaders and DataWriters.

Valid values are :

never: the service will never advertise the other Participants when discovering a new Participant

always: the service will always advertise the other Participants when discovering a new Participant

otherVendors: the service will advertise only the non-Vortex Participants when discovering a new Participant

An invalid value will be equivalent to never.

4.4.15. link.servicesDiscoveryPropagation¶

Valid values:: true , false
Default value:: true
Purpose:: The discovery propagation facilitates the discovery of other services when using TCP transport between services. When activated, each time the service discovers a new remote service, it propagates the information about this new service to all the other services it already knows. So it is not necessary to configure each service with the locators of all the other services, which makes the system more flexible.

4.4.16. link.blockBuiltinPartition¶

Valid values:: true , false
Default value:: false
Purpose:: This property enables the filtering out (‘not routing’) of all entities using the _BUILT-IN PARTITION_. The _BUILT-IN PARTITION_ is a partition use by Vortex OpenSplice for it’s buit-in entities. When blocking this partition, you will loose some functionalities in Vortex OpenSplice. But those buit-in entities may cause problems in large scale systems. That’s why it may be necessary to block this _BUILT-IN PARTITION_ in some cases.

4.4.17. link.blockDurabilityPartition¶

Valid values:: true , false
Default value:: false
Purpose:: This property enables the filtering out (‘not routing’) of all entities using the durabilityPartition. The durabilityPartition is a partition use by all Vortex products to provide the durability functionality. When blocking this partition, durability (TRANSIENT, PERSISTENT) will not work any more. But it may be necessary to block this durabilityPartition in large scale systems.

4.4.18. link.blacklist.file¶

Valid values:

any string

Default value:

not defined

Purpose:

Identifies a black list file location. This file contains a list of partition.topic items which will not be routed. Together with the white list file it is used for selective routing filtering. See Selective Routing.

The value of this configuration property can be any file location as specified in Files locations.

4.4.19. link.whitelist.file¶

Valid values:

any string

Default value:

not defined

Purpose:

Identifies a white list file location. This file contains a list of partition.topic items which will be routed. Together with black list file it is used for selective routing filtering. See Selective Routing.

The value of this configuration property can be any file location as specified in Files locations.

4.4.20. link.ssl¶

Valid values:: true , false
Default value:: false
Purpose:: When set to true all the TCP communications will be secured via a SSL (or TLS) protocol. See the other “ssl” configuration properties below to configure the SSL protocol.

4.4.21. link.ssl.algorithm¶

Valid values:: any string
Default value:: TLS
Purpose:: Specifies SSL protocol to use. This must be a standard SSL protocol name. See the SSLContext section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard protocol names.

4.4.22. link.ssl.keystore.file¶

Valid values:

any string

Default value:

not defined

Purpose:

Indicates the keystore file providing credential (private/public keys and certificates) to be used for encryption and authentication. See the Java Secure Socket Extension Reference Guide for more information.

The value of this configuration property can be any file location as specified in Files locations.

4.4.23. link.ssl.keystore.format¶

Valid values:

any string

Default value:

JKS

Purpose:

Indicates the type of the keystore file.

See the KeyStore section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard keystore types.

4.4.24. link.ssl.keystore.password¶

Valid values:: any string
Default value:: not defined
Purpose:: Indicates the password of the keystore file.

4.4.25. link.ssl.keymanager.algorithm¶

Valid values:

any string

Default value:

PKIX

Purpose:

Specifies the name of the requested SSL Key Manager algorithm. This must be a standard algorithm name.

See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.

4.4.26. link.ssl.truststore.file¶

Valid values:

any string

Default value:

not defined

Purpose:

Indicates the truststore file providing trusted certificates which are used to verify the identity of remote entities. See the Java Secure Socket Extension Reference Guide for more information. Note that if this property is not defined and a keystore file is defined, the keystore will be used as truststore.

The value of this configuration property can be any file location as specified in Files locations.

4.4.27. link.ssl.truststore.format¶

Valid values:

any string

Default value:

JKS

Purpose:

Indicates the type of the truststore file.

See the KeyStore section in the Java Cryptography Architecture Standard Algorithm Name Documentation for information about standard keystore types.

4.4.28. link.ssl.truststore.password¶

Valid values:: any string
Default value:: not defined
Purpose:: Indicates the password of the truststore file.

4.4.29. link.ssl.trustmanager.algorithm¶

Valid values:

any string

Default value:

PKIX

Purpose:

Specifies the name of the requested SSL Trust Manager algorithm. This must be a standard algorithm name.

See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.

4.4.30. link.ssl.crl.file¶

Valid values:

any string

Default value:

not defined

Purpose:

Indicates the CRL (Certificate Revocation List) file providing the list of revoked certificates. This file can be PEM-encoded or DER-encoded.

The value of this configuration property can be any file location as specified in Files locations.

4.5. Files locations¶

Some configuration properties define a file location (e.g. link.blacklist.file). Vortex Link accepts the file location to be specifeid as a path (absolute or relative), a Java resource or an URL. It will try to open the file treating the location parameter in the following order:

as a path to a file on local file system:

as an absolute path

as a relative path from “user.dir” system property (i.e. working directory)

as a relative path from “user.home” system property (i.e. home directory)

as a Java resource:

loaded by the ClassLoader which loaded Link

loaded by the SystemClassLoader (see java.lang.ClassLoader.getSystemClassLoader())

as an java.net.URL accepting the following protocols:

http, https, ftp, file and jar

any other protocol if the java.net.URLStreamHandlerFactory was previously set via the java.net.URL.setURLStreamHandlerFactory(java.net.URLStreamHandlerFactory) operation.

4.6. Vortex Link service advanced configuration¶

The Vortex Link service is implemented on top of the Vortex Café ddsi stack. For performance or interoperability reasons, it may be necessary to fine-tune the ddsi stack. So, if needed, any Vortex Café ddsi configuration property (properties that start with ddsi) can be set to the Vortex Link service. For more details about Vortex Café ddsi configuration properties, please refer to the Vortex Café documentation.

Note that some of the Vortex Link configuration properties directly impact the ddsi configuration. For example, the Vortex Link link.tcp.port property impacts the Vortex Café ddsi.discovery.tcp.port property. For such configuration properties, if both Vortex Link and Vortex Café properties are set, the Vortex Café property will have precedence over the Vortex Link property and will apply.