Chapter 5 Configuring Solaris Bandwidth Manager Using batool

The Solaris Bandwidth Manager tool, batool, provides a graphical interface for configuring the Solaris Bandwidth Manager software. This chapter describes how to use batool to configure Solaris Bandwidth Manager. Refer to Chapter 8, Statistics for information on using batool to look at statistics.

Using batool

This section describes how to start and navigate in batool and the available modes of operation.

To Start the batool Application

You can run batool as:

• An application on your local machine. You must have the SUNWbac and SUNWbat packages installed.

• An applet accessed through a browser such as HotJava^TM 1.0.1 or Netscape 4.0 or compatible versions with Java Activator plug-in. If you want to configure a remote system, you must have a web server such as Sun WebServer^TM installed on the system that is running Solaris Bandwidth Manager.

If you run batool as an application, you can configure Solaris Bandwidth Manager on a local or remote system.

1. Start the batool application by running the batool script:

   hostname% /opt/SUNWconn/ba/sbin/batool

   The application window starts and displays the batool Overview window.

To Start the batool Applet

1. As root, start the Solaris Bandwidth Manager policy agent on the system where Solaris Bandwidth Manager is installed:

   # /etc/init.d/bagent.control start

2. Create a link between /opt/SUNWconn/ba/html and a directory (badir) that is below the documentation root for your web server.

   The web server must be installed on the same machine as Solaris Bandwidth Manager.

3. On your local system, start the HotJava 1.0.1 browser and open the URL http://hostname/badir/batool.html, where hostname is the name of the system running Solaris Bandwidth Manager and badir is the directory containing the link to /opt/SUNWconn/ba/html.

Connecting to a Host System

When using batool to configure a system running Solaris Bandwidth Manager, you need to connect to the host running the Solaris Bandwidth Manager software. This applies even if the Solaris Bandwidth Manager software is installed on the local system.

To connect to the system where Solaris Bandwidth Manager is installed, select Connect from the Connection menu. The connection dialog box is displayed. Specify:

• The name of the server hosting the Solaris Bandwidth Manager software.

• The username for the server. This is the username set when the Solaris Bandwidth Manager software was installed. It is defined in the file /etc/opt/SUNWconn/ba/agent.properties.

• The password for the server. This is the password set when the Solaris Bandwidth Manager software was installed. It is defined in the file /etc/opt/SUNWconn/ba/agent.properties. You can change the password using the Change Password option of the Connection menu.

If your username and password are valid, the Overview window is displayed.

---

Note -

If you log in without specifying a username or password, you have read-only access to the configuration information.

---

Connecting to a Directory Service

If the configuration for Solaris Bandwidth Manager is stored in a directory service, you must connect to it. To do so, select Open URL from the File menu. In the Location field, type the URL of the directory you want to use.

Use the format ldap://host:port/distinguishedName. distinguishedName is the entry in the directory tree that holds the configuration information in a series of sub-entries and attributes.

The Directory configuration is opened and the application window displays the Overview window. For information on using a Directory Service with Solaris Bandwidth Manager, see Chapter 6, Configuring Solaris Bandwidth Manager with a Directory Service.

Working in Online and Offline Mode

You can configure Solaris Bandwidth Manager in online or offline mode. This mode determines how modifications to the configuration are handled. Toggle between online and offline mode using the button at the top left hand side of the tool-bar.

Modifications are not automatically saved to the configuration file. To save a file, choose Save from the File menu.

Running batool in Online Mode

Use the online mode to configure batool dynamically. If any modifications are made, the configuration for the kernel module is updated immediately. This is useful if an immediate temporary change is required because of a problem in your network. Online mode allows you to observe the consequences of a particular configuration before you save it.

---

Caution -

Care must be taken when modifying the configuration file in online mode as changes are effective immediately. For example, by reducing the bandwidth allocation to your own connection, you can disconnect yourself from the host system.

---

Running batool in Offline Mode

Use the offline mode to edit a Solaris Bandwidth Manager configuration file without disturbing the current behavior of the kernel module. This is useful if you want to make multiple changes in the configuration and have them implemented next time the policy agent is restarted. This is the default mode.

Navigating in batool

batool has a set of menus and an icon bar which you can use to navigate in the tool and make changes to the configuration.

Using the File Menu and Icon Panel

You can use the File menu to create a new configuration file, open an existing configuration file (by specifying either a filename or a URL), save a configuration file, and save a configuration file with a new name. You can also save your current configuration file and restart the Solaris Bandwidth Manager policy agent.

Alternatively, you can use the icon panel to perform most of the same functions:

