** This Document is incomplete
The ET/BWMGR uses a "pluggable" protocol engine that allows users to map protocols in a flexible way. Most protocols are fixed, based on port of behavior, and many of these are not configurable. However a user can map a site to a protocol.
The base distribution includes 2 protocol files that are loaded when you first start the BWMGR software via the load protocols command:
bwmgr loadprotocols /etc/bwmgr-ports
bwmgr loadprotocols /etc/bwmgr-protocols
These 2 files contain support for about 4000 protocols. There are a few examples for tag and protocol mappings. bwmgr-ports is dedicated to mapping tcp and udp port to text protocols. You can add or modify this file in any way you like. bwmgr-protocols is designed to be user-specific protocols.
Protocols and Tags
We define Protocols loosely; it's really just a name that used to describe a traffic flow. There are certainly well-known protocols such as SMTP and HTTP. We allow you to define your own protocols, such a "porn"; the only different is that many of the most well-known protocols are hard coded into the Bandwidth Manager software. Tags are similar to protocols except that they are totally user defined. They add a layer of flexibility; and a secondary way of matching traffic that may be part of a hard-coded protocol that you can't change. You can define something as a protocol or tag using the following syntax:
protocol:PROTOCOL_NAME
tag:TAG_NAME
Not very complicated, but not very useful without the use of a selector.
Selectors
Selectors tell the engine which criteria to use to map items to a tag or protocol. Selectors available are:
ip_address IP Address agent User Agent String site Web Site or Domain server HTTP Server Specification content Content Type url URL match xheader HTTP xheader content
ip_address
The ip_address selector allows you to
Using Tags
Tags are not actually protocols; they are a marker that can be used as an alternative to a protocol. In versions before v5.0, you could only map items to protocol; version 5 adds tags to create more flexibility. Tags are aliases that allow you to create named groups using differing criteria.
Supposed you wanted to map a bunch of sites to a user-defined protocol. Lets call is adultRestricted. So you could
protocol:adultRestricted
site:playboy.com protocol:adultRestricted
site:sex.com protocol:adultRestricted
match.com protocol:adultRestricted
Internal Protocols:
Many protocols are defined internally, and you can use any internally-defined name in a rule. To get a list of available protocols, use the command:
bwmgr getprot all
This will display all of the protocols defined by the system.
User Defined Protocols: /etc/bwmgr-protocols
Users can define protocols by manipulating the /etc/bwmgr-protocols file. This file is included in your system distribution with many well-known default settings. Using the protocols file, you can define which ports should be mapped to a specific protocol. This allows you to group ports in a much more efficient manner than using groups of rules. The syntax for /etc/bwmgr-protocols is:
port tcp||udp protocol-name
so to define the protocol "myprot" on udp port 11472, you'd use:
11473 udp myprot
Now suppose that ports 11474 and 12800 also were used in this protocols, you could add the lines:
11474 udp myprot
12800 udp myprot
and now when you used the rule:
bwmgr em0 -x 5000 -addr 11.1.1.1 -ipprot myprot -bwprofile lotsabandwidth
the rule would match on ports 11473, 11474 and 12800.
The /etc/user-protocols files is the same format as the bwmgr-protocols file. Its recommended that you define your protocols in the user-protocols file, so that you can use the standard protocols that we include with each release. We'll be updating bwmgr-protocols regularly so any changes you have made with be lost if you want to use our newer file.
1000 tcp http
in bwmgr-protocols and
1000 tcp someprot
in user-protocols, port 1000 will be mapped to someprot.
Mapping Agents to Protocols
Anyone hosting a web site knows about crawlers and exploits. The ET/BWMGR allows you to "map" user agents to protocols so you can manage them more easily. Managing user agents in the BWMGR allow you to create central policies for blocking bots, crawlers and exploits without having to create complicated rules for each web site in Apache or by using .htaccess
You can create user agent protocol mappings in the file /etc/bwmgr_agents. Below is an example:
protocol goodbots bots
protocol badbots bots
# syntax
# agent protocol priority
#
mozilla http 0
googlebot goodboots 10
slurp goodbots 10
twiceler badbots 10
gecko http 5
Once you have your file with settings, run the command:
bwmgr loadagents
After running this command, datastreams with the specified user agent will be mapped to the protocol specified. The purpose of the priority is to specify the importance of the string. Take the following agent string:
Mozilla/5.0 (compatible; Yahoo! Slurp/3.0
This might be both Mozilla and Slurp, however Slurp is more specific. So you want to make sure it checks the more specific ones first. By giving Slurp a higher priority, the above agent will map to goodbots instead of http.
To see the currently defined agents, use the command:
bwmgr getagent all
Mapping URLs to Protocols
You can use the same principle describe above to map parts of urls to protocols. This is particularly useful for catching exploits on a network-wide basis.
You can create URL protocol mappings in the file /etc/bwmgr_urls. Below is an example:
protocol exploits
protocol protected
# syntax
# url protocol priority
#
phpmyadmin protected 10
=http exploits 10
passwd exploits 10
Once you have your file with settings, run the command:
bwmgr loadurls
As with agents, the priority is to specify the importance of the string.
To see the currently defined urls, use the command:
bwmgr geturl all