System Administration Guide: IP Services

Chapter 29 Starting and Maintaining IPQoS (Tasks)

This chapter contains tasks for activating an IPQoS configuration file and for logging IPQoS-related events. The following topics are covered:

Administering IPQoS (Task Map)

This section lists the set of tasks for starting and maintaining IPQoS on a Solaris system. Before you use the tasks, you must have a completed IPQoS configuration file, as described in Defining a QoS Policy in the IPQoS Configuration File (Task Map).

Task 

Description 

For Instructions 

1. Configure IPQoS on a system. 

Use the ipqosconf command to activate the IPQoS configuration file on a system.

How to Apply a New Configuration to the IPQoS Kernel Modules

2. Make the Solaris startup scripts apply the debugged IPQoS configuration file after each system boot. 

Ensure that the IPQoS configuration is applied each time the system reboots. 

How to Ensure That the IPQoS Configuration Is Applied After Each Reboot.

3. Enable syslog logging for IPQoS.

Add an entry to enable syslog logging of IPQoS messages.

How to Enable Logging of IPQoS Messages During Booting.

4. Fix any IPQoS problems that arise. 

Troubleshoot IPQoS problems by using error messages. 

Refer to the error messages in Table 29–1.

Applying an IPQoS Configuration

You activate and otherwise manipulate the IPQoS configuration by using the ipqosconf command.

ProcedureHow to Apply a New Configuration to the IPQoS Kernel Modules

You use the ipqosconf command to read the IPQoS configuration file and to configure the IPQoS modules in the UNIX kernel. The next procedure uses as an example the file /var/ipqos/Goldweb.qos, which is created in Creating IPQoS Configuration Files for Web Servers. For detailed information, refer to the ipqosconf(1M) man page.

  1. Assume the Primary Administrator role, or become superuser, on the IPQoS-enabled system.

    The Primary Administrator role includes the Primary Administrator profile. To create the role and assign the role to a user, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.

  2. Apply the new configuration.


    # /usr/sbin/ipqosconf -a/var/ipqos/Goldweb.qos
    

    ipqosconf writes the information in the specified IPQoS configuration file into the IPQoS modules in the Solaris kernel. In this example, the contents of /var/ipqos/Goldweb.qos are applied to the current Solaris kernel.


    Note –

    When you apply an IPQoS configuration file with the -a option, the actions in the file are active for the current session only.


  3. Test and debug the new IPQoS configuration.

    Use UNIX utilities to track IPQoS behavior and to gather statistics on your IPQoS implementation. This information can help you determine if the configuration operates as expected.

See Also

ProcedureHow to Ensure That the IPQoS Configuration Is Applied After Each Reboot

You must explicitly make an IPQoS configuration persistent across reboots. Otherwise, the current configuration applies only until the system reboots. When IPQoS works correctly on a system, do the following to make the configuration persistent across reboots.

  1. Assume the Primary Administrator role, or become superuser, on the IPQoS-enabled system.

    The Primary Administrator role includes the Primary Administrator profile. To create the role and assign the role to a user, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.

  2. Test for the existence of an IPQoS configuration in the kernel modules.


    # ipqosconf -l
    

    If a configuration already exists, ipqosconf displays the configuration on the screen. If you do not receive output, apply the configuration, as explained in How to Apply a New Configuration to the IPQoS Kernel Modules.

  3. Ensure that the existing IPQoS configuration is applied every time the IPQoS system reboots.


    # /usr/sbin/ipqosconf -c
    

    The -c option causes the current IPQoS configuration to be represented in the boot-time configuration file /etc/inet/ipqosinit.conf.

Enabling syslog Logging for IPQoS Messages

To record IPQoS boot-time messages, you need to modify the /etc/syslog.conf file as shown in the next procedure.

ProcedureHow to Enable Logging of IPQoS Messages During Booting

  1. Assume the Primary Administrator role, or become superuser, on the IPQoS-enabled system.

    The Primary Administrator role includes the Primary Administrator profile. To create the role and assign the role to a user, see Chapter 2, Working With the Solaris Management Console (Tasks), in System Administration Guide: Basic Administration.

  2. Open the /etc/syslog.conf file.

  3. Add the following text as the final entry in the file.


    user.info                 /var/adm/messages
    

    Use tabs rather than spaces between the columns.

    The entry logs all boot-time messages that are generated by IPQoS into the /var/adm/messages file.

  4. Reboot the system to apply the messages.


