Chapter 4 Editing the Configuration Files

This chapter decribes how to edit the Solaris Bandwidth Manager configuration files directly, using a text editor. To edit the configuration files using batool, see Chapter 5, Configuring Solaris Bandwidth Manager Using batool.

The following definitions are specified in the main Solaris Bandwidth Manager configuration file:

• A timeout value,

• The interfaces where traffic is to be controlled by Solaris Bandwidth Manager.

• The filters used to assign traffic to a class. For each filter, you need to define:

  • The service, or traffic type

  • The URL or URL group

  • Local entity information, in terms of hosts, host groups, or subnets

  • Remote entity information, in terms of hosts, host groups, or subnets.

• The classes to which traffic is to be allocated, their priorities, and the amount of bandwidth allocated.

Each definition contains both mandatory and optional parameters, which can be edited to suit your configuration requirements.

You can also edit the agent properties file, if neccessary for your configuration.

You must log into the machine running Solaris Bandwidth Manager as root or become superuser in order to carry out any configuration.

Configuration Overview

To configure Solaris Bandwidth Manager you must create a group of classes that will be used to determine how network traffic is handled. Classes are defined in terms of the filters that are used to allocate traffic to a particular class, and filters are composed of a a number of elements. Therefore, you must create both the filter elements and filters you require before you can create classes. All classes are assigned to a particular physical interface, so you must also define the interface(s) that you want to use in your configuration.

The Solaris Bandwidth Manager configuration file cannot contain forward references, so you must configure the definitions in the following order:

• Filter elements:

  • URL groups

  • Host groups

  • Subnet groups

  • Services

• Filters

• Interfaces

• Classes.

The rest of this chapter describes the files and directories used to hold configuration information, and explains how to specify the configuration you want by editing the files directly.

Configuration Files and Directories

The file /etc/opt/SUNWconn/ba/ba_config.location indicates the location of the configuration file currently being used. This can be done by specifying:

• A file name -- by default, the configuration file is stored in the directory/etc/opt/SUNWconn/ba

• A full pathname -- this is useful if you do not store the configuration file in the default location

• A URL, if the configuration is stored in a Directory Service

When the Solaris Bandwidth Manager policy agent starts, it reads the file named in ba_config.location. If ba_config.location does not exist or cannot be read, the policy agent assumes that the configuration file is ba.conf. If the configuration changes while the policy agent is running, it can be re-read by the policy agent (see "Dynamic Reconfiguration").

The directory /etc/opt/SUNWconn/ba also contains the following files:

• ba_config.location-sample -- The template for the ba_config.location file

• ba.conf-sample -- A sample configuration file

• agent.properties-- A file configuring the properties of the policy agent

• agent.properties-sample -- A sample file containing policy agent properties

• autopush.ba-sample -- The template for the autopush.ba and autopush_usr.ba files. These files are used to insert ipqos between IP and the interface drivers.

  • Use the autopush.ba file to specify interface drivers located in the /kernel/drv directory.

  • Use the autopush_usr.ba file to specify interface drivers located in the /usr/kernel/drv directory.

  When you configure an interface in Solaris Bandwidth Manager, the relevant changes are made to the autopush.ba and autopush_usr.ba files when you try to reload the new configuration. You must then reboot your system for the changes to take effect. Do not change autopush.ba-sample

• /etc/default/ba_info -- A script that sets the environment variables needed by the Solaris Bandwidth Manager software. If you do not install Solaris Bandwidth Manager in the default location, edit this file and specify the correct values for BACONFIGFILES and BAHOME.

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:

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

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.

Agent Properties File Format

To edit the agent properties file, you require root access to the system running Solaris Bandwidth Manager. The file is called agent.properties, and is located in the /etc/opt/SUNWconn/ba directory. The parameters it contains are:

• login--An authentication login name for batool and Java clients. If no login is configured, users have read-only access.

• password--An authentication password.

• agentPort--Port number for the agent. The default value is 6969, but it can be overridden here to avoid conflicts with other products.

• dirPort--Port number for the LDAP replication slave. The default value is 389.

• lightweight --This can be one of true or false. With lightweight mode enabled, the policy agent is started in a special resource-saving mode. In this mode, all the features of the policy agent such as connection from the tool, restart operations, and SNMP monitoring are disabled, except the transmission of NetFlow packets. By default, lightweight mode is disabled.

• netFlowHost--Specifies the host to which flow accounting information will be sent using the NetFlow protocol . By default, NetFlow packets are not sent. The NetFlow host can be specified as a hostname or an IP address in decimal dot notation.

• netFlowPort--Specifies the UDP port number to which NetFlow packets will be sent. This is used only if netFlowHost is specified. The default value is 9991.

Configuration Examples

This section contains some examples of configuration files, based on the "Configuration Planning Example".

• "IP-Transparent Mode Interface Configuration" shows an IP-transparent configuration.

• "Server Mode Interface Configuration" shows the configurations for two interfaces, each configured in server mode.

• "Logical Interfaces" shows the configuration for one interface that is configured as one logical interface at the IP level, using classes to divide the traffic by subnet.

