..
..                             Vortex Link
..
..    This software and documentation are Copyright 2010 to 2018 ADLINK
..    Technology Limited, its affiliated companies and licensors. All rights
..    reserved.
..
..    Licensed under the ADLINK Software License Agreement Rev 2.7 2nd October
..    2014 (the "License"); you may not use this file except in compliance with
..    the License.
..    You may obtain a copy of the License at:
..                        docs/LICENSE.html
..
..    See the License for the specific language governing permissions and
..    limitations under the License.
..

#################
Detailed Examples
#################

In this chapter we detail in several use cases the configuration of each Vortex Link service,
but also the configuration of DDS applications.


****************
Device to Device
****************

In this use case we want to enable DDS discovery and communication
between devices running DDS applications over TCP (*e.g.* mobile
applications which are usually behind a symmetric NAT, and so have
no public IP). For this we need to deploy a Vortex Link service in 
a cloud on a host that is publicly accessible. In this example, we 
will consider that the cloud host that will host the service has a 
private IP address (10.2.0.1) but is accessible through a public Ip 
address (70.70.70.1).

We will configure the Vortex Link service to:

+ use the network interface ``eth0`` (as cloud hosts might be multi-homed)
+ use the public IP of its host (``70.70.70.1``)
+ listen for TCP connections on port 8500

.. figure:: ./images/Adv_ex_001.png
   :alt: Device to Device
   :width: 25em
   :height: 12em
   :scale: 100 % 
   :align: center

**Vortex Link service**:

.. code-block:: properties

   link.network.interfaces=eth0
   link.externalNetworkAddresses=70.70.70.1
   link.tcp.port=8500

**App 1 and 2** (using Vortex Café):

.. code-block:: properties

   ddsi.network.udp.enabled=false
   ddsi.discovery.tcp.peers=70.70.70.1:8500
   ddsi.discovery.tcp.port=7400
   ddsi.discovery.externalNetworkAddresses=none

*********************************
Device to Device & Device to Link
*********************************

In this use case we want to enable DDS discovery and communication
between devices with DDS applications over TCP, but also DDS
applications running in the cloud (over UDP multicast or TCP). 

We will configure the Vortex Link service to:

+ use the network interface ``eth0`` (as cloud hosts, might be multi-homed)
+ use the public IP of its host (``70.70.70.1``)
+ listen for TCP connections on port 8500
+ discover UDP multicast applications on domain 0

.. figure:: ./images/Adv_ex_002.png
   :alt: Device to Device & Device to Link
   :width: 25em
   :height: 12em
   :scale: 100 % 
   :align: center

**Vortex Link service**:

.. code-block:: properties

   link.network.interfaces=eth0
   link.externalNetworkAddresses=70.70.70.1
   link.tcp.port=8500
   link.domainid=0

**App 1 and 2** (using Vortex Café):

.. code-block:: properties

   ddsi.network.udp.enabled=false
   ddsi.discovery.tcp.peers=70.70.70.1:8500
   ddsi.discovery.tcp.port=7400
   ddsi.discovery.externalNetworkAddresses=none
   
**App 3** (using Vortex Café):

   If using multicast:
   
     Nothing particular to configure (use domainId 0 by default)
     
   If using tcp:
   
      .. code-block:: properties
      
         ddsi.network.udp.enabled=false
         ddsi.discovery.tcp.peers=10.2.0.1:8500
         ddsi.discovery.tcp.port=7400

********************************************
LAN to LAN (I can deploy on my Firewall/NAT)
********************************************

In this use case we want to interconnect two LANs where DDS applications
are running using UDP multicast. For this we need to deploy a Vortex Link
service in each LAN.

Each Vortex Link service will discover applications in its LAN, but also
get informations about the applications discovered by the remote
Vortex Link service in the other LAN. The Vortex Link services will then be
able to establish a route between applications in distinct LAN.

In this use case we can deploy the services on the NAT host (*i.e.* a
host with two network interfaces: one connected to the LAN with a
private IP, and one connected to the WAN with a public IP).

We will configure the Vortex Link service in each LAN to:

+ use the network interface connected to the LAN to discover UDP user
  applications and route traffic from user applications
+ use the network interface connected to the WAN to route traffic to the
  remote Vortex Link service through TCP
+ establish a TCP connection with the remote Vortex Link service in the other LAN

.. figure:: ./images/Adv_ex_003.png
   :alt: LAN to LAN (I can deploy on my Firewall/NAT)
   :width: 45em
   :height: 15em
   :align: center

**Vortex Link service 1**:

.. code-block:: properties

   link.udp.interface=eth0
   link.tcp.interface=eth1
   link.tcp.peers=80.80.80.80:7400

**Vortex Link service 2**:

.. code-block:: properties

   link.udp.interface=eth0
   link.tcp.interface=eth1
   link.tcp.peers=65.65.65.65:7400

**App 1, 2, 3, 4**:

 *(nothing to configure)*