Example 29–1 IPQoS Output From /var/adm/messages

When you view /var/adm/messages after system reboot, your output might contain IPQoS logging messages that are similar to the following.


May 14 10:44:33 ipqos-14 ipqosconf: [ID 815575 user.info]
 New configuration applied.
May 14 10:44:46 ipqos-14 ipqosconf: [ID 469457 user.info] 
Current configuration saved to init file.
May 14 10:44:55 ipqos-14 ipqosconf: [ID 435810 user.info]
Configuration flushed.

You might also see IPQoS error messages that are similar to the following in your IPQoS system's /var/adm/messages file.


May 14 10:56:47 ipqos-14 ipqosconf: [ID 123217 user.error]
 Missing/Invalid config file fmt_version.
May 14 10:58:19 ipqos-14 ipqosconf: [ID 671991 user.error] 
No ipgpc action defined.

For a description of these error messages, see Table 29–1.


Troubleshooting with IPQoS Error Messages

This section contains a table of error messages that are generated by IPQoS and their possible solutions.

Table 29–1 IPQoS Error Messages

Error Message 

Description 

Solution 

Undefined action in parameter parameter-name's action action-name

In the IPQoS configuration file, the action name that you specified in parameter-name does not exist in the configuration file.

Create the action. Or, refer to a different, existing action in the parameter. 

action action-name involved in cycle

In the IPQoS configuration file, action-name is part of a cycle of actions, which is not allowed by IPQoS.

Determine the action cycle. Then remove one of the cyclical references from the IPQoS configuration file. 

Action action-name isn't referenced by any other actions

A non-ipgpc action definition is not referenced by any other defined actions in the IPQoS configuration, which is not allowed by IPQoS.

Remove the unreferenced action. Alternatively, make another action reference the currently unreferenced action. 

Missing/Invalid config file fmt_version

The format of the configuration file is not specified as the first entry of the file, which is required by IPQoS. 

Add the format version, as explained in How to Create the IPQoS Configuration File and Define Traffic Classes.

Unsupported config file format version

The format version that is specified in the configuration file is not supported by IPQoS. 

Change the format version to fmt_version 1.0, which is required to run the Solaris 9 9/02 and later versions of IPQoS.

No ipgpc action defined.

You did not define an action for the ipgpc classifier in the configuration file, which is an IPQoS requirement.

Define an action for ipgpc, as shown in How to Create the IPQoS Configuration File and Define Traffic Classes.

Can't commit a null configuration

When you ran ipqosconf -c to commit a configuration, that configuration was empty, which IPQoS does not allow.

Be sure to apply a configuration file before you attempt to commit a configuration. For instructions, see How to Apply a New Configuration to the IPQoS Kernel Modules.

Invalid CIDR mask on line line-number

In the configuration file, you used a CIDR mask as part of the IP address that is out of the valid range for IP addresses.  

Change the mask value to be in the range of 1–32 for IPv4 and 1–128 for IPv6. 

Address masks aren't allowed for host names line line-number

In the configuration file, you defined a CIDR mask for a host name, which is not allowed in IPQoS. 

Remove the mask or change the host name to an IP address. 

Invalid module name line line-number

In the configuration file, the module name that you specified in an action statement is invalid. 

Check the spelling of the module name. For a list of IPQoS modules, refer to Table 31–5.

ipgpc action has incorrect name line line-number

The name that you gave to the ipgpc action in the configuration file is not the required ipgpc.classify.

Rename the action ipgpc.classify.

Second parameter clause not supported line line-number

In the configuration file, you specified two parameter clauses for a single action, which IPQoS does not allow. 

Combine all parameters for the action into a single parameters clause. 

Duplicate named action

In the configuration file, you gave the same name to two actions. 

Rename or remove one of the actions. 

Duplicate named filter/class in action action-name

You gave the same name to two filters or two classes in the same action, which is not allowed in the IPQoS configuration file. 

Rename or remove one of the filters or classes. 

Undefined class in filter filter-name in action action-name

In the configuration file, the filter references a class that is not defined in the action. 

