From e6ed86acd651cffd1b7a7618a9bbd755dc7128e3 Mon Sep 17 00:00:00 2001 From: tgoff0 Date: Fri, 22 May 2015 00:56:58 +0000 Subject: [PATCH] doc:4.8rc1 control net documentation --- doc/ctrlnet.rst | 193 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 doc/ctrlnet.rst diff --git a/doc/ctrlnet.rst b/doc/ctrlnet.rst new file mode 100644 index 00000000..356f4b87 --- /dev/null +++ b/doc/ctrlnet.rst @@ -0,0 +1,193 @@ +.. This file is part of the CORE Manual + (c)2015 the Boeing Company + +.. _Control_Network: + +*************** +Control Network +*************** +.. index:: controlnet + +.. index:: control network + +.. index:: X11 applications + +.. index:: node access to the host + +.. index:: host access to a node + +The CORE control network allows the virtual nodes to communicate with their host environment. +There are two types: the primary control network and auxiliary control networks. The primary +control network is used mainly for communicating with the virtual nodes from host machines +and for master-slave communications in a multi-server distributed environment. Auxiliary control networks +have been introduced to for routing namespace hosted emulation software traffic +to the test network. + +.. _Activating_the_Primary_Control_Network: + +Activating the Primary Control Network +====================================== + +Under the :ref:`Session_Menu`, the *Options...* dialog has an option to set +a *control network prefix*. + +This can be set to a network prefix such as +``172.16.0.0/24``. A bridge will be created on the host machine having the last +address in the prefix range (e.g. ``172.16.0.254``), and each node will have +an extra ``ctrl0`` control interface configured with an address corresponding +to its node number (e.g. ``172.16.0.3`` for ``n3``.) + +A default for the primary control network may also +be specified by setting the ``controlnet`` line in the +:file:`/etc/core/core.conf` configuration file which new +sessions will use by default. To simultaneously run multiple sessions with control networks, the session +option should be used instead of the :file:`core.conf` default. + +.. NOTE:: + If you have a large scenario with more than 253 nodes, use a control + network prefix that allows more than the suggested ``/24``, such as ``/23`` + or greater. + + + +.. IMPORTANT:: + Running a session with a control network can fail if a previous session has set up a control network and the its bridge is still up. + Close the previous session first or wait for it to complete. If unable to, the ``core-daemon`` may need to be restarted and the lingering + bridge(s) removed manually: + +:: + + # Restart the CORE Daemon + sudo /etc/init.d core-daemon restart + + # Remove lingering control network bridges + ctrlbridges=`brctl show | grep b.ctrl | awk '{print $1}'` + for cb in $ctrlbridges; do + sudo ifconfig $cb down + sudo brctl delbr $cb + done + +.. TIP:: + If adjustments to the primary control network configuration made in :file:`/etc/core/core.conf` do not seem + to take affect, check if there is anything set in the :ref:`Session_Menu`, the *Options...* dialog. They may + need to be cleared. These per session settings override the defaults in :file:`/etc/core/core.conf`. + + + +.. _Distributed_Control_Network: + +Control Network in Distributed Sessions +======================================= + +.. index:: distributed control network + +.. index:: control network distributed + +When the primary control network is activated for a distributed session, +a control network bridge will be created on each of the slave servers, with GRE tunnels back +to the master server's bridge. The slave control bridges are not assigned an +address. From the host, any of the nodes (local or remote) can be accessed, +just like the single server case. + +In some situations, remote emulated nodes need to communicate with the +host on which they are running and not the master server. +Multiple control network prefixes can be specified in the either the session option +or :file:`/etc/core/core.conf`, separated by spaces and beginning with the master server. +Each entry has the form "``server:prefix``". For example, if the servers *core1*,*core2*, and *core3* +are assigned with nodes in the scenario and using :file:`/etc/core/core.conf` instead of +the session option: + +:: + + controlnet=core1:172.16.1.0/24 core2:172.16.2.0/24 core3:172.16.1.0/24 + +then, the control network bridges will be assigned as follows: +*core1* = ``172.16.1.254`` (assuming it is the master server), +*core2* = ``172.16.2.254``, and *core3* = ``172.16.3.254``. + +Tunnels back to the master server will still be built, but it is up to the +user to add appropriate routes if networking between control network +prefixes is desired. The control network script may help with this. + + + +Control Network Script +^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: control network scripts + +.. index:: controlnet_updown_script + +A control network script may be specified using the ``controlnet_updown_script`` +option in the :file:`/etc/core/core.conf` file. This script will be run after +the bridge has been built (and address assigned) with the first argument being +the name of the bridge, and the second argument being the keyword "``startup``". +The script will again be invoked prior to bridge removal with the second +argument being the keyword "``shutdown``". + +Auxiliary Control Networks +========================== + +.. index:: auxiliary control networks + +.. index:: auxiliary_controlnet + +Starting with EMANE 0.9.2, CORE will run EMANE instances within namespaces. +Since it is advisable to separate the OTA traffic from other traffic +(See :ref:`Distributed_EMANE`), we will need more than single channel +leading out from the namespace. Up to three auxiliary control networks may be defined. +Multiple control networks are set up in :file:`/etc/core/core.conf` file. +Lines ``controlnet1``, ``controlnet2`` and ``controlnet3`` define the auxiliary +networks. The format of value to assign the controlnets are the same as in +:ref:`Distributed_Control_Network`. For example, having the following +lines in :file:`/etc/core/core.conf`: + +:: + + controlnet = core1:172.17.1.0/24 core2:172.17.2.0/24 core3:172.17.3.0/24 + controlnet1 = core1:172.18.1.0/24 core2:172.18.2.0/24 core3:172.18.3.0/24 + controlnet2 = core1:172.19.1.0/24 core2:172.19.2.0/24 core3:172.19.3.0/24 + +will activate the primary and two auxiliary control networks and +add interfaces ``ctrl0``, ``ctrl1``, ``ctrl2`` to each node. One use case would +be to assign ``ctrl1`` to the OTA manager device and ``ctrl2`` to the Event Service device +in the EMANE Options dialog box and leave ``ctrl0`` for CORE control traffic. + +.. NOTE:: + ``controlnet0`` may be used in place of ``controlnet`` to configure the primary control network. + +Unlike the primary control network, the auxiliary control networks will not employ +tunneling since their primary purpose is for efficiently transporting multicast EMANE OTA and +event traffic. Note that there is no per-session configuration for auxiliary control networks. + +To extend the auxiliary control networks across a distributed test environment, +host network interfaces need to be added to them. The following lines in +:file:`/etc/core/core.conf` will add host devices ``eth1``, ``eth2`` and +``eth3`` to ``controlnet1``, ``controlnet2``, ``controlnet3``: + +:: + + controlnetif1 = eth1 + controlnetif2 = eth2 + controlnetif3 = eth3 + +.. NOTE:: + There is no need to assign an interface to the primary control network + because tunnels are formed between the master and the slaves using IP + addresses that are provided in ``servers.conf``. (See :ref:`Distributed_Emulation`.) + +Shown below is a representative diagram of the configuration above. + + +.. _example_control_network: + +.. figure:: figures/controlnetwork.* + :alt: Control Network Diagram + :align: center + :scale: 75% + + + Example Control Network + + +