:orphan:

.. index:: pair: group; Auxiliary library to define network in YAML format
.. _doxid-group__tapi__net__yaml:

Auxiliary library to define network in YAML format
==================================================

.. toctree::
	:hidden:

Overview
~~~~~~~~

Definition of test API to provide a way to set up test network defined in YAML files. :ref:`More...<details-group__tapi__net__yaml>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// global variables

	static const :ref:`te_enum_map<doxid-structte__enum__map>` :ref:`tapi_net_yaml_af_map<doxid-group__tapi__net__yaml_1gafcb52584614769ea50f989249218d6c4>`[] = {     {.name = "inet",  .value = AF_INET},     {.name = "inet6", .value = AF_INET6},     :ref:`TE_ENUM_MAP_END<doxid-group__te__tools__te__enum_1gada90a2afc0f1558a5ddd9d64f22ff4ad>` };

	// global functions

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_net_yaml_parse<doxid-group__tapi__net__yaml_1gaa14203fab140d622b8bebfb765332151>`(const char* filename, :ref:`tapi_net_ctx<doxid-structtapi__net__ctx>`* net_ctx);

.. _details-group__tapi__net__yaml:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Definition of test API to provide a way to set up test network defined in YAML files.

Global Variables
----------------

.. index:: pair: variable; tapi_net_yaml_af_map
.. _doxid-group__tapi__net__yaml_1gafcb52584614769ea50f989249218d6c4:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	static const :ref:`te_enum_map<doxid-structte__enum__map>` tapi_net_yaml_af_map[] = {     {.name = "inet",  .value = AF_INET},     {.name = "inet6", .value = AF_INET6},     :ref:`TE_ENUM_MAP_END<doxid-group__te__tools__te__enum_1gada90a2afc0f1558a5ddd9d64f22ff4ad>` }

Mapping between an address family and its string representation used in the YAML configuration file.

Global Functions
----------------

.. index:: pair: function; tapi_net_yaml_parse
.. _doxid-group__tapi__net__yaml_1gaa14203fab140d622b8bebfb765332151:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_net_yaml_parse(const char* filename, :ref:`tapi_net_ctx<doxid-structtapi__net__ctx>`* net_ctx)

Parse a YAML network configuration file.

The function reads a YAML document describing test agents, their base interfaces, and logical point-to-point networks built over those interfaces. On success it fills ``net_ctx`` with arrays of agents and networks that can be used to set up network for tests.

=== Data model (YAML schema, informal) ===

Root mapping contains:

* "interfaces": sequence (required)

* "networks": sequence (required)

1) interfaces: list of base NICs per agent. Each item is a mapping:

* agent : string (required) // test agent name

* names : sequence<string> // non-empty list of base ifaces

Parsed into: :ref:`tapi_net_ta <doxid-structtapi__net__ta>` [] with per-agent lists of base interfaces as SLIST stacks (base at head). See tapi_net_ta/tapi_net_iface.

2) networks: list of point-to-point logical networks. Each item is a mapping with fields:

* iface_type : enum { base, vlan, qinq, gre } (required)

* af : enum { inet, inet6 } (required)

* vlan_id : int >= 0 (VLAN only)

* outer_id : int >= 0 (QinQ only, S-tag)

* inner_id : int >= 0 (QinQ only, C-tag)

* endpoints : sequence of exactly 2 mappings (required):
  
  * agent : string (required)
  
  * base_iface : string (required)
  
  * iface : string (optional; defaults to base_iface for 'base')

Behavior:

* iface_type == base: No new logical interfaces are created; existing base interfaces are used as is.

* iface_type in { vlan, qinq, gre }: Logical interfaces are created on top of the specified base interfaces and pushed into the per-base SLIST stack (e.g., GRE sub-interface can be based on VLAN sub-interface with vlan_id, which in turn can be based on one of the interfaces defined in the root 'interfaces' section). The endpoint "iface" field names the resulting logical interface.

Parsed into: :ref:`tapi_net_link <doxid-structtapi__net__link>` []; each net has name "test_net\_<idx>", address family, and two endpoints (agent/iface).

3) nat: list of NAT rules per agent (optional). Each item is a mapping:

* agent : string (required)

* rules : sequence<rule> (required)

rule mapping:

* type : enum { snat, dnat } (required)

* mode : enum { address, masquerade } (required)

* from : { agent: string, iface: string } (required)

* to : { agent: string, iface: string } (conditional)

Semantics:

* For mode = "address": Both ``from`` and ``to`` endpoint objects are required. Static translation occurs between these two interfaces.

* For mode = "masquerade": Supported only for ``type`` = "snat". The ``to`` field should be omitted. The configurator applies standard source NAT masquerading rules.

Parsed into: :ref:`tapi_net_nat_rule <doxid-structtapi__net__nat__rule>` [] associated with each ``:ref:`tapi_net_ta <doxid-structtapi__net__ta>``` in the network context.

=== Variable expansion ===

Scalar values in the YAML (strings and integers written as scalars) are passed through environment expansion.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- filename

		- Path to YAML configuration file.

	*
		- net_ctx

		- Network configuration context.



.. rubric:: Returns:

Status code.