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 to edit the config files manually. It is important to note that, NVP follows a transactional model approach. The NVP changes the configuration on temporary files. The changed configuration is reflected 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 pairsini: Refers to files that have sections associated with key-value pairsxml: Refers to XML formatted filesplain text: Refers to files that contain plain text-like format
In addition to the 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:
setgetdumpappendresetdiscardbackuprollbackapplyresethelp
NVP operates on a transactional model; therefore, it is recommended that it is avoided 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 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 the "2.0.0-4" tag:
ufm plugin tools add tag
2.0.0-4It is recommended to disable the plugin as it is not necessary 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
NoteAs of NVP 2.0.0 and UFM Enterprise v6.19.0, users no longer need to disable the plugin manually. By default, UFM will not monitor the tools plugin.
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 NVIDIA UFM-SDN Appliance Command Reference Guide 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 ""
As of version 2.0.0, NVP supports the SET command with a force flag. This feature is helpful when a configuration does not exist and the user wants to add it to a file. The force option is available only for flat config and ini files. For INI files, the force flag first checks for a matching section. If the section is not found, NVP will create it and then add the key-value pair to the newly created section. If the section exists but the key does not, NVP will add the new key-value pair to the existing section.
The command follows this syntax:
nvp set <file_name> <key> <value> force
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
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 NVIDIA UFM-SDN Appliance Command Reference Guide 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 NVIDIA UFM-SDN Appliance Command Reference Guide 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 API to reset/empty the root_guid.conf file is as follows:
nvp reset root_guid.conf
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
The NVP Discard feature allows users to discard any configuration changes made. This action deleted the specified file from the transaction folder, resulting in the loss of all changes made by the user. NVP Discard can be performed on each file by specifying the file name as an argument. If no argument is provided, the entire transaction folder will be deleted, discarding changes for all NVP-supported files.
The Discard action expects the below syntax, with the file name being optional:
nvp discard <file_name>
For example, to discard changes to the gv.cfg file, use the command:
nvp discard gv.cfg
To discard all files, use the command:
nvp discard
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
The NVP Backup feature creates backups of all NVP-supported files in the form of a tarball. Users can specify a name for the tarball; if none is provided, NVP generates a backup name based on the current timestamp. The created backup tarball can later be applied using the ROLLBACK API. By default, the maximum number of backups is set to 10, but this limit can be adjusted by modifying the backup limit configuration parameter in the nvp.cfg file.
Note: Backups should only be performed when there are no pending changes to apply and there are no files in the transaction folder. If this condition is not met, the backup action will result in an error.
The Backup action expects the below syntax, with the backup name being optional:
nvp backup <backup_name>
For example, to create a backup with a specified name, use:
nvp backup nvp_backup_initial_configuration
If the backup name is not specified, NVP generates a tarball named in the format nvp_backup_<TS>.tar.gz. For instance, the command below creates a tarball named nvp_backup_2024-10-10_09-40-48.tar.gz:
nvp backup
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
To assist users in managing backups, utility functions such as Delete, Fetch, and Upload are available. These APIs are implemented at the CLI level and are not part of the NVP Image.
The Delete command removes the specified backup file created using the
BACKUPcommand. The syntax for this command is:nvp delete <backup_name>
Refer to nvp delete for command syntax.
The Fetch command downloads the NVP backup configuration from a remote host. The syntax for this command is:
nvp fetch <url>
Refer to nvp fetch for command syntax.
The Upload command uploads the NVP backup configuration to a remote host. The syntax for this command is:
nvp upload <backup_name> <url>
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
The NVP Rollback action restores the contents of the specified tarball (a backup configuration created using the BACKUP action) to the transactional folder, overwriting its current contents.
Note: Since the Rollback action overwrites the transactional folder, users must subsequently call APPLY to implement the changes from the transactional folder to the UFM configuration.
The Rollback action expects the below syntax, where backup_tar is the name of the tarball:
nvp rollback <backup_tar>
For example, to apply the configuration from backup_1.tar.gz, the command would be:
nvp rollback nvp_backup_initial_configuration.tar.gz
To bypass prompts, users can utilize the force option.
Refer NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
The nvp apply command involves a two-step process. First, the nvp apply command moves 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 NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.
To bypass prompts, users can utilize the force option. This will initiate the UFM restart without any user interaction.
Refer NVIDIA UFM-SDN Appliance Command Reference Guide 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 NVIDIA UFM-SDN Appliance Command Reference Guide command syntax.