Icon	Menu Item	Description
	none	Refreshes the screen display.
none	New	Creates a new configuration file, with the name new.conf.
	Open	Opens the specified file and displays its contents in the Overview window.
	Save	Saves a file. If the file has not been saved before, use the file selection window to specify a filename and directory. The file name should have the extension .conf.
none	Save As	Saves the configuration file with a new name or writes it to a Directory Service using the specified URL.
	Save and Restart	Saves the configuration file and restarts the policy agent using the saved version of the file.
none	Restart URL	Restarts the policy agent using the configuration saved in the Directory Service specified using the URL.

Using the Edit Menu and Icon Panel

You can use the Edit menu to create, cut, copy, and paste definitions in many of the windows in batool. The exact function of each option depends on the active window. For example, the paste option will paste a URL group in the URL Group window and will paste a class as child or sibling in the Classes window.

Alternatively, you can use the icon panel to perform the same functions as the Edit menu:

Icon	Menu Item	Description
	New	Creates a new definition. If you create a new class, it is added as a child of the currently selected definition. New definitions always have the name new. Change this before saving the configuration.
	Cut	Deletes a definition from the definition hierarchy.
	Copy	Adds a duplicate definition as a child of the selected destination. It inherits parameter values and a name, appended by a number, from the original definition.
	Paste	Adds the definition as a child of the selected destination.
	none	Navigate up and down the definition hierarchy

Wherever you see an instruction to use the Edit menu, you can use these icons.

Configuring Solaris Bandwidth Manager

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 number of elements. Therefore, you must create both the filter elements and the 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.

If you configure Solaris Bandwidth Manager using batool, the configuration is stored, by default, in the file /etc/opt/SUNWconn/ba/ba.conf. If you start Solaris Bandwidth Manager from batool and specify a different configuration file to be used, ba_config.location is updated automatically to contain the name of this configuration file. The name of the configuration file must be in the form *.conf.

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 uses the ba.conf configuration file. If the configuration changes while the policy agent is running, it can be re-read by the policy agent (see "Dynamic Reconfiguration").

You can also load a configuration stored in a directory service, by specifying a URL. Use the Open URL option of the File menu, and enter the URL of the directory you want to use. Use the format ldap://host:port/distinguishedName. The distinguishedName parameter is the entry in the directory tree that holds the configuration information in a series of sub-entries and attributes.

There are two ways of modifying the values of configuration parameters using batool:

• From the Overview window--double click a definition to launch its editing window. You can also use the Overview window to view summary configuration information.

• From the Configuration window--select the Configuration tab then select the definition you want to modify. The editing window for the definition is displayed.

Viewing the Configuration Overview

The Overview window displays the definitions for the current configuration in a hierarchical format. The parameters and values for each definition are displayed in the adjacent rows and can be easily modified. The Overview window is displayed by default when batool is started. Otherwise, select Overview from the tab menu to display it.

The definitions are displayed as a hierarchy from left to right, in the following order:

• Interface name

• Interface flow direction

• Class, sibling class

• Child class

Select a definition to display its parameters and values in the adjacent table.

Definitions that contain other definitions are displayed as folders.

In the table, the following interface parameters are displayed:

Bandwidth	The total available bandwidth for the interface expressed in bits per second.
Activation Mode	The level of statistics logging expressed as stats, stats & tos, stats tos & scheduling or no.
Default Class	Indicates the presence of a default class, expressed as Yes or No.
IP Transparency	Indicates the IP transparency mode, expressed as Yes or No.

In the table, the following class parameters are displayed:

Bandwidth	The bandwidth allocated to the class, expressed as a percentage.
Priority	The level of priority assigned to the class, expressed as a value between 1 and 7.
TOS Mask	The Type of Service, expressed as a value between 0 and 255.
Flow events	Indicates whether "flow added" events are generated when a new flow is detected in the class.
Filters	Click the filter cell to display the currently selected filters for the class.

You can use the Edit menu or icon bar to create, delete, move, copy, and modify these definitions.

Editing the Configuration

To display the Configuration window, click the Configuration tab. The Configuration window contains six definition windows. A tab appears for each one when you display the Configuration window. The definitions can be configured in any order but should be completed in sequence from left to right to avoid forward references to other definitions:

• Interfaces

• URL Groups

• Subnet and Host Groups

• Services

• Filters

• Classes

To display a definition window, click its tab.

Defining Interfaces

The Interface definition specifies an interface device name, its flow direction, and the bandwidth to be associated with it.

Figure 5-1 Interfaces Window