*******************************************************************
LAN to LAN (I can't deploy on my Firewall/NAT but can configure it)
*******************************************************************

This use case is similar to the previous one (see
`LAN to LAN (I can deploy on my Firewall/NAT)`_) except that here we
cannot deploy the Vortex Link services on the NAT hosts.
Instead, we can configure each NAT to redirect the TCP port (default 7400) 
to a host in each LAN.

The only differences from the configurations of the previous use case
are that the services are now using only one network interface, and that
we need to specify the NAT public IP for each service using the
*externalNetworkAddresses* property.

.. figure:: ./images/Adv_ex_004.png
   :alt: LAN to LAN (I can't deploy on my Firewall/NAT but can configure it)
   :width: 45em
   :height: 15em
   :align: center

**Vortex Link service 1**:

.. code-block:: properties

   link.network.interface=eth0
   link.tcp.peers=80.80.80.80:7400
   link.externalNetworkAddresses=65.65.65.65

**Vortex Link service 2**:

.. code-block:: properties

   link.network.interface=eth0
   link.tcp.peers=65.65.65.65:7400
   link.externalNetworkAddresses=80.80.80.80

**App 1, 2**:

 *(nothing to configure)*

******************************************************************************
Indirect LAN to LAN (I can't deploy on my Firewall/NAT and can't configure it)
******************************************************************************

This use case is similar to the previous ones (see
`LAN to LAN (I can deploy on my Firewall/NAT)`_ and see
`LAN to LAN (I can't deploy on my Firewall/NAT but can configure it)`_),
but here we can not deploy the Vortex Link services on the NAT hosts, and we can not
configure ports redirection on the NAT. The consequence is that services
deployed in each LAN cannot establish a direct connection with services
in the remote LAN.

We therefore need to use a cloud as an intermediate, and to deploy a
Vortex Link service within the cloud. This service will be in charge of 
routing communications between the Vortex Link services.

Note that this deployement is actually a hierarchical deployment, and thus
Vortex Link must be configured with a higher service level than the Vortex Link services
(which by default are configured with level 0). See :ref:`config_link_serviceLevel` configuration.

.. figure:: ./images/Adv_ex_005.png
   :alt: Indirect LAN to LAN (I can't deploy on my Firewall/NAT and can't configure it)
   :width: 45em
   :height: 25em
   :align: center

**Vortex Link service**:

.. code-block:: properties

   link.network.interface=eth0
   link.externalNetworkAddresses=70.70.70.1
   link.serviceLevel=1

**Vortex Link services 1 & 2**:

.. code-block:: properties

   link.network.interface=eth0
   link.tcp.peers=70.70.70.1:7400
   link.externalNetworkAddresses=none

**App 1, 2**:

 *(nothing to configure)*

****************************************
LAN to LAN + Internet devices (no cloud)
****************************************

This use case is similar to the one in
`LAN to LAN (I can deploy on my Firewall/NAT)`_, but we
also want to have external devices using DDS
over TCP to communicate with DDS applications in each LAN.

The TCP applications must be configured to connect to one (or both) of 
the Vortex Link services.

.. figure:: ./images/Adv_ex_006.png
   :alt: LAN to LAN + Internet devices (no cloud)
   :width: 45em
   :height: 15em
   :align: center

**Link 1**:

.. code-block:: properties

   link.udp.interface=eth0
   link.tcp.interface=eth1
   link.tcp.peers=80.80.80.80:7400

**Link 2**:

.. code-block:: properties

   link.udp.interface=eth0
   link.tcp.interface=eth1
   link.tcp.peers=65.65.65.65:7400

**App 1, 2, 3, 4**:

 *(nothing to configure)*

**App 5** (using Vortex Café):

.. code-block:: properties

   ddsi.network.udp.enabled=false
   ddsi.discovery.tcp.peers=65.65.65.65:7400
   ddsi.discovery.tcp.port=7400
   ddsi.discovery.externalNetworkAddresses=none


.. raw:: latex

    \clearpage

*************************************************
LAN to LAN + Internet devices (with public cloud)
*************************************************

This use case is similar to the previous one (see
`LAN to LAN + Internet devices (no cloud)`_), but in addition we want
applications deployed in a public cloud (without UDP multicast) to
communicate with applications in the LAN and applications on
devices using TCP.

To support this, we need to deploy a Vortex Link service in the cloud. 
Note that as the Vortex Link service is deployed in a cloud
with a public IP, the TCP applications on devices can connect to it
directly. Note also that as the Vortex Link service can mediate 
communications between the Vortex Link services in the sub systems, the 
Vortex Link services can be deployed on any host and do not need to be 
publicly accessible.

.. figure:: ./images/Adv_ex_007.png
   :alt: LAN to LAN + Internet devices (with public cloud)
   :width: 45em
   :height: 25em
   :align: center

**Vortex Link service**:

.. code-block:: properties

   link.network.interface=eth0
   link.externalNetworkAddresses=70.70.70.1
   link.serviceLevel=20
   
**Vortex Link services 1 & 2**:

.. code-block:: properties

   link.network.interface=eth0
   link.tcp.peers=70.70.70.1:7400
   link.externalNetworkAddresses=none
   
**App 1 & 2**:

 *(nothing to configure)*

**App 3**:

 *(nothing to configure)*
 
**App 4** (using Vortex Café):

.. code-block:: properties

   ddsi.network.udp.enabled=false
   ddsi.discovery.tcp.peers=70.70.70.1:7400
   ddsi.discovery.tcp.port=7400
   ddsi.discovery.externalNetworkAddresses=none