Appendix - NVP
The NVP is designed to help customers change, retrieve and apply the configuration to UFM parameters of config files. NVP aims to eliminate the need of manually editing the config files. It is important to note that, NVP follows a transactional model approach. The NVP changes the configuration on temporary files. The changed configuration reflects back in the actual configuration only when `APPLY` is performed. The tool supports 4 standard file types mentioned below:
flat config: Refers to files that only have key-value pairs
ini: Refers to files that have sections associated with key-value pairs
xml: Refers to XML formatted files
plain text: Refers to files that contain plain text like format
In addition to above formats, NVP supports custom config of pgrp_policy_config to support pgrp_policy.conf file.
The tool is provided as a plugin and can be operated either as a standalone application using Docker commands or invoked through CLI commands. All the examples provided below illustrate the usage of NVP via CLI commands.
The tool supports the following functionalities:
set
get
dump
append
reset
apply
help
NVP operates on a transactional model, therefore it is recommended to avoid using it alongside manual configuration edits. Doing so may result in the loss of manually made changes when NVP applies its configurations to the relevant files. Users can either manually edit the configuration and then use NVP or vice versa, however it is not advisable to use them simultaneously.
Please note that the tool's plugin operates without a running daemon. Upon adding the plugin via the plugin infrastructure, its status remains "stopped" signifying its inactive state without a daemon. However, when a user initiates NVP (either through standalone Docker usage or via the CLI commands), the image activates, executes the command, performs the necessary operations, and then exits.
To add tools/NVP plugin, perform the following:
Add the tools plugin with "latest" tag, run:
ufm plugin tools add tag latest
It is recommended to disable the plugin as it is unnecessary for UFM to monitor the tools plugin. When the tools plugin invokes NVP Apply, it triggers a restart of UFM and all the plugins it monitors. To prevent this, disable the Tools/NVP plugin by running:
no ufm plugin tools enable
The Set API is designed to change a file's configuration based on the user's key-value pair. It updates the specified key with a new value. The NVP tool generates an error indicating 'key not found' if the given key is not found'. Additionally, NVP refrains from making any changes if the new value for the key is identical to the old one. It is important to note that both the key and value are case-sensitive.
Refer to nvp set for command syntax.
Example of the nvp set command that changes qos value to TRUE for opensm.conf(flat config):
nvp set opensm.conf qos TRUE
Similarly, for INI:
nvp set gv.cfg GarbageCollector.enable false
For XML files, a valid XPath must be provided. See below examples of the nvp set command for an XML config:
The XPath must be enclosed in double quotes for NVP to function.
nvp set UFMHealthConfiguration.xml "./TestsSchedule/Test[@Name='CheckMgmtInterface']/Frequency/Value"
20
nvp set UFMHealthConfiguration.xml "./SupportedTests/Test[@Name='CpuUsageTest']/TestOperation[@Name='CPUTest']/Parameters/Parameter[@Name='ThresholdInPercents']/Value"
120
Note that there may be instances where files share identical names but are located in different directories. In such scenarios, NVP requires the file name to include its parent directory. For example, consider the file launch_ibdiagnet_config.ini, which exists in both secondary_telemetry_defaults and telemetry_defaults directories. If a user intends to modify the file within secondary_telemetry_defaults, the command should resemble the following:
nvp set secondary_telemetry_defaults/launch_ibdiagnet_config.ini <key> <val>
To assign an empty value using the "nvp set" command, pass an empty string as the value. For example:
nvp set gv.cfg Multisubnet.multisubnet_role ""
The purpose of the "nvp get" command is to retrieve the configuration from a file based on the key provided by the user. If NVP cannot locate the specified key, it raises an error indicating 'key not found'. It is important to note that the "nvp get" retrieves values from the transactional configuration. This means that only files whose configurations have been modified by the user using the "nvp get" command will be accessible to it. Please note that the key is case-sensitive.
Refer to nvp get for command syntax.
An example of "nvp get" command that would retrieve QoS from opensm.conf(flat config):
nvp get opensm.conf qos
Similarly, for INI:
nvp get gv.cfg GarbageCollector.enable
For XML files, a valid XPath must be provided. Here are a few examples of GET commands for XML configurations:
nvp get UFMHealthConfiguration.xml ./TestsSchedule/Test[@Name
="CheckMgmtInterface"
]/Frequency/Value
nvp get UFMHealthConfiguration.xml ./SupportedTests/Test[@Name
='CpuUsageTest'
]/TestOperation[@Name
='CPUTest'
]/Parameters/Parameter[@Name
='ThresholdInPercents'
]/Value
The nvp dump command produces a unified JSON file. This JSON file contains the configurations of all the NVP-supported configuration files represented as JSON objects, consolidated into a single JSON structure. Each file's content or configuration is appended to create an aggregated JSON structure. The sequence of the JSON dump corresponds to the original configuration file's order.
Refer to nvp dump for command syntax.
The nvp append is provided to support plain text file format, making it useful for users who need to add any new configuration line as text to the configuration. Notably, the reset action follows a transactional model approach similar to the SET action (i.e Append copies the file and operates on the copy, the changes take effect once nvp apply is called).
The Append Action expects the below syntax:
nvp append <file_name> <config_line>
An example of Nvp Append that would add root_switches config to the root_guid.conf file is as follows:
nvp append root_guid.conf "root_switches"
Refer to nvp append for command syntax.
The nvp reset is provided to support plain text file format, making it useful for users to clear/empty the configuration. Notably, the reset action follows a transactional model approach similar to the SET action.
The Reset Action expects the below syntax:
nvp reset <file_name>
An example of NVP Reset to reset/empty the root_guid.conf file is as follows:
nvp reset root_guid.conf
Refer to nvp reset for command syntax.
The nvp apply command involves a two-step process. First, the NVP nvp apply command relocates all files that have been changed through the nvp set command to their original positions. The second step involves restarting the UFM Server to implement the new changes. The relocation of modified files from the transaction folder to their actual locations occurs independently of whether the UFM server is offline or if any errors arise during the UFM server restart process. Notably, NVP does not support rollback functionality in the event of an unsuccessful UFM server restart. Therefore, the first step of the nvp apply command operates irrespective of the outcome of the second step (UFM restart success/failure). However, if an error occurs during the first step, the function will prompt an appropriate error message and exit without attempting to restart the UFM.
Please note that a confirmation prompt is presented to the user before proceeding with this action, as the command restarts the UFM.
Refer to nvp apply for command syntax.
To bypass prompts, users can utilize the force option. This will initiate the UFM restart without any user interaction. Refer to nvp apply force for command syntax.
In situations where users want to apply the changed configuration and do not wish to restart the UFM, `no-restart` can be used.
Refer to nvp apply no-restart for command syntax.