.. _multi-tenanted-networking:

Multi-Tenanted Networking
#########################

Publish and subscribe networking uses a series of services to collect and distribute address information. The
:ref:`ansar network <ansar-command-reference-network>` command is used to configure these services according to specific networking requirements.
Examples of this configuration have appeared in the series of pub-sub guides;

* :ref:`composite-applications`,
* :ref:`a-networked-laboratory`,
* and :ref:`remote-weather-stations`.

These examples have made use of a *default* set of services, provided as an easy-to-use, general-purpose
networking service. It's also a single, global namespace - all pub-sub networking that joins this
namespace shares it with everyone else. Rather than responding with solutions like a naming convention,
ansar provides a set of *shared* services that exist alongside the default services. Installation
of **ansar-host** and **ansar-lan** actually configures three services each;

* reserved,
* default,
* and shared.

The *reserved* service is a system namespace, intended for future features such as automated software
deployment. The *shared* service provides multiple namespaces. A specific namespace is selected during
an initial exchange of messages, e.g. when **ansar-group** connects to **ansar-host**.

To make use of the shared service, add a pair of arguments to the :ref:`ansar network <ansar-command-reference-network>`
command;

.. code::

	$ ansar network --connect-scope=GROUP --to-scope=HOST --product-name=Acme --product-instance=TESTING

The presence of these arguments causes different connection details to be passed to **ansar-group**. It
switches from the default service to the shared service and joins a *private* namespace with the
identity ``Acme/TESTING``. Full and formal use of the pub-sub networking services will look like;

.. code::

	$ ansar network
	+ WAN Acme/TESTING
	+ LAN Acme/TESTING
	+ HOST Acme/TESTING
	+ GROUP 127.0.0.1:45221

The **ansar-group** service supports namespaces by joining a selected namespace.

Pub-sub networking at the WAN level is always within a named namespace. During creation of an ansar account,
an initial directory is created for the new user. This is given the name ``Ansar Networking/TESTING`` - a composite
of a string title and an enumeration. Ansar directories are the implementation of namespaces. Eleven enumerations are provided;

* DEVELOPMENT
* TESTING
* INTEGRATION
* QA
* STAGING
* PRODUCTION
* DEMONSTRATION
* TRAINING
* SALES
* EVALUATION
* OTHER

.. _standard-and-custom-network-addresses:

Standard And Custom Network Addresses
*************************************

By default ansar network services are available at standard IP addresses and port numbers. These are;

.. list-table:: Standard Network Addresses
    :widths: 50 100 100
    :header-rows: 1

    * - Scope
      - Host
      - Ports
    * - WAN
      - ansar-mx.net
      - 5022
    * - LAN
      - 192.168.1.176
      - 32176, 32177, 32178
    * - HOST
      - 127.0.0.1
      - 32176, 32177, 32178
    * - GROUP
      - 127.0.0.1
      - *ephemeral*

The three port numbers listed against the LAN and HOST services are the ports used by the reserved,
default and shared network services.

Selection of these values acknowledges a few network technicalities but was otherwise fairly arbitrary.
The goal was to achieve a set of configuration commands that did not require entry of IP addresses or port
numbers, and that the resulting configuration would be functional within as many sites as possible.

For those sites that do not match the selected defaults, all network configuration commands must include
additional arguments, e.g.;

.. code::

	$ ansar network --connect-scope=HOST --to-scope=LAN --custom-host=10.0.1.24 --custom-port=40201

These can be combined with the ``--product-name`` and ``--product-instance`` arguments. Use of the
``--custom-port`` argument must be matched to a corresponding value at installation time, for the
relevant ansar service, e.g. **ansar-lan**;

.. code::

	$ make ansar-lan-service CUSTOM_PORT=40201

The **ansar-lan** service is installed on the current host and the individual services (i.e. reserved,
default and shared) are listening on 40201, 40202 and 40203 respectively.