• "Complete Configuration" shows a complete configuration for the Paris site, including the standard service definitions.

IP-Transparent Mode Interface Configuration

Figure 4-1 IP-Transparent Configuration at London Site

In IP-transparent mode, the host running Solaris Bandwidth Manager sits between the traffic source (usually a LAN) and the router. On the host shown in Figure 4-1, you configure the qe1_out interface for Solaris Bandwidth Manager, giving le0 as the network device. For example:

interface   qe0_out
            rate          512000
            activate      enabled
            router_addr   123.xxx.yyy.1
            network       le0
            router_mac    809xxxxx
            multicast     all

In addition to the configuration shown above, you must configure a standard IP interface for the network interface to the LAN. This is necessary for the interface to be inserted into the IP stack at boot time. Create the file /etc/hostname.interfacename with a reference to the IP address of the interface.

Do not configure the network interface on the WAN side. Run ifconfig -a and check that there is no reference to this interface.

Server Mode Interface Configuration

Figure 4-2 Interfaces Configuration at Paris Site

In this example, the host running Solaris Bandwidth Manager is acting as a router and there are two interfaces. le0 is the interface used when sending network traffic to London, and ipdptp1 is a PPP interface used when sending network traffic to Bonn. The configurations for both interfaces are normal server mode configurations. For example:

interface   le0_out
            rate       263144
            activate   enabled
interface   ipdptp1_in
            rate       65536
            activate   enabled

Logical Interfaces

Figure 4-3 Configuring Logical Interfaces

Solaris Bandwidth Manager operates at the level of the physical interface (le0) and does not recognize logical interfaces (le0:1 and le0:2, for example). If your IP configuration includes logical interfaces, you can use the class hierarchy to subdivide network traffic according to the destination subnet, and then manage the traffic for each subnet separately. Figure 4-3 shows a configuration with two logical interfaces. The configuration file contains a definition for the le0 interface, and filter and class definitions for the subnet1 and subnet2 classes. For example:

filter    subnet1
          remote
                   type            subnet
                   address         123.xxx.yyy.0
                   mask            255.255.255.0

filter    subnet2
          remote
                   type            subnet
                   address         123.xxx.zzz.0
                   mask            255.255.255.0

interface le0
                   rate            263144
                   activate        enabled

class     subnet1
                   parent          root
                   interface       le0_in
                   bandwidth       60
                   priority        3
                   max_bandwidth   100
                   filter          subnet1

class     subnet2
                   parent          root
                   interface       le0_in
                   bandwidth       40
                   priority        3
                   max_bandwidth   100
                   filter          subnet2                  

Complete Configuration

The following file implements the configuration described for the Paris server in "Configuration Planning Example". Note that two filters, imap and smtp, have been used to define the class email.

# Sample configuration file for Paris site



version 1.5
timeout 30

#Subnet Group definitions

subnet_group bonn
        address         129.xxx.xxx, 129.xxx.yyy
        mask            225.225.225.0

subnet_group paris
        address         129.yyy.xxx, 129.yyy.yyy, 129.yyy.zzz
        mask            225.225.225.0

subnet_group london
        address         129.zzz.xxx, 129.zzz.yyy
        mask            225.225.225.0

#Filter definitions

filter http_to_london
        local
                type    subnet_group
                name    paris
        remote
                type    subnet_group
                name    london
        service         http

filter telnet
        service         telnet

filter imap
        service         imap

filter http_to_bonn
        local
                type    subnet_group
                name    paris
        remote
                type    subnet_group
                name    bonn
        service         http
filter snmp
        service         snmp

filter http
        service         http

filter ftp
        service         ftp

filter smtp
        service         smtp

#Interface defintions for qe0_out

interface qe0_out
        rate            128000
        activate        enabled


#Class definitions for interface qe0_out

class ftp
        interface       qe0_out
        parent          root
        filter          ftp
        bandwidth       15
        priority        7
        max_bandwidth   15

class email
        interface       qe0_out
        parent          root
        filter          imap, smtp
        bandwidth       20
        priority        7
        max_bandwidth   20

class snmp
        interface       qe0_out
        parent          root
        filter          telnet
        bandwidth       5
        priority        1
        max_bandwidth   5

class telnet
        interface       qe0_out
        parent          root
        filter          telnet
        bandwidth       30
        priority        1
        max_bandwidth   30

class http
        interface       qe0_out
        parent          root
        filter          http
        bandwidth       20
        priority        5
        max_bandwidth   20

class http_bonn
        interface       qe0_out
        parent          http
        filter          http_to_bonn
        bandwidth       5
        priority        3
        max_bandwidth   5

class http_london
        interface       qe0_out
        parent          http
        filter          http_to_london
        bandwidth       10
        priority        3
        max_bandwidth   10

class default
        interface       qe0_out
        bandwidth       0
        priority        7
        max_bandwidth   0

#Interface definition for qe0_in

interface qe0_in
        rate            0
        activate        enabled

#Class definition for interface qe0_in

class default
        interface       qe0_in
        bandwidth       0
        priority        7
        max_bandwidth   0