Cisco CDA Visual Quality Experience Application User Guide, Release 3.0 - Chapter 6: Configuring VQE Server and VQE Tools [Cisco Videoscape Distribution Suite for Internet Streaming]

Table Of Contents

Configuring VQE Server and VQE Tools

Managing /etc Configuration Files Using the VQE CMS Versus Editing the Files Manually

Managing /etc Configuration Files with the VQE CMS

Managing /etc Configuration Files by Manually Editing the Files

Using the VQE Configuration Tool

Starting the Configuration Tool and Using the Root Menu

Using the Configuration Tool Menus

Entering Data for Configuration Parameters

Entering Data for Parameters That Can Have Only One Definition

Entering Data for Parameters That Can Have Multiple Definitions

Entering New Values for Parameters That Have a Currently Defined Value

Reverting to the Default VCDB Values

VQE Configuration Engine

VCDB Parser

Manually Editing the VCDB File

Using VCDB File Syntax

Multiple Definitions

Parameter Order

Understanding the vcdb.conf.sample File

Using the VQE Configuration Tool Command-Line Options

Configuring VQE Server and VQE Tools

This chapter describes these VQE Configuration Management System software components: VQE Configuration Tool, Configuration Engine, and the VCDB Parser. The chapter also provides task-based information on the following topics:

•Managing /etc Configuration Files Using the VQE CMS Versus Editing the Files Manually

•Using the VQE Configuration Tool

•VQE Configuration Engine

•VCDB Parser

•Manually Editing the VCDB File

•Using the VQE Configuration Tool Command-Line Options

The chapter also provides information on the VQE Configuration Engine and the VCDB Parser.

Note This chapter describes VQE configuration management facilities that are used after the VQE-S or VQE Tools server has been initially configured (on first power on). For information on initial configuration, see Chapter 2, "Getting Started with the VQE Startup Configuration Utility."

Table 6-1 provides acronyms or terms and descriptions for the major components of the VQE Configuration Management System that you need to be familiar with.

Table 6-1 VQE Configuration Management System Components

Acronym or Term

Expansion and Description

VCDB

VQE Configuration Database stores key-value pairs with the parameters and values you have specified with Configuration Tool or by manually editing the vdcb.conf file (the VCDB file).

CT

VQE Configuration Tool provides a menu-driven user interface that you use to display VCDB parameters and their values, add parameters to VCDB, and specify values for VCDB parameters needed for the operation of a VQE Server or VQE Tools system. See the "Using the VQE Configuration Tool" section.

CE

VQE Configuration Engine is used to apply the configuration values in VCDB (vcdb.conf) to the running VQE-S or VQE Tools server. CE also ensures that the configuration values in the VCDB and the configuration on the CDE110 server are synchronized. See the "VQE Configuration Engine" section.

CMS

VQE Configuration Management System includes CT, CE, and the VCDB Parser.

/etc configuration files

Configuration files in the directories under /etc. This is the set of configuration files for the CDE110 that hosts VQE Server or VQE Tools. These files include the existing VCDB file, all history VCDB backup files, the password file, the SDP file, and so on.

Managing /etc Configuration Files Using the VQE CMS Versus Editing the Files Manually

Starting with Cisco VQE Release 3.0, the configuration files under the /etc directory can be managed in two ways:

•Managing /etc Configuration Files with the VQE CMS

•Managing /etc Configuration Files by Manually Editing the Files

On both the VQE-S and VQE Tools hosts, the /etc configuration files are used for VQE software configuration and for CDE110 system and network configuration. For information on VQE, system, and network parameters, see Appendix A, "VQE, System, and Network Parameters."

Note Using the VQE CMS is the recommended method for managing VQE, system, and network configuration files.

For some deployments, it may be necessary to manage one or more /etc configuration files by manually editing the files because the set of CDE110 system and network parameters that can be managed by the VQE CMS does not include all system and network parameters that your implementation requires. Those /etc configuration files that you manage manually are removed from the control of the VQE CMS.

Managing /etc configuration files by manually editing the /etc configuration files has this disadvantage: When it becomes necessary to upgrade the VQE software to a later release, changes to the /etc files that you have made by manual file editing (outside the control of the VQE Configuration Management System) will, in most cases, be lost.

Managing /etc Configuration Files with the VQE CMS

Managing /etc configuration files with the VQE CMS consists of using the Configuration Tool or manual editing of the vcdb.conf file to set parameter values, and using the Configuration Engine to apply parameter values to the CDE110 server. Using the VQE CMS is the recommended method for managing VQE, system, and network configuration files. The VQE CMS automates much of the work related to configuring a VQE system. If you manage /etc files with the VQE CMS, the CMS automatically does the following:

•Provides the correct syntax for each /etc file parameter

•Checks for the allowed set of values for each /etc file parameter

•Restarts the appropriate system processes or reboots the CDE110 server so that changed parameter values take effect