The Interface List in the left hand column displays all the currently configured interface device names. To display configuration information for an interface, click its name. The relevant parameters and values are displayed in the interface panel.

The configurable parameters are:

• Device Name.

  A new interface is created with the temporary name new. To change this name, type a new name in the Device Name field and click Apply. The device name must follow the Solaris convention of driver name, driver number, for example qe0.

  The Device Name is automatically appended with _in or _out depending on the flow direction selected.

• Bandwidth.

  This 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.

  ---

• Default Class.

  Allowed values are:

  Yes	Create a default class.
  No	There is no default class.

• Flow Direction.

  Allowed values are:

  In	The hierarchy below this interface will regulate incoming traffic only.
  Out	The hierarchy below this interface will regulate outgoing traffic only.

  Depending on your selection, the interface device name is automatically appended with _in or _out.

• IP Transparency Mode.

  Allowed values are:

  Yes	Use Solaris Bandwidth Manager in IP-transparent mode.
  No	Use Solaris Bandwidth Manager in Non-transparent mode.

  If you choose to run Solaris Bandwidth Manager in IP-transparent Mode, you must complete the additional options in the panel below:

  • Network Device.

    This is the name of the device used to communicate with the network, as opposed to the router.

  • Router Address

    This a list of IP addresses (or hostname) of the router. If you specify more than one address, separate them with a comma.

  • Multicast

    The Mulicast option defines how multicast packets are forwarded:

    None	No multicast packets are forwarded.
    All	All multicast packets are forwarded through ipqos with the exception of: Packets where the time-to live is less than 2 Packets for the local subnet, with destination addresses in the range 224.0.0.0 to 224.0.0.255 In both of these cases, they go directly to the router.
    Direct	All multicast packets are forwarded directly, not through ipqos.

  • Router MAC

    This is the MAC address of the router which can be expressed in the standard hexadecimal format.

  • SendNon-IP traffic to:

    This option defines how non-IP packets are forwarded:

    scheduler	All non-IP packets are classified and scheduled.
    router	All non-IP packets are forwarded directly, not through ipqos. These packets are not logged in the flow statistics.

• Statistics Logging.

  Allowed values are:

  Statistics	Statistics are collected on the interface, with the classifier running but not the scheduler.
  Statistics and TOS	Statistics are collected on the interface, with the Type of Service activated and the classifier running, but not the scheduler.
  Statistics and TOS and scheduler	Statistics are collected on the interface, with the classifier and scheduler running.

You can also use the Interface window to disable Solaris Bandwidth Manager. Select No in the Active panel.

Defining URL Groups

The URL Group definition is a list of one or more URLs (Uniform Resource Locator). These are typically made use of in the URL block of the Filter definition. See "Filter Definition".

Figure 5-2 URL Group Window

The URL Group list in the left hand column displays all the currently configured URL groups. To display configuration information for a particular URL group, click its name.

The configurable parameters are:

• URL Group Name.

  The name of the URL group.

• Group

  The list of URL group members.

To Add a Definition to the URL Group

1. Double-click the empty line below the last URL entry.

   The text editing mode starts, indicated by a cursor in the empty line.

2. Type the URL you want to include in the URL group. Specify the URLs in the format:

   protocol://username:password@host:port/path

   where:

   • username is the login of a user.

   • password is the password corresponding to the user login.

   • protocol is the transport protocol used, for example, http, ftp, nntp.

   • host is the host machine. You can use an asterisk (*) as a wildcard to include a particular pattern, for example, *.sun.com.

   • port is the port used. You can use an asterisk (*) to indicate any protocol. If no value is specified, 80 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.

3. Click Apply.

Configuring Host and Subnet Groups

A host or subnet group is a list of IP addresses (in dotted decimal format) or of host names that will be resolved by the systems host's database or networks table. A subnet group also contains a subnet mask.

Figure 5-3 Host and Subnet Group Window

The Group List in the left hand column displays all the currently configured Host and Subnet groups. Configurable parameters are:

• Group name

  Assign a new group name when you create the group.

• Group Type

  This can be either Host or Subnet

• Address List

  The list of addresses that compose the group.

• Subnet mask

  The subnet mask. This is only required for a subnet group. This must be expressed in IP dotted notation or as a name that can be resolved by the system's host table.

To add an address to a host or subnet group:

1. From the Group List, select the group you want to add an address to.

   The addresses currently contained in the group are displayed in the adjacent address list panel.

2. In the Address List panel, double-click in the empty line below the last address entry.

   The text editing mode starts, indicated by a cursor in the empty line.

3. Type the address you want to include in the group.

   The address can be specified as a hostname or IP address.

