Appendix - NVP
The NVP is designed to help customers change, retrieve, and apply the configuration changes to UFM configuration files. NVP aims to simplify the process, sparing users from manually editing the config files. NVP follows a transactional model approach, modifying/setting the configuration on temporary files. These changes are only integrated into the actual configuration upon executing the apply command. The tool supports three file types:
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
It is important to note that the current version of NVP does not facilitate adding new configurations to existing configuration files. 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
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 NVP is designed to help customers change, retrieve, and apply the configuration changes to UFM configuration files. NVP aims to simplify the process, sparing users from manually editing the config files. NVP follows a transactional model approach, modifying/setting the configuration on temporary files. These changes are only integrated into the actual configuration upon executing the apply command. The tool supports three file types:
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
It is important to note that the current version of NVP does not facilitate adding new configurations to existing configuration files. 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
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
NVP Set
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 ""
NVP Get
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
NVP Dump
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.
NVP Apply
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.
NVP Apply Force
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.