Solaris Bandwidth Manager 1.5 Administration Guide

Configuration File Format

The Solaris Bandwidth Manager configuration file contains general configuration parameters and a number of definitions used to allocate bandwidth to network traffic. These definitions can be included in any order, but forward references to other definitions are not permitted.

The file contains definitions for the following items:

URL group
Host group
Subnet group
Service
Filter
Interface
Class

A definition is terminated by the keyword indicating the start of the next definition or by the end of the file. Within a definition there is a series of keywords and their values. Class names and filter names must not exceed 20 characters.

Some keywords can take only one value but can be present more than once in a subsection. Other keywords can take more than one value, in a list separated by commas. A value cannot contain a comma. If the list of values for a keyword continues over more than one line, use a backslash (\) as a continuation character. A value can contain a backslash, unless the backslash is the last character in the line, in which case it is treated as a continuation character.

You can include comment lines, starting with a pound sign (#). All lines starting with a hash sign are treated as comments, however, a value can contain a hash sign. Within a comment line, any characters are permitted.

You must be root in order to edit this file.

General Configuration Parameters

The configuration file contains the following general parameters:

timeout seconds -- Indicates a time limit after which dynamic classes and filters are removed if no traffic is classified in them. The default value is 30 seconds. If a value of 0 is specified, the dynamic classes and filters are never removed.
version --Indicates the version of the product in use. In this case 1.5.

URL Group Definition

A URL group definition is a list of one or more URLs (Uniform Resource Locator).

Format

url_group   name
                     url   url_address

name is the name of the URL group.
url_address is a URL-based filter, specified as protocol://username:password@host:port/path where:
- protocol is the transport protocol used. For example, http, ftp, nntp. If no value is specifed, http is used. You can use an asterisk (*) as a wildcard to specify any protocol.
- username is the login used to connect to the remote server. Use of a username is optional. You can use an asterisk (*) as a wildcard to specify any username.
- password is the password corresponding to the user login. Use of a password is optional. You can use an asterisk (*) as a wildcard to specify any password. The password is ignored for classification purposes.
- host is the web server. The value of this filter can be an IP address, host name or domain name. You can use an asterisk (*) as a wildcard to specify any host.
- port is the port number. You can use an asterisk (*) to indicate any protocol. If no value is specifed, the default protocol specified in the /etc/services file is used.
- path is the path of the URL. You can use an asterisk (*) as a wildcard to include a particular pattern, for example, *.htm. You cannot include more than one asterisk in a path.

The following characters are restricted, and must be entered as an ascii code, preceded by a percent (%) sign:

character	ascii code
%	25
@	40
:	3A
,	2C
#	23

The / character can only be used as part of a path.

Example

url_group   web_sun_group
            url   http://www.sun.com/*.html
            url   http://www.sun.com/*.gif
            url   http://*:8080/~mylogin
            url   ftp://ftp.sun.com/*

Host Group Definition

A host group is a list of IP addresses (in dot format) or host names that will be resolved by the host's database on the system where Solaris Bandwidth Manager is running.

Format

host_group   name
             address   address_list

name is the name of the host group.

address_list is the list of hosts to be included in this group.

Example

host_group   grp_sales
             address   134.xxx.yyy.1, 134.xxx.yyy.2
host_group   grp_paris
             address   125.xxx.yyy.1, 125.xxx.yyy.2, apple, pear,\
                       orange

Subnet Group Definition

A subnet group is a list of IP addresses (in dot format) or network names that will be resolved by the host's database of the system running Solaris Bandwidth Manager or by the networks table. A subnet group also contains a subnet mask.

Format

subnet_group   name
               address   address_list
               mask      subnet_mask

name is the name of the subnet group.

address_list is the list of networks to be included in this group. If entered as names, networks listed must be defined in the /etc/hosts file or the /etc/networks file.

subnet_mask is the subnet mask in dot format. You cannot use the + style of specifying a netmask.

Example

subnet_group   grp_nets
               address   129.xxx.yyy.0, plum
               mask      225.225.225.0

Service Definition

A service definition provides a mapping between a service defined in application layer terms and the protocol and ports used. This includes control protocols such as PIM, RSVP, and IGMP. A number of services are pre-defined in the file /opt/SUNWconn/ba/lib/services.def. "Complete Configuration" shows the pre-defined services.

Format

service   name
          protocol   protocol
          ports      local_port,remote_port

name is the name of the service
protocol can be either the ANY keyword or any protocol defined in the /etc/protocols file.
local_port and remote_port are the source and destination ports used by the service, separated by a comma. Use an asterisk (*) to indicate any port. You can specify any number of ports keywords and pairs of ports.

Note -
To avoid confusion, the adjectives local and remote refer to the same servers or ports regardless of the direction of the traffic. local refers to the server on which Solaris Bandwidth Manager resides, and remote is the rest of the network. In the case of an IP transparent configuration of Solaris Bandwidth Manager, local refers to the LAN-side, and remote refers to the WAN-side.

Example

service   tv
          protocol   tcp
          ports      2023,*
          ports      2024,*
          ports      *,2023
          ports      *,2024

Filter Definition

A filter contains local and remote information and a service, and is used to determine the class of a packet. It can also contain URL information and a Type of Service value.

Format

filter   name
         local
                         type      type
                         local_info
         remote
                         type      type
                         remote_info
         url
                         type      urltype
                         url_info
        tos_match        tos_match
        tos_match_mask   tos_match_mask
        service          service

name is the name of the filter. This value can contain up to 20 characters.
type is the type of information identifying the local or remote network entity and is one of:
- host
- host_group
- subnet
- subnet_group
local_info and remote_info are specific local and remote network entity information. The convention for what is local and what is remote is the same as for the service definitions. The format depends on the value of type:
- If type is host, specify the keyword address and the IP address or name of the host.
- If type is host_group, specify the keyword name and the name of a host group that is defined earlier in the configuration file.
- If type is subnet, specify the keyword mask and the subnet mask (in decimal dot format only), and specify the keyword address and the IP address or name of the network.
- If type is subnet_group, specify the keyword name and the name of a subnet group that is defined earlier in the configuration file.
urltype is the type of information identifying the url setting and is one of:
- url
- url_group
url_info is specific URL information. The format depends on the value of urltype:
- If urltype is url, specify the keyword address and the URL in the format protocol://username:password@host:port/path.
- If urltype is url_group, specify the keyword name and the name of a url group that is defined earlier in the configuration file.
tos_match is the Type of Service value specified as a value between 0-255. This value can be specified as a hexadecimal, decimal or octal value. Refer to "Type of Service Values" for further information. Prefix hexadecimal values with 0x and octal with 0.
tos_match_mask is a bit mask that specifies which bits will match the Type of Service value in the IP header with the tos_match. Refer to "Type of Service Values" for further information.
service is the name of the service or services. To specify any service, do not specify the service keyword.

Examples

filter   filter1
         local
                         type      host
                         address   apricot
         remote
                         type      host_group
                         name      grp_sales
         tos_match       0x03
         tos_match_mask  0x0F
         service         ftp,http
filter   filter2
         local
                         type      subnet_group
                         name      grp_nets
         remote
                         type      subnet
                         address   129.xxx.yyy.0
                         mask      255.255.255.0
         url
                         type      url_group
                         name      web_sun_group
         service         http

Interface Definition

An interface definition specifies a Solaris device name, its flow direction, and the bandwidth to be associated with it.

Format

interface   name
            rate         bandwidth
            activate     status
            router_addr  router_addr
            router_mac   router_mac
            network      network_device
            multicast    multicast
            nonip_mode   non_ipmode

name is the device name, and is followed by a suffix:
- _out indicates that the hierarchy below this interface will regulate outgoing traffic only. This is the default if no suffix is specified.
- _in indicates that the hierarchy below this interface will regulate incoming traffic only.
bandwidth is the operating bandwidth rate associated with the device, in bits per second. This value need not necessarily be the maximum of which the device is capable. The value should not exceed the device's maximum.

Note -
Consider the actual operating rate of the device, rather than the nominal rate when determining the value of the bandwidth rate.
status indicates the status of the interface with respect to Solaris Bandwidth Manager and is one of:
- enabled indicates that the classifier and scheduler are running. Bandwidth allocation is used on the interface and statistics are collected. This is the default value.
- tos indicates that the classifier is running but not the scheduler. Statistics are collected, and the TOS is activated. In this mode, the TOS is used in classes for marking.
- stats indicates that the classifier is running but not the scheduler. Statistics are collected.
- disabled indicates that bandwidth allocation is not used on the interface.

IP-Transparent Mode

If you are using Solaris Bandwidth Manager in IP-Transparent mode, you must specify the router_addr, network and router_mac keywords.

router_address is the list of IP addresses (or the hostname) of the router. If you specify more than one address, separate them with a comma.
network_device is the name of the device connected to the LAN.
router_mac is the MAC address of the router. This can be expressed in the standard hexadecimal format or as a hostname referenced in the ethers table.

The following parameters are optional in IP-Transparent mode:

multicast defines how multicast packets are forwarded:
- none indicates that no multicast packets are forwarded.
- all indicates that all multicast packets are forwarded through ipqos (unless the time-to-live is less than 2 or the packets are local subnet traffic with destination addresses in the range 224.0.0.0 to 224.0.0.255, in which case they go directly to the router).
- direct indicates that all multicast packets are forwarded directly, not though ipqos.
See "Multicast Routing and Solaris Bandwidth Manager" for more information about how Solaris Bandwidth Manager handles multicast traffic.
nonip_mode defines how non-IP packets are forwarded:
- ipqos indicates that all non-IP packets are classified and scheduled.
- direct indicates that all non-IP packets are forwarded directly, not through ipqos. These packets are not logged in the statistics.

Example

interface   qe0_out
            rate         512000
            activate     enabled
            router_addr  134.xxx.yyy.3
            router_mac   809xxxxx
            network      le0
            multicast    all
            nonip_mode   ipqos

Class Definition

A class definition contains the parameters for the class, including the filters that cause packets to be placed in this class.

Format

class   name
        parent             parent_class
        interface          interface
        bandwidth          bandwidth
        max_bandwidth      max_bandwidth
        priority           priority
        bandwidth_bps      bandwidth_bps
        max_bandwidth_bps  max_bandwidth_bps
        tos_mark           tos_mark
        tos_mark_mask      tos_mark_mask
        flow_events        flow_events
        filter             filter

name is the name of the class. This must be unique for the specified interface. If you want this class to act as the default class, its name must be default.
parent_class is the name of the class above this class in the hierarchy.
interface is the name of the interface used by traffic in this class.
bandwidth is the percentage of the bandwidth of the interface that is allocated to the class. Use either this parameter or bandwidth_bps.
max_bandwidth is the maximum percentage of bandwidth this class can use, including bandwidth borrowed from its parent class. Use either this parameter or max_bandwidth_bps.
priority is the priority of the class. Specify an integer from 1 (highest priority) to 7 (lowest priority).
bandwidth_bps is the absolute bandwidth in bits per second that is allocated to the class. Use either this parameter, or bandwidth.
max_bandwidth_bps is the absolute maximum bandwidth in bits per second that this class can use, including bandwidth borrowed from its parent class. Use either this parameter, or max_bandwidth.
tos_mark is the Type of Service specified as a value between 0-255. It overwrites the existing value in classified packets in this class. Refer to "Type of Service Values" for further information.
tos_mark_mask is a bit mask that specifies which Type of Service bits in the IP header are modified with the tos_mark. Refer to "Type of Service Values" for further information.
flow_events indicates that "flow added" events are generated when a new flow is detected in the class. There are no semantics associated with the value of this keyword. To disable flow added events, remove this line from the file.
filter is the name of a filter that allocates packets to this class. You can specify more than one filter, in a comma-separated list.

Example

class   test_class
        parent             root
        interface          qe0_out
        bandwidth          35
        max_bandwidth      45
        priority           3
        tos_mark           0x07
        tos_mark_mask      0x0F
        flow_events        ip_source
        filter             filter1,filter2

Type of Service Values

Solaris Bandwidth Manager uses the TOS byte in the following ways:

In filters, as a classification criterion
In classes, where it defines how the TOS byte must be overwritten

Table 4-1 Type of Service Values and Their Meanings


1000	minimize delay
0100	maximize throughput
0010	maximize reliability
0001	minimize monetary cost
0000	normal service

The classification criterion in filters is defined by the tos_match and the tos_match_mask parameters. tos_match_mask is a bitmask that defines which bits of the TOS byte need to be checked. tos_match is the value to check.

For example, to filter all packets whose TOS byte is "minimize delay" and "normal service" (xxx 1xx0 x): tos_match_mask must be set to 000 1001 0 (0x12), and tos_match must be set to 000 1000 0 (0x10).

In classes, the following parameters are used: tos_mark_mask, and tos_mark. tos_mark_mask is a bitmask defining which bits to modify in the TOS byte, and tos_mark is the value to apply.