4. Click Apply.

   The address is added to the group.

Defining Services

A service definition provides a mapping between a service defined in application layer terms and the protocol and ports used. A number of services are pre-defined in the file /opt/SUNWconn/ba/lib/services.def. You do not need to carry out any configuration to use these services. "Configuration Examples" shows the pre-defined classes.

Figure 5-4 Services Window

The Services Lists in the left hand column display all the currently configured services. The configurable parameters for user defined services are:

• Service Name

  New services are created with the temporary name new. To change this name, type a new name in the Service Name field and click Apply.

• Protocol

  Choose one of TCP, UDP, Other, or Any.

• Local and Remote Port.

• Other

  Specify the protocol you want to use here.

  You need only complete this field if you specified Other in the Protocol field.

To add port information:

1. From the Services List, select the service you want to add port information to. The service is highlighted. The ports currently used by the service are displayed in the TCP/UDP panel.

2. In the TCP/ UDP panel, double-click in the empty line below the last address entry. Complete both the Local and Remote port columns.

   The text editing mode starts, indicated by a cursor in the empty line.

3. Type the ports you want to include in the Service.

   Use an asterisk (*) to indicate any port.

4. Click Apply.

   The port information is added to the service.

Defining Filters

The filter definition 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.

Figure 5-5 Filters Window

The Filter List in the left hand column displays all the currently configured Filters. The configurable parameters are:

• Filter Name

  New filters are created with the temporary name new. To change this name, type a new name in the Filter Name field and click Apply.

• TOS

  In the TOS field, type the Type of Service value. This must be a value between 0 and 255.

• Matching mask

  This value specifies which bits will match the Type of Service value in the IP header with the Type of Service value. This must be specified as a bitmask.

• Remote and local network entity types.

  Specify the remote and local network entity types. For each type, a different name field is displayed:

  Host	Complete the Host Name field. This value can be expressed as a domain name or IP address.
  Host Group	Complete the Host Group Name field with a Host Group name defined in the Host and Subnet Groups window. To define a new Host Group, click Create. This starts the Host and Subnet Groups window.
  Subnet	Complete the Subnet Name field with a Host name or IP address. Complete the Subnet Mask field with a subnet mask.
  Subnet Group	Complete the Subnet Group Name field with a Subnet Group name defined in the Host and Subnet Groups window. To define a new Subnet Group, click Create. This starts the Host and Subnet Groups window.

• Service

  The available services are displayed in the drop-down menu. To define a new service in the Services window, click Create.

• URL

  From the local panel, select Single URL or URL Group. A different name field is displayed for each selection:

  Single URL	Complete the Single URL field. Specify the URL in the format protocol://username:password@host:port/path.
  URL Group	Complete the Group Name field with a URL group name defined in the URL Group window.   To define a new URL Group, click Create. This starts the URL Group window.

Defining Classes

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

Figure 5-6 Classes Window

The classes are displayed as an expandable tree structure in the Class Tree, together with the interface name and the flow direction. Classes that contain other classes are displayed as folders.

The definitions are presented as a hierarchy, from left to right, in the following order:

• Interface name

• Interface flow direction

• Class, sibling class

• Child class

The parameters and values for each class are displayed in the adjacent class panel.

New classes are added as a child or sibling of the currently selected class. Use the Edit menu to choose which. A new class is created with the temporary name new. To change this name, type a new name in the Class Name field and click Apply.

The configurable parameters for a class are:

• Bandwidth

  You can specify this as a percentage or in bits per second. You can also specify that this class is not allocated any bandwidth by choosing Deny Access.

• Priority

  This must be a value between 1 (highest priority) and 7 (lowest priority).

• Type of Service (TOS)

  This must be a value between 0 and 255.

• Match bits

  This value specifies which Type of Service bits in the IP header will be modified with the Type of Service value. This must be specified as a bitmask.

• Borrow bandwidth

  If you select Yes, complete the Max % field with the maximum bandwidth the class is allowed to borrow.

• Directory request

  If you select Yes, complete the Flow Event field with the flow events to be generated when a new flow is detected in the class. For more information on Flows, see "Flows".

• Filter

  This determines what network traffic will be allocated to this class. If you do not specify any filters, no traffic is allocated. To create a new filter, click Create.

Configuration Example

This section contains an overview of the procedure for creating a Solaris Bandwidth Manager configuration using batool. The configuration in this chapter is that defined for the Paris site in "Configuration Planning Example".

