Table Of Contents

Configuring VQE-S

Process Monitor Command-Line Options

VQE-S Configuration File Location and Editing

Editing the VQE-S Configuration File

Saving the VQE-S Configuration File and Restarting Process Monitor

VQE-S Configuration File Format and Options

Global Options

Process Options

Configuring VQE-S

---

If needed, the service provider can configure VQE-S using the command-line options to the process_monitor command and the global and process options in the VQE-S configuration file. The command-line options are for the Process Monitor, the process that starts and monitors other VQE-S processes. The process options in the configuration file are for these VQE-S processes:

•Control Plane

•Data Plane

•Multicast Load Balancer

This appendix provides information on using command-line options to the process_monitor command and the global and process options in the VQE-S configuration file. The appendix has these sections:

•Process Monitor Command-Line Options

•VQE-S Configuration File Location and Editing

•VQE-S Configuration File Format and Options

---

Note Modifying the vqes.conf file is not expected to be required in the typical deployment. Make any changes to the file carefully as the configuration options directly affect the behavior of the VQE-S processes.

---

Process Monitor Command-Line Options

The process_monitor command starts the VQE-S Process Monitor process, which in turn starts and monitors the other VQE-S processes—Control Plane, Data Plane, Multicast Load Balancer, and STUN Server. You can use the options to the process_monitor command to configure some Process Monitor behaviors.

The syntax for the process_monitor command is as follows:

process_monitor [{-c | --config-file} cfg_filepath] [{-l | --log-level} log_level]
[{-x | --xmlrpc-port} xmlrpc-port]

The process_monitor command provides a short and long version for the keywords used for each option. For example, the path (cfg_filepath) to the configuration file can be preceded by the keyword -c or --config-file.

Syntax Description

cfg_filepath	Specifies a full path name for the location of the VQE-S configuration file. The default path name is /etc/opt/vqes/vqes.conf.
log_level	Specifies an integer (0 to 7) indicating the logging level for the VQE-S Process Monitor process. Default value is Warning (4). For more information on logging levels, see the Usage Guidelines that follow.
xmlrpc-port	Specifies the TCP port number to be used by the XML-RPC remote interface. Recommended values are greater than 1024. Default value is 8050.

Usage Guidelines

The process_monitor command is started from the Linux /etc/inittab file. The entry for process_monitor must be the last entry in the file. For more information on editing the entry for process_monitor in the inittab file, see the "Starting the VQE-S Processes and Verifying Status" section on page D-12.

Table A-1 lists the logging levels that can be specified in the log_level option.

Table A-1 Logging Levels

log_level	Name
0	Emergency
1	Alert
2	Critical
3	Error
4	Warning
5	Notification
6	Informational
7	Debugging

Logging levels go from least verbose to most verbose. The Emergency level generates the smallest number of messages, and the Debugging level generates the greatest number of messages.

When you select a logging level, log messages are generated that level and the levels below that level. For example, when the level is set to Error, messages are generated for Emergency, Alert, Critical, and Error.

VQE-S Configuration File Location and Editing

The VQE-S configuration file is named vqes.conf and, by default, is located in the /etc/opt/vqes directory.

Editing the VQE-S Configuration File

You edit the vqes.conf file with a text editor, such as vi. To edit the file, you must be logged in as root or have used su or sudo to be granted root privileges. The file is read-only for all non-root users.

If Process Monitor finds an error in the vqes.conf file, it writes a syslog entry in the /var/log/vqes/vqes.conf file. When appropriate, the entry specifies a line number in vqes.conf and information on the syntax error. For example:

<<%VQES_PM-2-PM_CFG_PARSE_FAILURE>> Configuration file syntax error "mismatched element 
type in array" on line 26 in file /etc/opt/vqes/vqes.conf 

A number of conventions are used to structure each entry in the vqes.conf file. The following syntax rules apply when editing the vqes.conf file:

•Each line for an option has the following format:

option-name = option-value;

Each line with an option is ended with a semi-colon (;).

•Comments begin with a # character and extend to the end of the line.

•Boolean values can be specified in the following ways:

setting = true; OR setting = TRUE;

setting = false; OR setting = FALSE;

•Numeric values are not quoted.

integer_value = 5;

hex_value = 0xa5B;

float_value = -4.3

•Strings are quoted.

string = "String Value";

•Arrays are defined by square braces and all elements must be of the same type.

valid_array = ["string1", "string2", "string3"];

invalid_array = ["string1", true, 34];

Saving the VQE-S Configuration File and Restarting Process Monitor

After you edit and save the vqes.conf file, restart VQE-S Process Monitor. The configuration file is read once when Process Monitor starts. The configuration file can be changed while VQE-S is running, but the changes do not take effect until VQE-S is restarted. For information on restarting VQE-S, see the "Stopping and Restarting VQE-S" section on page 2-23.

If Process Monitor reads the vqes.conf file and detects a syntax or other error, it does not start and writes an error message to the /var/log/vqes/vqes.log file. For example:

<<%VQES_PM-2-PM_INIT_FAILURE>> Process Monitor initialization has failed for the 
specified reason: Config File Parsing 

For information on vqes.conf file syntax, see the "Editing the VQE-S Configuration File" section.

VQE-S Configuration File Format and Options

The VQE-S processes that you can configure by modifying the vqes.conf file include: Process Monitor, Control Plane, Data Plane, Multicast Load Balancer, and STUN Server. The VQE-S configuration file is divided into these sections:

•Process options—Options that apply to specific VQE-S processes

•Global options—Options that apply to all VQE-S processes

•Process definitions—Definitions that apply to specific VQE-S processes

---

Note Only the process options and global options should, if it is required, be modified.

With the exception of the run option for the stun_server process, do not modify the process definitions in the VQE-S configuration file. For information on the run option for the STUN Server, see the "Enabling the VQE STUN Server (Optional)" section on page D-8.

---

The following is an abbreviated example of the VQE-S configuration file: Only the required options are shown and many comments that appear in the default vqes.conf file are omitted.

# VQE-S config file

# Copyright (c) 2007 by Cisco Systems, Inc.

# All Rights Reserved.

# List of vqes service modules monitored by process_monitor

vqes_applications = ["mlb", "vqes_control_plane", "vqes_data_plane", "stun_server"];

# PROCESS OPTIONS BEGIN 

# VQE-S Control Plane settings 

vqes_control_plane =

{

  xmlrpc-port = 8051;

  cfg = "/etc/opt/vqes/vqe_channels.cfg";

};

# VQE-S Control Plane settings 

vqes_data_plane = 

{

# No required options 

}; 

# VQE-S Multicast Load Balancer settings

mlb =

{

  interface = "eth1,eth2,eth3,eth4";

  xmlrpc-port = 8052;

};

# STUN Server settings 

stun_server =

{

  xmlrpc-port = 8054;

};

# PROCESS OPTIONS END 

############################################################

# Warning: Changing contents below this line may adversely 

#  affect the behavior of process monitor. Modifications 

#  should be made carefully and in accordance with VQE-S

#  documentation. All parameters below are REQUIRED unless

#  otherwise noted. 

############################################################

#

# Definition beginning start of Process Monitor specific section

#

process_monitor =

{

# GLOBAL OPTIONS BEGIN 

   status_check_interval = 5;

# GLOBAL OPTIONS END 

# PROCESS DEFINITIONS BEGIN 

  vqes_control_plane =

   {

     name = "VQE-S Control Plane";

     exec = "/opt/vqes/bin/vqes_cp";

     dependency = ["vqes_data_plane"];

     startup_dependency = ["vqes_data_plane"];

     post = "/opt/vqes/bin/fbt_flush.sh >> /var/log/vqes/fbt.log";

   };

   vqes_data_plane =

   {

     name = "VQE-S Data Plane";

     exec = "/opt/vqes/bin/vqes_dp";

     dependency = ["mlb", "vqes_control_plane"];

     startup_dependency = ["mlb"];

     privileged = true;

   };

   mlb =

   {

     name = "Multicast Load Balancer";

     exec = "/opt/vqes/bin/mlb";

   };

   stun_server =

   {

     name = "STUN Server";

     exec = "/opt/vqes/bin/stun_server";

     privileged = true;

     run = false;

   };

# PROCESS DEFINITIONS END

};

# VQE-S Configuration File Syntax Version number

version = 1;

In the next two sections, the tables that list the global options and process options provide the format for each option.

Global Options

Global options affect all VQE-S processes. You enter global options after the opening brace in the Process Monitor definition and before the vqes_control_plane process definition. In the following example, status_check_interval = 5; is a global option.

process_monitor =

{

   status_check_interval = 5;

vqes_control_plane =

... 

Table A-2 lists the VQE-S global options. All global options are optional and do not have to be specified in the vqes.conf file.

Table A-2 VQE-S Global Options

Global Option	Description
status_check_interval = seconds;	Specifies the frequency in seconds that Process Monitor checks for a down VQE-S process (Control Plane, Data Plane, and Multicast Load Balancer). A shorter value results in faster detection but greater overhead on the system. Allowed range is 1 to 300 seconds. Default value is 5 seconds.
nonpriv_user = "UID";	Gives the user ID that a nonprivileged VQE-S process runs under. The user ID must exist in the system and cannot be root (0). Default value is "vqes".
nonpriv_group = "GID";	Gives the group ID that a nonprivileged VQE-S process runs under. The group ID must exist in the system and cannot be root (0). Default value is "vqes".

Process Options

Process options apply to a specific VQE-S process. In the process options section, you enter the options between the opening and closing braces ({ }) in the block of statements specified for the process. The process options section is located toward the beginning of the vqes.conf file. For example, the Control Plane block of process options is as follows:

vqes_control_plane =

{

  xmlrpc-port = 8051;

  cfg = "/etc/opt/vqes/vqe_channels.cfg";

};

In the preceding example, the block of options for Control Plane is identified by vqes_control_plane = and by the block's opening and closing braces ({ }). You enter the Control Plane process options in this block.

---

Note Do not enter process options in the process definition for the process.

---

Tables A-3 to A-5 list the VQE-S process options that can be configured by the user for the three VQE-S processes. In the tables, an option marked Required must be specified in the vqes.conf file. The default value listed in the tables is used when the option is not explicitly specified in the vqes.conf file.

•Table A-3 lists process options for the Control Plane (vqes_control_plane).

•Table A-4 lists process options for the Data Plane (vqes_data_plane).

•Table A-5 lists process options for the Multicast Load Balancer (mlb).

•Table A-6 lists process options for the STUN Server (stun_server).

---

Note VQE-S has more process options than are listed in the following tables. If a process option is not listed in the tables, that option value should be changed only at the request of Cisco Technical Support.

---

Table A-3 Control Plane Process Options

Process Option	Description
cfg = "channel_cfg_pathname";	(Required) Gives the path name for the channel configuration file. Default value is /etc/opt/vqes/vqe_channels.cfg. The specified directory must exist and be writable by the Control Plane process.
burst-rate = burst_rate_percent;	Specifies the percent of excess bandwidth that will be used for Error Repair. Allowed range is 0 to 100. Default value is 20.
er-cache-time = time_in_ms;	Specifies the amount of time (in milliseconds) to cache original source stream packets for Unicast Retransmission. Default value is 3000.
exporter-enable = true_or_false;	Specifies whether RTCP exports are enabled. The value true enables RTCP exports, and false disables RTCP exports. Default value is false. If exporter-enable equals true, both vqm-host and vqm-port must be provided. For information on configuring RTCP Exporter, see the "Configuring VQE-S RTCP Exporter" section on page 2-22.
log-level = log_level;	Specifies the logging level for the VQE-S Control Plane process. Allowed values are 0 (Emergency) to 7 (Debugging). Default value is 4 (Warning). For information on logging levels, see the Usage Guidelines in the "Process Monitor Command-Line Options" section.
max-channels = max_number;	Specifies the maximum number of channels supported by RTP/RTCP and Error Repair. Allowed range is 100 to 1000. Default value is 250. The practical limit of MPEG-2 SD channels that can be serviced by one VQE-S is approximately 250.
max-clients = max_number;	Specifies the maximum number of clients supported by RTP/RTCP and Error Repair. Allowed range is 1 to 2,000,000. Default value is 32,000. Each VQE-S supports up to 10,000 VQE Clients on set-top boxes. The actual number of VQE Clients supported will vary depending on the error characteristics of the transmission lines, home wiring, and other external factors.
no-dynamic-fbt = true_or_false;	Specifies whether to use dynamic Feedback Target addresses. •The value false means each channel must have a unique Feedback Target address for Error Repair, and the VQE Server will add or remove the Feedback Target address dynamically depending on whether there is service for that channel or not. •The value true means that each channel must have a static and pre-assigned Feedback Target address for Error Repair. Default value is false.
vqm-address = "IP_address_of_VQM";	Deprecated. See vqm-host.
vqm-host = "IP_address_of_VQM";	Specifies the IP address, hostname, or fully qualified Internet domain name of the host on which the video-quality monitoring (VQM) application resides. By default, no value is configured. For information on configuring RTCP Exporter, see the "Configuring VQE-S RTCP Exporter" section on page 2-22.
vqm-port= vqm_port_no;	Specifies the TCP port number on which the VQM application listens for video quality data from RTCP Exporter. By default, no value is configured. For information on configuring RTCP Exporter, see the "Configuring VQE-S RTCP Exporter" section on page 2-22.
xmlrpc-port = xmlrpc_port_no;	Specifies the TCP port number to be used by the XML-RPC remote interface. Recommended values are greater than 1024. Default value is 8051.

Table A-4 Data Plane Process Options

Process Option	Description
group = "group_name_or_number";	Sets the group on the Interprocess Communication (IPC) interfaces to the name or a number given. Default value is "vqes". The group_name_or_number value is interpreted first as a name and, if that fails, as a number.
log-level = log_level;	Specifies the logging level of the VQE-S Data Plane process. Allowed values are 0 (Emergency) to 7 (Debugging). Default value is 4 (Warning). For information on logging levels, see the Usage Guidelines in the "Process Monitor Command-Line Options" section.
max-pkts = max_number;	Specifies the maximum number of packet buffers in the VQE-S cache manager. Allowed range is 100,000 to 1,000,000. Default value is 1,000,000.
rtp-inactivity-tmo = time_in_ms;	Specifies the timeout (in milliseconds) for received RTP streams. If no packets are received on an input channel for this amount of time, the channel is declared inactive until the next input packet is received for that stream. Allowed range is 10 to 900. The default value is 300.
setcpu = cpu_no;	Specifies the number of the CPU to which to taskset the data mover thread. The number must match a value that is included in the isolcpus parameter in the /boot/grub/grub.conf file. The setcpu value might need to be changed if the number in the isolcpus parameter changes. Allowed values are 0 to 3. The default value corresponds to the first CPU that is specified in the isolcpus parameter in the /boot/grub/grub.conf file.

Table A-5 Multicast Load Balancer Process Options

Process Option	Description
interface = "if_name[,if_name]...";	(Required) Specifies the interface names to be used by Multicast Load Balancer (MLB). Multiple interfaces should be separated by a comma without any space in between names. Allowed values are eth1, eth2, eth3, and eth4. By default, no interfaces are specified.
log-level = log_level;	Specifies the number for the logging level of the MLB process. Allowed values are 0 (Emergency) to 7 (Debugging). Default value is 4 (Warning). For information on logging levels, see the Usage Guidelines in the "Process Monitor Command-Line Options" section.
poll-interval = interval;	Specifies the MLB event polling interval in seconds. Any positive integer is allowed. Recommended value is 1 (the default).
ssm = number;	Specifies whether to allow SSM (single source multicast). The value 1 allows SSM, and the value 0 disallows SSM. Default value is 1. •When SSM is allowed, MLB tries to use IGMP v3 messages as long as the multicast routing environment is configured properly. •When SSM is disallowed or when the routing environment is not properly configured for IGMP v3, v2 messages are used.
unicast-reservation = "percent";	Specifies the percent of network bandwidth reserved for inbound Unicast Retransmission requests. Allowed range is from 0 to 100. Recommend values are between 10 and 50. Default value is 20.
xmlrpc-port = port_no;	(Required) Specifies the TCP port number to be used by the XML-RPC remote interface. Recommended values are greater than 1024. Default value is 8052.

Table A-6 STUN Server Process Options

Process Option	Description
log-level = log_level;	Specifies the number for the logging level of the STUN Server process. Allowed values are 0 (Emergency) to 7 (Debugging). Default value is 4 (Warning). For information on logging levels, see the Usage Guidelines in the "Process Monitor Command-Line Options" section.
xmlrpc-port = port_no;	(Required) Specifies the TCP port number to be used by the XML-RPC remote interface. Recommended values are greater than 1024. Default value is 8054.