Create the class, or change the filter reference to an already existing class. 

Undefined action in class class-name action action-name

The class refers to an action that is not defined in the configuration file. 

Create the action, or change the reference to an already existing action. 

Invalid parameters for action action-name

In the configuration file, one of the parameters is invalid. 

For the module that is called by the named action, refer to the module entry in IPQoS Architecture and the Diffserv Model. Alternatively, you can refer to the ipqosconf(1M) man page.

Mandatory parameter missing for action action-name

You have not defined a required parameter for an action in the configuration file. 

For the module that is called by the named action, refer to the module entry in IPQoS Architecture and the Diffserv Model. Alternatively, you can refer to the ipqosconf(1M) man page.

Max number of classes reached in ipgpc

You specified more classes than are allowed in the ipgpc action of the IPQoS configuration file. The maximum number is 10007.

Review the configuration file, and remove unneeded classes. Alternatively, you can raise the maximum number of classes by adding to the /etc/system file the entry ipgpc_max_classesclass-number.

Max number of filters reached in action ipgpc

You specified more filters than are allowed in the ipgpc action of the IPQoS configuration file. The maximum number is 10007.

Review the configuration file, and remove unneeded filters. Alternatively, you can raise the maximum number of filters by adding to the /etc/system file the entry ipgpc_max_filtersfilter-number.

Invalid/missing parameters for filter filter-name in action ipgpc

In the configuration file, filter filter-name has an invalid or missing parameter.

Refer to the ipqosconf(1M) man page for the list of valid parameters.

Name not allowed to start with '!', line line-number

You began an action, filter, or class name with an exclamation mark (!), which is not allowed in the IPQoS file. 

Remove the exclamation mark, or rename the action, class, or filter. 

Name exceeds the maximum name length line line-number

You defined a name for an action, class, or filter in the configuration file that exceeds the maximum length of 23 characters. 

Give a shorter name to the action, class, or filter. 

Array declaration line line-number is invalid

In the configuration file, the array declaration for the parameter on line line-number is invalid.

For the correct syntax of the array declaration that is called by the action statement with the invalid array, refer to IPQoS Architecture and the Diffserv Model. Alternatively, refer to the ipqosconf(1M) man page.

Quoted string exceeds line, line-number

The string does not have the terminating quotation marks on the same line, which is required in the configuration file. 

Make sure that the quoted string begins and ends on the same line in the configuration file. 

Invalid value, line line-number

The value that is given on line-number of the configuration file is not supported for the parameter.

For the acceptable values for the module that is called by the action statement, refer to the module description in IPQoS Architecture and the Diffserv Model. Alternatively, you can refer to the ipqosconf(1M) man page.

Unrecognized value, line line-number

The value on line-number of the configuration file is not a supported enumeration value for its parameter.

Check that the enumeration value is correct for the parameter. For a description of the module that is called by the action statement with the unrecognized line number, refer to IPQoS Architecture and the Diffserv Model. Alternatively, you can refer to the ipqosconf(1M) man page.

Malformed value list line line-number

The enumeration that is specified on line-number of the configuration file does not conform to the specification syntax.

For correct syntax for the module that is called by the action statement with the malformed value list, refer to the module description in IPQoS Architecture and the Diffserv Model. Alternatively, you can refer to the ipqosconf(1M) man page.

Duplicate parameter line line-number

A duplicate parameter was specified on line-number, which is not allowed in the configuration file.

Remove one of the duplicate parameters. 

Invalid action name line line-number

You gave the action on line-number of the configuration file a name that uses the predefined name “continue” or “drop.”

Rename the action so that the action does not use a predefined name. 

Failed to resolve src/dst host name for filter at line line-number, ignoring filter

ipqosconf could not resolve the source or destination address that was defined for the given filter in the configuration file. Therefore, the filter is ignored.

If the filter is important, try applying the configuration at a later time. 

Incompatible address version line line-number

The IP version of the address on line-number is incompatible with the version of a previously specified IP address or ip_version parameter.

Change the two conflicting entries to be compatible. 

Action at line line-number has the same name as currently installed action, but is for a different module

You tried to change the module of an action that already exists in the system's IPQoS configuration, which is not allowed. 

Flush the current configuration before you apply the new configuration.