In Solaris Bandwidth Manager, traffic is allocated bandwidth on the basis of the class to which it belongs. Classes are defined in terms of filters, and filters are defined in terms of URL groups, host and subnet groups, and services. You must also define the interface(s) running Solaris Bandwidth Manager. To configure Solaris Bandwidth Manager:

1. Define the interface running Solaris Bandwidth Manager.

2. Define the information that will be used to create filters.

3. Create filters.

4. Create classes.

You can define an interface at any time. You can only define a class in terms of filters that already exist, and you can only define a filter based on information that you have already defined. Therefore, when using batool, work from left to right.

Before you can create a new configuration file, you must:

1. Start the batool application by running the batool script:

   /opt/SUNWconn/ba/sbin/batool

2. Create a new configuration file. To do this, select New from the File menu. This creates a configuration file called new.conf with undefined parameter values.

3. Display the configuration window. Click the Configuration tab.

Defining Interfaces

The example system requires two interfaces: one to handle outgoing traffic and one to handle incoming traffic.

Define qe0_out to handle outgoing traffic like this:

1. Change the default device name new0 to the name of the interface, in this case qe0. Do not append _out; this is done automatically for you.

2. Specify the bandwidth for this interface, in this case 1000000 bits per second.

3. Specify that there is a default class for this interface, that the direction of traffic handled is out, and that the interface is not IP transparent.

4. Specify the level of activation for the interface, statistics, TOS, and scheduling.

5. Click Apply, then choose Save from the File menu to save your changes.

The filled in window looks like this:

Creating Filter Components

A Solaris Bandwidth Manager filter is defined using URL, host and subnet groups, and services. You must define these before you create filters. The example configuration requires 3 subnet groups, one each for the Paris, Bonn, and London networks. It also requires services to handle the following protocols: http, telnet, snmp, smtp, imap, and ftp. However, as these services are all preconfigured, you do not need to create them. It does not require any URL groups or any host groups.

Creating a Subnet Group

Using Solaris Bandwidth Manager, you can classify traffic based on the source or destination IP address of an individual machine. If you want to classify all of the traffic from a given network or group of networks, a convenient way to do this is to create a subnet group.

To create a subnet group for the Bonn site

1. Display the Host/Subnet Groups configuration window by clicking the Host/Subnet Groups tab.

2. Click the new icon to create a new group.

3. Allocate a name to the group by changing the default name new.

4. Specify that the group type is Subnet.

5. Specify the list of subnets that belong to the Bonn site. To do this, click the top left of the Addresses pane -- this creates an editable field where you can type an address. After entering an address, click Apply. This records the address you just entered and makes the line below writable for your next entry. Specify subnet addresses in standard IP dotted notation.

6. Specify the subnet mask for these addresses.

7. Click Apply. Then choose Save from the File menu to save your changes.

You could also use a host group for the same purpose, but you would have to enter the IP address of each host at the Bonn site separately.

Creating Filters

Filters are used by Solaris Bandwidth Manager to put traffic into classes. They are defined using host, subnet, and URL groups and services.

For example, to create a filter http:

1. Click the Filters tab to display the Filters window.

2. Click the new icon to create a new filter.

3. Assign a name to the filter by overtyping new in the Filter Name field.

4. Specify that this filter applies to http traffic. Use the pull-down menu in the service pane to choose http.

5. Click Apply.

6. Choose Save from the File menu to save your changes.

The completed http filter looks like this:

To create a filter any_bonn:

1. Click the new icon to create a new filter.

2. Assign a name to the filter, by overtyping new in the Filter Name field.

3. Specify that this filter applies to traffic for Bonn. In the remote pane, click beside Subnet Group. Then use the pull-down menu to choose the subnet group bonn.

4. Click Apply.

5. Choose Save from the File menu to save your changes.

The completed any_bonn filter looks like this:

Creating Classes

Once you have created all the filters you require, you can create classes using them. When you open the Classes window (click the Classes tab) there is a navigation pane on the left hand side of the window. The class qe0 already exists. This represents the interface you configured earlier. The expanded class hierarchy looks like this:

Note that a default class has been created automatically for each interface, as you specified when creating the interface that there would be a default class.

To create the class http as a child of the Out class:

1. Click to highlight the Out class in the navigation window. A new class is always created as a child of the highlit class.

2. Click the new icon to create a new class.

3. Assign a name, for example http, to the new class.

4. Specify the percentage of bandwidth to be allocated to the new class (20%) and the priority (5) it should be given.

5. From the list of available filters, choose the filter(s) that define this class and add them to the selected filters list.

6. Click Apply.

7. Choose Save from the File menu.

The completed new class looks like this: