.. index:: pair: group; Configurator .. _doxid-group__te__engine__conf: Configurator ============ .. toctree:: :hidden: group_confapi.rst .. _doxid-group__te__engine__conf_1te_engine_conf_introduction: Introduction ~~~~~~~~~~~~ Configurator (Configuration Subsystem, CS) is an application of :ref:`Test Engine ` that exports configuration tree. A node of configuration tree can be associated with some software or hardware component controlled or tracked by a Test Agent. Such nodes have well-known path names and require support on te_agents side. Also :ref:`Configurator ` allows creating an arbitrary set of auxiliary configuration nodes that are not associated with anything and rather play role of shared storage or database. Configurator features: * stores a configuration database; * synchronizes the database with te_agents (See :ref:`Synchronization configuration tree with Test Agent `); * provides an API for traversing configuration tree; * provides an API to tests for the configuration reading and changing (See :ref:`Configuration tree traversal ` and :ref:`Configuration tree access operations `); * provides an API to tests and :ref:`Tester ` for backuping, verifying and restoring the configuration (See :ref:`Configuration backup manipulation `); * provides an API to tests for te_agents rebooting with or without restoring of the configuration (See :ref:`Test Agent reboot `). .. image:: /static/image/ten_conf_context.png :alt: Configurator context in TE .. _doxid-group__te__engine__conf_1te_engine_conf_tree: Configuration tree structure - Objects and Instances ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A configuration database consists of two trees: the tree of objects and the tree of instances. Objects are used to specify the attributes of an abstract configuration item: * type: integer, string, address (IPv4, IPv6, MAC); * access rights for the configuration item: read-only, read-write, read-create; * relations between configuration items (ownership of one item by another item); * dependencies between items (if changing of one configuration item may affect the existence or value of another configuration item). For example, MAC address of the network interface would have access rights “read-write”, type “address”, be owned by the interface, which in its turn is owned by the host. An IP address of the network interface (which is also “owned” by this interface) has access rights “read-create” because several IP addresses may be assigned to a single interface. Each object is identified by a string, which consists of several labels (sub-identifiers) separated by slashes. Each node in the object tree has its own sub-identifier and the full object identifier of the node is a sequence of sub-identifiers of its ancestors. For example, an object /agent/interface/net_addr is a son of the object /agent/interface which in its turn is a son of the object /agent. Tree of instances contains information about real configuration items observed by CS on te_agents, and/or instances created during processing of the configuration file or test requests. Each instance also has an object identifier. It also consists of a set of labels separated by slashes, but each label contains both a sub-identifier of the corresponding object and an instance name, which identifies uniquely the particular configuration item. Instance name is separated from the sub-identifier by a colon. For example, the instance /agent:nut/interface:eth0/net_addr:1.2.3.4 of the object /agent/interface/net_addr corresponds to IP address 1.2.3.4 on the network interface eth0 of the station on which Test Agent named nut is running. It's allowed to use empty instance names. For example, /agent/:nut/interface:eth0/link_addr: identifier is possible because the interface may have only one link address. An object sub-identifier must not contain symbols : (however this symbol is allowed in the instance name), '\*' and ' ' (space). Empty instance name is used when the object has only one instance. Instances which belong to /agent: subtree correspond to real configuration items observed on the te_agents (network interfaces, IP addresses, routes, ARP entries, daemons, etc.). Their change may lead to re-configuration of remote hosts. The list of basic configuration objects, which is likely to be supported by any Test Agent, can be found in ${TE_BASE}/doc/cm/cm_base.xml file. Other subtrees may be considered as information storage: changing instances in these subtrees does not affect the hosts controlled by te_agents, but may be used to share data between tests. API to browse configuration trees can be found at :ref:`Configuration tree traversal ` page. .. _doxid-group__te__engine__conf_1te_engine_conf_oper: Configuration Operations ~~~~~~~~~~~~~~~~~~~~~~~~ Two operations are allowed for the objects: Register and Unregister. Register operation describes attributes of a new object (identifier, type, access, dependencies) to :ref:`Configurator `. Unregister command forces :ref:`Configurator ` to forget about an object. Usually a command Register is used in the configuration file. Three operations are allowed for instances: Set (change the value), Add (add a new instance) and Delete (delete an existing instance). Moreover, :ref:`Configurator ` provides an API for read access to the object and instance databases (including different kinds of lookup). All operations requested in the configuration file and by the tests are stored in the history to allow quick configuration restoring. API to read and modify configuration tree can be found at :ref:`Configuration tree access operations ` page. .. _doxid-group__te__engine__conf_1te_engine_conf_backup: Configuration Backup ~~~~~~~~~~~~~~~~~~~~ Configuration backup is a snapshot of the object and instance trees. It is stored in the file and may be associated with the point in the command history. It is possible to create several backups at one or different points of the history. Backup verification is a simple comparison of the backup (snapshot) with the current state of the database. Restoring the configuration may be performed using two approaches: * Restoring by history (used only if a backup is associated with some point in the history): * The command list in the history is scanned in reverse order until the backup point is met. * The effect of each command is rolled back (for the add command the corresponding instance is deleted, for the delete command the corresponding instance is added etc.). * Restoring by a backup file (used when the backup is not associated with the history point or when the first approach fails): * Current database is synchronized with the snapshot – excessive instances are removed, missed instances are added, incorrect values are changed. After a successful restoring of the backup from the history or after a successful backup verification the command history may be cut off. API to manipulate configuration backups can be found at :ref:`Configuration backup manipulation ` page. .. _doxid-group__te__engine__conf_1te_engine_conf_file: Configurator Configuration File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`Configurator ` has its own configuration file where it is possible to specify the sequence of configuration operations to be run on :ref:`Configurator ` start-up. It is also possible to use a backup-like snapshot as a configuration file, which could be useful when you want to reproduce some problem that happens with particular configuration set-up. .. _doxid-group__te__engine__conf_1te_engine_conf_file_content: File Syntax ----------- You can find samples of :ref:`Configurator ` configuration files under ${TE_BASE}/conf directory. Normally the structure of :ref:`Configurator ` configuration files is organized as following: .. ref-code-block:: xml ... ... There can be multiple occurences of register object and add instance sections and they can be mixed. For example: .. ref-code-block:: xml This sample registers few object nodes and then adds some object instances. Instance adding feature is very useful when you need to tune some configuration parameters via configurator configuration file. Then from test scenarios it is possible to gather this information, which means there is no need to rebuild sources when you need to change some configuration, but instead you can just modify a simple text file. Note that you can also add new instances and set instance values of /agent subtree. For example if you want to switch off IPv4 forwarding in your test suite you can write the following lines in your configuration file: .. ref-code-block:: xml XSD schema of :ref:`Configurator ` configuration file can be found at ${TE_BASE}/doc/xsd/cs_config.xsd. .. _doxid-group__te__engine__conf_1te_engine_conf_file_features: Special features ---------------- One useful feature of :ref:`Configurator ` configuration file is that it is possible to include the content of one file into another with XML **include** tag. For example your upper level file can keep only includes to different parts of configuration: .. ref-code-block:: xml :ref:`Configurator ` allows to use environment variables in the content of configuration file. Which makes it possible to tune configuration via environment variables without modification of configuration file. For example: .. ref-code-block:: xml