•When a VQE software upgrade is required, automatically preserves your deployment's configuration in the upgraded software

In addition to this automation, using the VQE CMS to manage /etc configuration files makes it possible to efficiently setup multiple CDE110 servers. With the exception of some server-specific parameter values, the same VCDB set of parameter values (the vcdb.conf file) may be appropriate for multiple CDE110 servers.

Managing /etc Configuration Files by Manually Editing the Files

You can manage one or more /etc configuration files manually by editing them with a text editor. In this scenario, those /etc configuration files that you manage manually are removed from the control of the VQE CMS. For some deployments, it may be necessary to manage one or more /etc configuration files manually because the set of CDE110 system and network parameters that can be managed by the VQE CMS does not include all system and network parameters that your implementation requires.

For the VQE software itself, all user-configurable parameters can be managed with the VQE CMS. The essential VQE software parameters can be configured with VQE Configuration Tool. All VQE software parameters can be configured by manually editing the VCDB file (vcdb.conf).

With the VQE CMS, the Configuration Engine is used to apply VCDB values to the set of /etc configuration files. Each time VQE Configuration Engine runs, it performs a checksum comparison to determine which /etc configuration files have been manually edited. If an /etc configuration file has been manually edited, the Configuration Engine assumes that you (the VQE administrator) are managing the files manually, and Configuration Engine does not apply VCDB values to that /etc configuration file. When the Configuration Engine detects a checksum mismatch for an /etc configuration file, CE logs a warning message and, if CE is being used interactively, CE also displays the message on standard output.

Note The configuration parameters for the VQE software (and all system and network components) are contained in the vcdb.conf file, which can be manually edited. If you manually edit the VQE parameters in vcdb.conf, you must use the VQE Configuration Engine to apply the VQE parameters to the VQE configuration files under /etc. For the list of user-configurable VQE parameters, see Appendix A, "VQE, System, and Network Parameters."

When you manually manage some /etc configuration files and you later decide you would like the VQE CMS to start managing one or more such files, you can use the vqe_cfgtool command with the -fix_checksum option to have the checksum recomputed so that the manually edited /etc configuration files pass the checksum verification. This will allow these manually edited files to be managed through the VQE CMS, while at the same time preserving the manually edited sections of the file.

When you manually manage some /etc configuration files and you later decide you would like to return to using the factory default version of the /etc file, you can use the vqe_cfgtool command with the -fix_config option. When -fix_config is specified, vqe_cfgtool discards each /etc configuration file where there is a checksum mismatch and replaces it with the factory default /etc configuration file from the RPM package. vqe_cfgtool then recomputes the checksum using the factory default file

Using the VQE Configuration Tool

VQE Configuration Tool (CT) provides a menu-driven user interface that you use to display VCDB parameters and their values, add parameters to VCDB, and specify values for VCDB parameters needed for the operation of a VQE Server or VQE Tools system. Only essential parameters required for a VQE-S or VQE Tools system are configurable with CT. For those parameters that are not configurable with CT, you can use a text editor to manually modify the vcdb.conf file, which holds the VCDB. For information on editing vcdb.conf, see the "Manually Editing the VCDB File" section.

From the Linux command line, you start CT using the vqe_cfgtool command with the -config option. For information on the vqe_cfgtool command, see the "Using the VQE Configuration Tool Command-Line Options" section.

Note This section provides information on using CT when it is started with vqe_cfgtool -config. For information on the Cisco VQE Startup Configuration Utility, see Chapter 2, "Getting Started with the VQE Startup Configuration Utility."

Starting the Configuration Tool and Using the Root Menu

When CT is started with vqe_cfgtool -config, it calls the VCDB Parser to parse existing VCDB contents.

•If the Parser finds errors, CT displays the Parser output and quits. The Parser also logs the errors in the /var/log/vqe/vqe.log file.

Note To correct the parsing errors, you must use a text editor to manually edit the vcdb.conf file. You modify the file to correct parameter errors and remove parameters not recognized by the Parser.

•If the Parser finds no errors, CT displays the VQE Configuration Tool Root Menu:
VQE Configuration Tool Root Menu: 
     1) System Parameters 
     2) Network Parameters 
     3) VQE-S Parameters 
     S) Save and Exit 
     A) Save/Apply and Exit 
     E) Exit without saving 
Table 6-2 describes the choices on the CT Root Menu. You enter the number or letter for your choice.

Table 6-2 CT Root Menu Choices

Choice

Description

1) System Parameters

Configures the system parameters

2) Network Parameters

Configures the network parameters

3) VQE-S Parameters

Configures the VQE-S parameters. This choice is present only on the VQE-S system.

S) Save and Exit

Saves the changes you have made to the VCDB parameters and exits CT. Any new parameter values are not applied to the configuration files under /etc.

A) Save/Apply and Exit

Saves the changes you have made to the VCDB parameters, applies any new parameter values to the configuration files under /etc, restarts services (as needed), and exits CT.

E) Exit without saving

Exits CT. Any changes you have made to the VCDB parameters are not saved.

Using the Configuration Tool Menus

The System Parameters, Network Parameters, and VQE-S Parameters menus and prompts are self-documenting and do not require line-by-line explanation. The System Parameters menu, which is typical of the menu format, is as follows:
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      []
   3) DNS Search Domain:                  []
   4) Timezone:                           [America/New_York] 
   5) NTP Server(s):                      []
   6) SNMP RO Community String:           []
   7) SNMP System Location:               []
   8) SNMP System Contact:                []
   9) SNMP Trap Listener(s):              []
   R) Go to Root Menu 
   Enter a number choice followed by a letter 'd'(eg. 3d) will reset the 
   corresponding parameter to its factory default value. 
Enter your choice: 
To the right of the VQE Configuration Tool menu choice, one of the following is displayed:

•If a value is displayed, it is the current user-defined value for the parameter in VCDB. In the preceding example, vqe_server1 is the current user-defined value in VCDB for the Hostname parameter.

•If a value enclosed by brackets is displayed, this is the default value—the value used when no user-defined value has been specified. In the preceding example, America/New York is a default value.

•If empty brackets ([ ]) are displayed, there is no current user-defined value and no default value for the parameter.

For the default values used for specific parameters, see the file /etc/opt/vqes/vcdb.conf.sample.

In the System Parameters menu and similar menus, the numbered menu choices allow you to configure the set of relevant parameters. The lettered menu choice "R) Go to Root Menu" returns you to the Root menu.

CT allows you to specify values for the system, network, and VQE parameters that require configuration as well as some of the most common optional parameters. Table 6-3 tells you where to find guidance on the system, network, and VQE-S parameters that are configurable with CT.

Note When a VCDB parameter is not configurable with Configuration Tool, you can specify the parameter and a value for it by manually editing the /etc/opt/vqes/vcdb.conf file. For information on manually editing the vcdb.conf file, see the "Manually Editing the VCDB File" section.

Table 6-3 Where To Find Information on Configuration Tool Parameters

Configuration Tool Parameter

Where To Find Information

                                                     System Parameters

Hostname

Hostname for the CDE110, page 2-14

DNS Server(s)
DNS Search Domain

Domain Name System (DNS) IP Addresses and a Search Domain (Optional), page 2-14

Timezone

System Timezone and Current System Time, page 2-14

NTP Server(s)

NTP Server IP Addresses (Optional), page 2-14

SNMP RO Community String
SNMP System Location
SNMP System Contact
SNMP Trap Listeners

SNMP Read-only Community String, Location, Contact, and Trap-Listener IP Addresses or Hostnames (Optional), page 2-14

                                                      Network Parameters

Eth1 Interface
Eth2 Interface
Eth3 Interface
Eth4 Interface

Ethernet Interface Configurations IP Addresses and Prefix Lengths, page 2-14

Management Route(s)

IP Address and Prefix Length and Gateway Address for a Static Route for a Management Network (Optional), page 2-15

Default Gateway(s)

Gateway IP Addresses for Multipath Static Routes (VQE-S Host Only), page 2-15

                                        VQE-S Parameters (for VQE-S Host Only)

Trusted VCPT Host(s)

Trusted Channel-Provisioning Server (VQE-S Host Only), page 2-16

Log Priority

vqe.vqes.log_priority parameter in Table A-1

Excess Bandwidth Fraction

vqe.vqes.excess_bw_fraction parameter in Table A-4

VQE-S Traffic Interface(s)

Ethernet Interfaces That Will Be Used for VQE-S Traffic (VQE-S Host Only), page 2-16

Entering Data for Configuration Parameters

In the CT menus, when you enter a number for your choice, a set of prompts asks you for the required parameter information. This section provides information on using the System Parameters menu. Using the other CT menus is similar.

VCDB additions are appended to the end of the vcdb.conf file. That is, VCDB additions are added after the parameters that are already in the file.

The procedures for entering configuration data varies slightly depending on whether the parameter can have only one definition or multiple definitions.

Entering Data for Parameters That Can Have Only One Definition

To enter data for a VCDB configuration parameter that can have only one definition, do the following:

Step 1 When the System Parameters menu is displayed, enter the number for the parameter you want to configure and press Enter. In this example, a single definition is specified for the Hostname parameter.
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           [localhost]
   2) DNS Server(s):                      []
   3) DNS Search Domain:                  []
   4) Timezone:                           [America/New_York] 
   5) NTP Server(s):                      []
   6) SNMP RO Community String:           []
   7) SNMP System Location:               []
   8) SNMP System Contact:                []
   9) SNMP Trap Listener(s):              []
   R) Go to Root Menu 
   Enter a number choice followed by a letter 'd'(eg. 3d) will reset the 
   corresponding parameter to its factory default value. 
Enter your choice: 1 
Step 2 At the Hostname prompt, enter a hostname and press Enter.
Enter the Hostname of this server: vqe_server1 <Enter> 
For a parameter that allows only one definition, enter the needed data for the parameter and press Enter. Hostname allows only one definition. In this case, CT does not prompt for a multiple entries.

The System Parameters menu is displayed with the newly entered parameter value displayed to the right of the menu choice.
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      []
   3) DNS Search Domain:                  []
 ...
Entering Data for Parameters That Can Have Multiple Definitions

To enter data for a VCDB configuration parameter that can have multiple definitions, do the following:

Step 1 When the System Parameters menu is displayed, enter the number for the parameter you want to configure and press Enter. In this example, multiple definitions are specified for the DNS Server(s) parameter.
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1 
   2) DNS Server(s):                      []
   3) DNS Search Domain:                  []
   4) Timezone:                           [America/New_York] 
   5) NTP Server(s):                      []
   6) SNMP RO Community String:           []
   7) SNMP System Location:               []
   8) SNMP System Contact:                []
   9) SNMP Trap Listener(s):              []
   R) Go to Root Menu 
   Enter a number choice followed by a letter 'd'(eg. 3d) will reset the 
   corresponding parameter to its factory default value. 
Enter your choice: 2 
Configure DNS Server(s). Enter one DNS server on each subsequent line.          
Hit Enter at the prompt will complete this configuration.                       
Step 2 For a parameter that allows multiple definitions, enter one or more definitions on separate lines. To complete the configuration, press Enter at the prompt without entering data. For example, DNS Server(s) allows multiple definitions. In this case, CT prompts for multiple entries.
Enter a DNS server IP address: 1.2.3.4 <Enter> 
Enter a DNS server IP address: 5.6.7.8 <Enter> 
Enter a DNS server IP address: <Enter> 
The System Parameters menu is displayed with the newly entered parameter values displayed to the right of the menu choices.
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      1.2.3.4, 5.6.7.8 
   3) DNS Search Domain:                  []
 ...
Entering New Values for Parameters That Have a Currently Defined Value

For a parameter that has one or more currently defined values in VCDB, the Configuration Tool does not allow you to add additional values or delete a subset of the existing parameter values. When you add a new value for a parameter, all old values for that parameter are deleted.

Note When you specify a value for a parameter that already has a user-defined value specified, the old value for that parameter is deleted and the value you have entered becomes the current value.

If there are multiple existing definitions for a parameter and you specify a value for that parameter, all existing definitions are deleted and the value you have entered becomes the current value.

To enter a new value for a parameter that currently has a value defined in VCDB, do the following:

Step 1 At the System Parameters menu, enter the number of the parameter. For example:
Enter your choice: 2 
The prompt for the parameter is displayed:
Configure DNS Server(s). Enter one DNS server on each subsequent line.          
Hit Enter at the prompt will complete this configuration.                       
Enter a DNS server IP address:
Step 2 Enter the new parameter value and press Enter. For example:
Enter a DNS server IP address: 9.9.9.9 
Repeat this step if you want to add more parameter values. Each parameter value that you enter is added to VCDB in a cumulative manner.

Step 3 If you have no further parameter values to add, press Enter.
Enter a DNS server IP address: <Enter> 
When the System Parameters menu is displayed, the new parameter value (9.9.9.9) replaces any existing definitions and values.

As an example, assume that prior to entering a new value for a parameter, the DNS Server(s) parameter had two definitions, one with the value 1.2.3.4 and one with the value 5.6.7.8:
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      1.2.3.4, 5.6.7.8
   ...
After the new value (9.9.9.9) is entered, the DNS Server(s) parameter has one definition with the value 9.9.9.9:
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      9.9.9.9 
   ...
Reverting to the Default VCDB Values

To revert to the default VCDB value when an existing user-defined value has been specified, do the following:

When the System Parameters menu is displayed, enter the number of the parameter followed by the letter "d" and press Enter. For example:
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           vqe_server1
   2) DNS Server(s):                      9.9.9.9 
   3) DNS Search Domain:                  []
   4) Timezone:                           []
   5) NTP Server(s):                      []
   6) SNMP RO Community String:           []
   7) SNMP System Location:               []
   8) SNMP System Contact:                []
   9) SNMP Trap Listener(s):              []
   R) Go to Root Menu 
   To reset a parameter to its factory default, enter
   its number choice followed by the letter `d' (e.g. 3d).
   Default values are displayed inside square brackets [].
Enter your choice: 1d <Enter> 
Any existing values for the parameter that have been set in VCDB are deleted. The default value for the parameter is in effect.

In this example, when the System Parameters menu is displayed, the default value (localhost) is listed to the right of the parameter name (Hostname).
VQE Configuration Tool <System Parameters> Menu: 
   1) Hostname:                           [localhost] 
   2) DNS Server(s):                      9.9.9.9 
   ...
VQE Configuration Engine

Configuration Engine (CE) is used to apply the configuration values in VCDB (vcdb.conf) to the running VQE-S or VQE Tools server. CE also ensures that the configuration values in vcdb.conf and the configuration on the server are synchronized.

CE is invoked in the following ways:

•Each time the VQE-S or VQE Tools server reboots, CE runs automatically.

•From the Configuration Tool root menu, choose menu choice A—Save/Apply and Exit.

•From the Linux command line, use the vqe_cfgtool command with the -apply option to start CE.

For information on the vqe_cfgtool command, see the "Using the VQE Configuration Tool Command-Line Options" section.

When CE is invoked, it does the following:

1. CE (by calling the VCDB Parser) parses the entire vcdb.conf file for parameter validity. A line in vcdb.conf is invalid if it has unknown parameter keywords or syntax errors. If any invalid lines are found, CE logs an error for each invalid line and completes file parsing, but does not proceed to update the /etc configuration files. Instead, CE quits after parsing is complete. CE logs any invalid lines to the /var/log/vqe/vqe.log file on the VQE-S server or on the VQE Tools server. CE also displays parsing errors on standard output when run interactively.

If CE quits because of invalid lines in the vcdb.conf file, you must manually edit vcdb.conf to correct the invalid lines. Then issue the command vqe_cfgtool -apply to apply the values in vcdb.conf to the server's /etc configuration files.

Note When CE is automatically invoked during system reboot, no interactive questions are displayed. You are not prompted on whether to continue if CE detects a checksum mismatch for an /etc configuration file, or before changes are made to the running configuration and services restarted if a restart is needed to put a new parameter value into effect.

When CE is invoked using the vqe_cfgtool command and the -apply prompt-off option, no interactive questions are displayed before changes are made to the running configuration.

2. CE verifies the checksum of each /etc configuration file managed by the CMS. If a checksum is different, this usually means that changes outside of VCDB control (manual changes) have been made to this /etc file since the last CE update. If such a file is found, CE logs the file name and checksum mismatch to /var/log/vqe/vqe.log. CE does not apply VCDB values to /etc files where there is a checksum mismatch. To fix a checksum mismatch so that the /etc configuration file is again managed by the CMS, use vqe_cfgtool with the option -fix_checksum.

If CE cannot find or cannot read an /etc file, CE logs the error and does nothing. In this case, you must replace the missing file before normal VQE-S operations can continue. You can use vqe_cfgtool with -fix config to replace missing or unreadable /etc configuration files with the factory default configuration files.

Note Copies of the factory default configuration files are in the /vqe-etc/etc-pristine directory.

3. For synchronization, CE checks that all parameters in VCDB exist in the files under /etc, and that these parameters are effective within the running application. If there is a difference between the configuration values in VCDB and a configuration file under /etc, CE applies the VCDB values to the /etc configuration file where the differences exist.

VCDB is the authority for overall system configuration. If there is a conflict between VCDB and the configuration on the running system, the VCDB value always overrides the value in the /etc file.

4. CE backs up the VCDB files. The current running VCDB configuration is saved in the file /etc/opt/vqes/vcdb-running.conf. When CE finds a difference between the VCDB file (vcdb.conf) and the vcdb-running.conf file, it does the following:

•Updates the latest running configuration file with the values in vcdb.conf.

•Saves a copy of vcdb.conf in the archive directory (/etc/opt/vqes/archive/).

The name of the archived file contains the software version, date, and time stamp (for example, vcdb-3.0.0-20080204.1150.conf). Up to 100 VCDB archived backup files can be saved. Backup files over the 100 file limit are deleted based on the time stamp in the filename. Oldest files are deleted first.

5. After applying the VCDB values, CE (if needed) restarts the associated services or reboot the system. CE restarts only those services that had a VCDB value applied to the corresponding /etc configuration file and that require a service restart or reboot for the changed value to take effect.

Note In interactive mode, CE warns you when service interruptions are required to put a VCDB value into effect for the service, or when a reboot is required to put a VCDB value into effect. You can choose to apply the changes and restart services, or to terminate CE processing.

•If the system.hostname parameter value has changed, CE reboots the server, and all services are restarted.

•If the system.hostname parameter value has not changed, CE restarts individual services in the following order:

1. network and routing

2. iptables

3. Domain Name System (DNS)

4. Network Time Protocol (NTP)

5. Net-SNMP

6. VQE-S Process Monitor (VQE-S server only)

VCDB Parser

When the VCDB Parser starts, it reads the /etc/opt/vqes/vcdb.conf.sample file. This file contains information on all the valid VCDB parameters and their syntax. Next the VCDB Parser reads the /etc/opt/vqes/vcdb.conf file line by line, validates the syntax and parameter keywords, and outputs messages as it proceeds. The VCDB Parser writes its output informing you about any problems to the /var/log/vqe/vqe.log file and to standard output (if the Parser is used in an interactive mode). The VCDB Parser does not stop when it finds an error but finishes parsing the whole VCDB file.

There are several categories of VCDB Parser output messages: debug, info, warning, error. The format for the log messages is the same as is used for VQE-S logging. For information on log entry format, see "VQE Server and VQE Tools Logging and Log Files" section on page 5-2.

In addition to checking syntax and parameter keywords, the VCDB Parser also performs limited semantic checks. For example, if identical values are specified for a parameter that requires unique values, the VCDB Parser logs a warning and continues.

The VCDB Parser is invoked in the following ways:

•Each time the Configuration Tool runs, the VCDB Parser is automatically invoked.

•Each time the Configuration Engine runs, the VCDB Parser is automatically invoked.

•From the Linux command line, use the vqe_cfgtool command with the -parse option to start the VCDB Parser.

For information on the vqe_cfgtool command, see the "Using the VQE Configuration Tool Command-Line Options" section.

Manually Editing the VCDB File

The VQE Configuration Tool allows you to specify values for the required system, network, and VQE parameters. It also allows you to configure some of the most common optional parameters. When a VCDB parameter is not configurable with Configuration Tool, you can specify the parameter and a value for it by manually editing the /etc/opt/vqes/vcdb.conf file.

This section provides information on how you specify parameters in the vcdb.conf file and how you use the reference information in the vcdb.conf.sample file to edit vcdb.conf:

•Using VCDB File Syntax

•Understanding the vcdb.conf.sample File

For information on the VCDB parameters, see Appendix A, "VQE, System, and Network Parameters."

Note When you manually edit the vcdb.conf file to modify, add, or remove parameters, you must apply the parameter values in vcdb.conf to the server /etc configuration files in order for the changed parameters to take effect. To apply the values, use the vqe_cfgtool command with the -apply option. For information on vqe_cfgtool, see the "Using the VQE Configuration Tool Command-Line Options" section.

Tip After you manually edit and save the vcdb.conf file, use the vqe_cfgtool command with the -parse option to check that your changes have not created any errors in the file.

Using VCDB File Syntax

This section provides information on the syntax rules you need to follow when editing the vcdb.conf file.

The vcdb.conf file contains a list of key-value pairs. Each key-value pair is associated with a system, network, or VQE parameter that is used to configure a VQE-S or VQE Tools system. Each key-value pair has the following syntax:

section.subsection.parameter = "value"

Each key is associated with a section and subsection. Section names are vqe, system, and network. Some key-value pair examples are as follows:
vqe.vqes.exporter_enable = "TRUE"
system.global.hostname = "iptv_host"
network.eth1.addr = "11.2.9.2/24"
The syntax rules for the vcdb.conf file are as follows:

•Allowed VCDB keys and their syntax are defined in the vcdb.conf.sample file.

•Each key is case-sensitive.

•The key and its value are separated by an equal sign (=).

•The value is enclosed by quotation marks ("value").

•A comment line starts with #. The VCDB Parser ignores these lines.

•The following are allowed but ignored:

–Leading space before a key

–Leading space before and trailing space after a value

–Spaces before or after the equal sign (=)

Multiple Definitions

If a parameter definition appears more than once in vcdb.conf when multiple definitions of the parameter are not allowed, the VCDB Parser logs an error and terminates. None of the values in vcdb.conf are applied to the /etc configuration files.

When this multiple definition error occurs, you must edit vcdb.conf manually to correct the items that are in error.

Parameter Order

For those parameters that can only appear once in VCDB, parameter order is not important.

If a parameter can have multiple values, it requires multiple lines of definition. Each line defines one value. The order of these definitions in the vcdb.conf file is important because the same order is kept in the /etc configuration files. Consider the following vcdb.conf file items:
system.snmp.trap_listener = "1.2.3.4"
system.snmp.trap_listener = "5.6.7.8"
When the Configuration Engine applies these two system.snmp.trap_listener items to the /etc/snmp/snmpd.conf file, listener 1.2.3.4 is defined in the snmpd.conf file before listener 5.6.7.8 because 1.2.3.4 is specified first in the vcdb.conf file.

Understanding the vcdb.conf.sample File

For each VQE release, the vcdb.conf.sample file provides user reference information on the parameters recognized by the VCDB Parser. For each VCDB parameter, vcdb.conf.sample contains the key-value pair, syntax rules, range of allowed values, and other information. The vcdb.conf.sample file is located in /etc/opt/vqes/vcdb.conf.sample. It is a read-only file and should not be moved.

To determine how to specify a VCDB parameter in vcdb.conf, you read about the parameter and its usage in vcdb.conf.sample. Some parameter examples from vcdf.conf.sample are as follows:
# system.global.hostname="localhost"
# Description: "Fully Qualified Domain Name (FQDN) or hostname of the system."
# Type: String, minimum length 3 characters, maximum length 200 characters
# Default value: localhost
# Required: N
# Service interruption: "System reboot. "
# Allow multiple definitions: N
# Target /etc file: ""127.0.0.1" in /etc/hosts and "HOSTNAME" in /etc/sysconfig/network"
# network.eth1.addr=""
# Description: "IP address and network mask length for interface eth1 in the for
m ""1.2.3.4/24"""
# Type: IP_Prefix
# Default value: 
# Required: N
# Service interruption: "Potential network traffic interruption. "
# Allow multiple definitions: N
# Target /etc file: ""IPADDR" and "NETMASK" in /etc/sysconfig/network-scripts/if
cfg-eth1"
# vqe.vqes.log_priority="4"
# Description: "Global logging priority level for all VQE applications. Valid va
lues are 0-6. 0 - EMERGENCY, system is unusable, 1 - ALERT, action must be taken
 immediately, 2 - CRITICAL, critical conditions, 3 - ERROR, error conditions, 4 
- WARNING, warning conditions, 5 - NOTICE, normal but significant condition, 6 -
 INFO, informational. Levels less than or equal to log-level will be logged.",
# Type: Integer, minimum value is 0, maximum value is 6
# Default value: 4
# Required: N
# Service interruption: "VQE Process Monitor restart."
# Allow multiple definitions: N
# Target /etc file: ""log-level" in /etc/opt/vqes/.vqes.conf"
In vcdb.conf.sample, the first line of an entry is the key-value pair for the parameter. Table 6-4 lists the vcdb.conf.sample reference information that describes each VCDB parameter.

Table 6-4 Parameter Information in the vcdb.conf.sample File

Field

Description

Description

Explains how the parameter is used.

Type

Specifies one of the following data types and, if applicable, the range of values allowed.

•Integer—A whole number.

•Float—A floating-point number (for example, 10.25 or -5.75 or .50). The allowed floating-point numbers correspond to those allowed by the Perl float type.

•String —One or more characters. The set of characters allowed varies depending on the parameter.

•Boolean—Either true or false.

•IP—An IPv4 address in dotted-decimal form (for example, 10.0.0.1). The IP address must be in the range allowed for an IPv4 address.

•IP_PREFIX—An IP address and prefix-length in the form ip-address/prefix-length (for example, 10.0.0.0/8). The ip_address is the same as in IP. The prefix-length must be in the range 0 to 32.

•Route—A route in the format ip-address/prefix-length via ip-address (for example,
10.0.0.0/8 via 11.2.9.1). Each ip_address is the same as in IP. The prefix-length must be in the range 0 to 32.

•Host—Either an IP address or a string representing a fully qualified domain name (for example, myhost.company.com). The IP address is the same as in IP.

Default value

Specifies a default value. If there is no default value, this field is blank.

Required

Specifies one of the following:

•Y—The parameter must be defined, and there is no default value.

•N—The parameter does not have to be defined.

You can define a parameter by using the Configuration Tool or by manually editing the vcdb.conf file with a text editor.

Service interruption

Indicates whether VQE services will be interrupted when the parameter definition is applied to the relevant configuration file (for example, when you invoke the vqe_cfgtool command with the -apply option).

Allow multiple definition

Specifies one of the following:

•Y—The parameter can be specified more than once in the vcdb.conf file.

•N—The parameter can be specified only once in the vcdb.conf file.

Target /etc file

Specifies the configuration file under /etc that will be written to when the parameter is applied. Also indicates the configuration items that will be written to the /etc configuration file.

In the system.global.hostname parameter example preceding this table, "Target /etc file" indicates that a line 127.0.0.1 host_name will be written to the file /etc/hosts, and a line HOSTNAME=host_name will be written to the /etc/sysconfig/network file. The host_name is the value specified for system.global.hostname. The exact syntax for the line that will be added to the /etc file is not specified in the "Target /etc file" field.

Using the VQE Configuration Tool Command-Line Options

The vqe_cfgtool command performs a variety of configuration tasks related to the VQE Configuration Database (VCDB) and the configuration files under the /etc directory on a VQE-S or VQE Tools server.

The syntax for the vqe_cfgtool command is as follows:

vqe_cfgtool [-apply [prompt-off] | -backup | -config | -fix_checksum | -fix_config | -help |
-parse [full_pathname] | -restore full_pathname | -sanity_check | -version]
Syntax Description

-apply [prompt-off]

Launches the Configuration Engine to apply the values in VCDB to the server /etc configuration files.

If you specify prompt-off, no interactive questions are displayed before changes are made to the running configuration.

-backup

Copies all files under /etc into a tar file and saves the tar file in /vqe-etc/vqe-release-hostname-timestamp.tar.gz.

-config

Launches the Configuration Tool so that you can modify the VQE configuration parameter values that are stored in VCDB.

-fix_checksum

Recomputes the checksum for each /etc configuration file that has a checksum mismatch.

-fix_config

Discards the current copy of each /etc configuration file where there is a checksum mismatch and replaces it with the original copy of the file that comes with the RPM package.

-help

Displays information on how to use the vqe_cfgtool command and its options. If no valid option is specified when vqe_cfgtool is invoked, -help is the default.

-parse [full_pathname]

Performs validation of the VCDB contents (parameters, values, syntax, and so on) for the current vcdb.conf file.

If full_pathname is specified, that file is parsed rather than the current vcdb.conf file.

-restore full_pathname

Extracts the contents of the tar file specified in full_pathname, and replaces all /etc configuration files with the tar file contents. The tar file is typically created with vqe_cfgtool -backup.

-sanity_check

Compares the parameter values in VCDB with the values in the /etc configuration files, and displays any differences on the command line.

-version

Displays software version information.

Usage Guidelines

The vqe_cfgtool command is available on the VQE-S or VQE Tools server. The tool is located in the /opt/vqes/bin directory. You must have root privileges to invoke vqe_cfgtool. The vqe_cfgtool command does not respond to Ctrl-C and cannot be exited prematurely once execution has started.

The vqe_cfgtool command writes its output to standard output (by default, it is displayed on the command line) and to the /var/log/vqe/vqe.log file.

-apply Option

When -apply is specified, vqe_cfgtool invokes the Configuration Engine to apply the VCDB values to the server /etc configuration files. After applying the VCDB values, CE (if needed) will restart the associated services or reboot the system. CE restarts only those services that had a VCDB value applied to the corresponding /etc configuration file and that require a service restart or reboot for the changed value to take effect. For a detailed description of Configuration Engine processing, see the "VQE Configuration Engine" section.

If prompt-off is specified with the -apply option, you are not prompted on whether to continue for these two situations:

•If the Configuration Engine detects a checksum mismatch for an /etc configuration file. If a checksum is different, this usually means that unauthorized changes (that is, changes outside of VCDB control) have been made to this file after the last CE update.

•Before changes are made to the running configuration and services restarted (if a restart is needed to put any new parameter values into effect).

-backup and -restore Options

When -backup is specified, vqe_cfgtool saves all files under /etc into a tar file and saves the tar file in /vqe-etc/vqe-release-hostname-timestamp.tar.gz. After vqe_cfgtool saves the tar file, it displays the location of the tar file and reminds you to use the scp command to copy the file to a remote server. The -backup option is typically used before -config or -apply so that a backup copies of the /etc configuration files are available for rollback purposes.

When -restore full_pathname is specified, vqe_cfgtool extracts the contents of the tar file specified in full_pathname, and replaces all /etc configuration files with the tar file contents. The full_pathname argument usually gives the path to a tar file that has been created with -backup.

-config Option

When -config is specified, vqe_cfgtool parses the vcdb.conf file and, if there are no errors, runs the Configuration Tool so you can modify parameter values in VCDB. For information on how Configuration Tool works, see the "Using the VQE Configuration Tool" section.

-fix_checksum Option

VQE Configuration Engine does not apply VCDB values to /etc configuration files where there is a checksum mismatch. Use the -fix_checksum option to fix the checksum of one or more /etc configuration files that have a checksum mismatch.

When -fix_checksum is specified, vqe_cfgtool loops through /etc configuration files that have checksum mismatches and, for each, asks if you want the VQE CMS to manage the file again. If you answer yes, vqe_cfgtool recomputes the checksum for the file.

For information on how the Configuration Engine works, see the "VQE Configuration Engine" section.

-fix_config Option

When -fix_config is specified, vqe_cfgtool discards each /etc configuration file where there is a checksum mismatch and replaces it with the factory default /etc configuration file from the RPM package. vqe_cfgtool then recomputes the checksum using the factory default file.

A missing or unreadable /etc configuration file is considered a checksum mismatch and -fix_config copies the default factory file into the appropriate directory below /etc.

-parse Option

When -parse is specified, vqe_cfgtool parses the vcdb.conf file or, if the optional full_pathname is given, it parses the indicated file. This option is typically used to check the validity of offline VCDB configuration files. For information on the VCDB Parser, see the "VCDB Parser" section.

-sanity_check Option

When -sanity_check is specified, vqe_cfgtool checks the following:

•Whether the files under /etc have been manually edited (changes made not using VCDB)

•Whether the RPM software on the server is intact and no piece is missing

•Whether the vqe user account exists on the server

If vqe_cfgtool finds a problem with any of the preceding checks, it displays information about the issue on standard output.

Tip You can use the cron command to execute vqe_cfgtool -sanity_check periodically to check VQE-S or VQE Tools system sanity.