Oct 6th, 2012
First Posted
Oct 6th, 2012

ET/BWMGR v5.0 CLI Manual

This document describes the ET/BWMGR v5.0 Command Line Interface (CLI)


The basic syntax of the bwmgr utility is

bwmgr interface -x INDEX [ criteria ] [ bandwidth controls ]

There are many options for adding rules. Typical syntax for a basic rule is:

bwmgr igb0 -x 500 -addr -bwprofile default

This simple syntax sets a rule to use the default bandwidth profile on address You can also specify the specific controls:

bwmgr igb0 -x 500 -addr -bwin 512000 -bwout 512000 -bwburst 2048000 -bursttrig 4mbTrigger

For a full description, see the section titled Adding Rules.


Add a protocol definition

The bulk of your protocol definitions should be included in your protocols files and installed with the loadprotocols command. You can add a protocol definition manually with this function. Note that changes made with this function will not be sustained across a reboot.

# bwmgr add_protocol protocol ARG port ARG ipprot ARG disable ARG ip_address ARG site ARG agent ARG url ARG server ARG xheader ARG group ARG tag ARG -remove


bwmgr add_protocol site facebook.com tag facebook

Creates a mapping for traffic going to facebook to the tag facebook.

bwmgr ipprot tcp port 23 protocol telnet

maps TCP port 23 to telnet


Analyze your rules on an interface

bwmgr INTERFACE analyze

# bwmgr em0 analyze
stdClass Object
[firewall_global] => 7
[firewall_indexed] => 12
[firewall_worst] => 9
[bandwidth_global] => 5
[bandwidth_indexed] => 57
[bandwidth_worst] => 8
[cmd] => analyze

The above shows an analysis of rules on em0. The "global" rules are rules that must be checked for every packet; typically rules that do not have an indexed element such as an IP address. "indexed" is the number of rules that are indexed. "worst" shows the worst case, which is the global plus the maximum search depth for an index; ie the number of match tests that are necessary for the worst case.

Keeping the worst case number down will increase the efficiency of the bandwidth management device.


Add an interface to an existing bridge

# bwmgr BRIDGE bridge addif INTERFACE ff learning


bwmgr bridge0 createbridge
bwmgr bridge0 bridge addif em0
bwmgr bridge0 bridge addif em0

Adds em0 and em1 to the bridge named bridge0


Create a bridge. Specify ADDRESS to set the bridge MAC address

# bwmgr INTERFACE createbridge [address]


Clear hit and drop counts for a rule or group. Specify interface and rule number, or rule name.

# bwmgr INTERFACE clearcounters -x 200
# bwmgr clearcounters name RULE_NAME


Delete a a rule

# bwmgr [INTERFACE] delrule index


bwmgr em0 delrule 300


Disable a rule

# bwmgr em0 -x index disable

# bwmgr em0 -name AcmeWidgets disable

This command sets a flag which disables the rule from "hitting."


Enable a disabled rule

# bwmgr em0 -x index enable

# bwmgr em0 -name AcmeWidgets enable

Note that this command simply removes the disable flag from a disabled rule and has no effect on rules that are not disabled.


Clear all rules (or firewall rules) from an interface

# bwmgr INTERFACE flush fw all


Clear entries from the database

# bwmgr flushdb


Show the bridge settings and members

# bwmgr getbridges

The following is typical output from a failover appliance, such as the ET/R2400 or ET/R2800.

# bwmgr getbridges

stdClass Object
[bridge0] => stdClass Object
[address] => 02:62:cc:d1:76:00
[members] => stdClass Object
[em3] => stdClass Object
[ff] => 1

[em2] => stdClass Object
[ff] => 1



[cmd] => getbridges


Show the list of ethernet interfaces, with link status

# bwmgr getifac ifname


Show the firewall rules on INTERFACE. Or, list the firewall rule matching INDEX.

# bwmgr INTERFACE getfwrule index

bwmgr em0 getfwrule 1200


Get the protocol list, or information about a defined protocol

# bwmgr getprot protocol -getports -active

# bwmgr getprot http getports
stdClass Object
[index] => 5
[name] => http
[stats] => stdClass Object
[cur_rx_bytes] => 37465
[cur_tx_bytes] => 66384
[cur_rx_packets] => 151
[cur_tx_packets] => 126
[cur_drops] => 0
[cur_seconds] => 6
[period] => 60
[tot_rx_bytes] => 1830
[tot_tx_bytes] => 3214
[tot_rx_packets] => 16
[tot_tx_packets] => 14
[tot_drops] => 0
[last_rx_bytes] => 184
[last_tx_bytes] => 274
[last_rx_packets] => 4
[last_tx_packets] => 4
[lastdrops] => 0
[bps] => stdClass Object
[bps_in] => 8808
[bps_out] => 15616
[tcp_ports] => Array
[0] => 80
[1] => 443
[2] => 8080
[3] => 10000
[cmd] => getprot

Shows the protocol statistics and the ports associated with http.


Get Info about a Bandwidth Management Rule

# bwmgr INTERFACE getrule INDEX | NAME


# bwmgr em0 getrule AllTraffic

stdClass Object
[ruleinfo] => stdClass Object
[ifname] => em0
[incoming] => 1
[outgoing] => 1
[stats] => 1
[index] => 100
[idx] => 8192
[hits] => 213
[priority] => Normal
[drops] => 0
[name] => AllTraffic
[bwinfo] => stdClass Object
[burstmax] => 0
[bps] => stdClass Object
[bps_in] => 1168
[bps_out] => 1392
[cmd] => getrule


Get statistics on INTERFACE, or rule NAME on INTERFACE

# bwmgr INTERFACE getstats index
# bwmgr getstats name

Get the stats for the rule named "AllTraffic"

# bwmgr getstats AllTraffic

stdClass Object
[rule] => AllTraffic
[stats] => stdClass Object
[cur_rx_bytes] => 68233
[cur_tx_bytes] => 16995
[cur_rx_packets] => 219
[cur_tx_packets] => 175
[cur_drops] => 0
[cur_seconds] => 22
[period] => 60
[tot_rx_bytes] => 209015
[tot_tx_bytes] => 258675
[tot_rx_packets] => 1435
[tot_tx_packets] => 1655
[tot_drops] => 0
[last_rx_bytes] => 7199
[last_tx_bytes] => 28979
[last_rx_packets] => 76
[last_tx_packets] => 128
[lastdrops] => 0
[bps] => stdClass Object
[bps_in] => 76840
[bps_out] => 18128


[cmd] => getstats


Set the Firewall Indexlevel

# bwmgr INTERFACE fwlevel level

# bwmgr em0 fwlevel 3

Sets the Firewall indexlevel on em0 to 3.


Sets the indexlevel for an interface

# bwmgr INTERFACE indexlevel level

Valid Levels are 1-4. 4 indexes host addresses. If most of your rules are host addresses, this is the most efficient setting. If you are managing by Class C (/24) addresses, level 3 should be used. Note that host addresses cannot be indexed using 3, and subnets cannot be indexed using 4. There is no setting for odd subnets; so choose which best suits your rules. You can use the analyze function.

# bwmgr em0 indexlevel 3

Sets the indexlevel on em0 to 3.


Load the protocol definitions

bwmgr loadprotocols FILE

Where FILE is a file with protocol and tag specifications. See bwmgr-protocols example file.


bwmgr loadprotocols /etc/bwmgr-myprotocols

Loads protocols from /etc/bwmgr-myprotocols file.


Load the protocol definitions

bwmgr loadprotocols FILE

Where FILE is a file with protocol and tag specifications. See bwmgr-protocols example file.


bwmgr loadprotocols /etc/bwmgr-myprotocols

Loads protocols from /etc/bwmgr-myprotocols file.


(Antiquated in v5.2)

Load Agent Mappings Configuration File

bwmgr load_agent_config

Loads the protocol mappings from /usr/local/etc/bwmgr/config/agents.cfg


bwmgr load_agent_config


(Antiquated in v5.2)

Load Agent Mappings Configuration File

bwmgr load_agent_config

Loads the protocol mappings from /usr/local/etc/bwmgr/config/agents.cfg


bwmgr load_agent_config


Print the settings and rules in CLI format, for use in a startup script

# bwmgr rebuild [userules] > /etc/rc.bwmgr

outputs a startup file. The database will be used unless -userules is specified, in which case the rules currently running will be used.

# bwmgr rebuild > /etc/rc.bwmgr
# bwmgr rebuild userules > /etc/rc.bwmgr


Print the bridge configuration in CLI format

# bwmgr rebuildbridging


Register a protocol file for rebuild

#bwmgr register_protfile FILENAME

Register a file so that the rebuild function will load the specified file on boot.


# bwmgr register_profile /etc/bwmgr-myprotocols
# bwmgr rebuild
/usr/bwmgr/utils/bwmgr flushdb
/usr/bwmgr/utils/bwmgr loadprotocols /etc/bwmgr-ports
/usr/bwmgr/utils/bwmgr loadprotocols /etc/bwmgr-protocols
/usr/bwmgr/utils/bwmgr loadprotocols /etc/bwmgr-myprotocols

Registers file /etc/bwmgr-myprotocols so that it is included in the startup file.


Set ET/BWMGR parameters - Max Buffers, Burst Max, Stats Period, and Max Streams

# bwmgr set [max_buffers BUFFERS] [burstmax BURST] [unburst UNBURST] [stats_period PERIOD] [max_streams MAXSTREAMS]

Use the set command to change tunable parameters in the Bandwidth Management Driver

# bwmgr set max_buffers 50000

Sets maximum number of buffers to use to 50000.


This is the "Key" interface used to license the system. It's just a reference, but if your key interface changes, your license won't work. If you add ethernet cards to your system, the default key interface may change. The setkeyifac command is always output by rebuild.

#bwmgr setkeyifac igb0

You can find the current key interface:

bwmgr status | grep key_interface

          [key_interface] => em0

If you're upgrading you might need to manually set the key interface.


Show the settings and rules for INTERFACE

# bwmgr INTERFACE show

# bwmgr em2 show

Dumps the rules currently active on the specified interface.


Show configured bridges and bridge members

# bwmgr showbridges

This is the same as getbridges except that it will return all bridges rather than just the one specified.


Show firewall rules on INTERFACE

# bwmgr INTERFACE showfw index|name

Shows the firewall rule specified (See getrule).


Prints a list of ethernet interfaces and their link status

# bwmgr shownics

# bwmgr shownics
stdClass Object
[em0] => stdClass Object
[media_status] => stdClass Object
[link_status] => active
[duplex] => full
[speed] => 1000
[em1] => stdClass Object
[media_status] => stdClass Object
[link_status] => active
[duplex] => full
[speed] => 1000


[igb0] => stdClass Object
[media_status] => stdClass Object
[link_status] => active
[duplex] => full
[speed] => 1000

[igb1] => stdClass Object
[media_status] => stdClass Object
[link_status] => down


Print status of the ET/BWMGR. Optionally include INTERFACE to get interface-specific status.

# bwmgr [INTERFACE] status

# bwmgr status
stdClass Object
[bwmgr_status] => stdClass Object
[version] => 5.0
[build] => 18
[bwmgr_running] => 1
[module_time] => 1360506854
[unburst] => 10
[track_all] => 1
[small_pkt_pri] => 0
[stats_period] => 60
[max_streams] => 25000
[hi_streams] => 168
[mem_used] => 1293056
[streams_in_use] => 15
[max_buffers] => 15000
[bufs_in_use] => 0
[high_bufs] => 0
[count_headers] => 0
[appliance_type] => R2816
[hyperthreading] => 1
[license] => 1353803998
[license_limit] => 100
[expires] => 1387861200
[sniffing] => enabled
[urlparams] => enabled
[boottime] => 1360504503
[cpu] => Intel(R) Xeon(R) CPU E5520 @ 2.27GHz

[cmd] => status


Stop the ET/BWMGR

# bwmgr stop

Stops the Bandwidth Managers. All rule processing stops.


Print the ET/BWMGR version

# bwmgr version


# bwmgr version
# bwmgr -v

Adding Rules

If no other command is given, the default is to add a new rule.


Specify the index for a rule

# bwmgr em0 -x 100 -addr -bwprofile default

Creates a rule with index 100


Use first available index numbered less than INDEX

# bwmgr em0 -addr -bwprofile default -add_before GroupA

Will insert the rule in the first index available below GroupA


Rule is a firewall rule

# bwmgr em0 -x 100 -addr -fw -priority Allow
Creates an Allow rule at index 100


Rule Name

# bwmgr em0 -x 800 -name JoeSmith


Designate rule as Global. Global rules are rules that get counted but that do not keep higher indexed rules from "hitting"

# bwmgr em0 -x 100 -global -name AllTraffic -stats
# bwmgr em0 -x 200 -addr -bwprofile default

Creates a global rule at index 100 which will count all traffic. Because it is global, if rule 200 also matches, rule 200 will be implemented.


Match Incoming Traffic


Match outgoing traffic

# bwmgr em0 -o -port 80

Match only traffic on port 80 in outgoing direction.


Match no traffic (disable rule)

# bwmgr em0 -x 100 -d

Sets the disable flag for rule 100 on em0


Enable packet logging on this rule

# bwmgr em2 -x 250 -l -ipprot tcpconnect -dport sshd

Log all incoming connections to the SSH port. With logging enabled, traffic that matches the rule will be output to the console and to the log.

-addr IPADDR

Match host IP address

# bwmgr em0 -addr

Matches traffic with as the source or destination address.

-addrmsk MASK

Address subnet mask for -addr

# bwmgr em0 -x 100 -addr -addrmsk

Specifies a /24 subnet mask for the network.

-daddr IPADDR

Match Destination IP

Matches the destination address in packets only.

-daddrmsk MASK

Apply mask to destination IP Address to match a network instead of a host.

Address Mask modifier for -daddr

-saddr IPADDR

Match source IP Address

# bwmgr em0 -saddr

-saddrmsk MASK

Address mask for -saddr

# bwmgr em0 -x 100 -saddr -saddrmsk


Match a MAC hardware address

# bwmgr em -x 100 -maddr 00:01:02:03:04:05


Match destination MAC address

# bwmgr em -x 100 -dmaddr 10:fe:24:22:04:de


Match source MAC address

# bwmgr em -x 100 -smaddr 10:fe:24:22:04:de

-port PORT#

Match if either or both of source/destination port is PORT#

# bwmgr em0 -port 80

-dport PORT#

Match if destination port number is PORT#

-sport ARG

Match source port number

-portrange PORT1-PORT2

Match port range between 2 ports

# bwmgr em0 -portrange 3000-3100

matches ports 3000 through 3100, inclusive.


Match a defined tag. Tags are defined within a protocols file, or in the IP Tags tab in the ET/BWMGR GUI. See the loadprotocols command for more information.

# bwmgr -tag badrobots -l

Logs accesses by traffic matches to the badrobots tag.

-tos #

Match the TOS (Type Of Service) field in the IP header

# bwmgr -tos c0

The octal header 0x is assumed, and does not need to be entered.

-url TEXT

Match TEXT string in HTTP URL

# bwmgr em0 -url ".txt"

matches HTTP requests with .txt in the URL

-vlan ID

Match VLAN ID number

# bwmgr em0 -vlan 25

Matches all traffic with VLAN ID set to 25.


Limit incoming bandwidth (bits/second)

# bwmgr em0 -x 100 -addr -bwin 56000

Limit Incoming bandwidth to 56000 bps


Limit outgoing bandwidth (bits/second)

# bwmgr em0 -x 100 -addr -bwout 56000

Limit outgoing bandwidth to 56000 bps


Set combined in/out bandwidth

Set combined (IN+OUT) bandwidth. It's NOT recommended to use this setting for general bandwidth management, as it creates unintended complications.


Set a bandwidth minimum. This is a dedicated allocation of bandwidth that cannot be shared with other rules, and as such it should not be used for general bandwidth management.

-bwprofile PROFILE

Apply profile to rule

# bwmgr em0 -x 100 -addr -bwprofile default

Apply profile default to traffic matching address


Apply Time-of-Day profile TIME_PROFILE to rule

# bwmgr em0 -x 100 -addr -tod default,late_night

Applies both profiles default and late_night to the rule

Read more about Time of Day Profiles

-bwburst BPS, -bwburst_in BPS, -bwburst_out BPS

Set burst limit (bits/second)

Set the burst limit for this rule; requires a -bursttrigg setting as well, otherwise there's no way to tell whether bursting is allowed. A rule with -bwburst, or -bwburst_in and/or -bwburst_out set should also have regular bandwidth settings (bwin / bwout) that are lower than the corresponding burst setting. Specify -bwburst_in and -bwburst_out for asymmetric burst limits.

# bwmgr em0 -bwboth 1000000 -bbwurst 200000 -bursttrigger AllTraffic

Sets a 1Mb/s normal limit, with a 2Mb/s burst.

# bwmgr em0 -bwin 500000 -bwout 1000000 -bwburst_out 2000000 -bursttrigger AllTraffic

This rule allows 500k/s in and 1Mb/s out, with a 2Mb/s burst for outgoing traffic only.

-burstmax ARG

Set the maximum burst duration to ARG seconds

# bwmgr em0 -bwboth 1000000 -bbwurst 200000 -bursttrigger alltraffic -burstmax 45

-burstthresh_in THRESHBPS, -burstthresh_out THRESHBPS

Set burst threshold

Set a burst threshold for a rule. Adding a burst threshold to a rule sets up that rule as a burst trigger. Trigger rules must have a name.

# bwmgr -name AllTraffic -global -burstthresh_in 800000 -burstthresh_out 8000000

Sets up a burst trigger named "AllTraffic," with the burst threshold set to 800000 bps. When there is more than 800000bps of traffic that matches this rule, all burst limits that use this trigger will use the non-burst limits (-bwin, -bwout)

-burstperiod_in ARG, burstperiod_out ARG


Set the stats period, which determines the length of time that usage is averaged on a trigger rule before enabling or disabling bursting.

-bursttrig TRIGGER

Specifies the burst trigger for a rule with bursting enabled

# bwmgr em0 -bwin 512000 -bwout 512000 -bwburst_in 750000 -bwburst_out 750000 -bursttrig AllTraffic

Sets AllTraffic as the trigger for bursting

-group NAME

Create a group (requires -name)

# bwmgr em0 -group GroupA

Creates a group named "GroupA"


"Balanced Group" where active members share bandwidth pool equally. Can only be used along with "-group"

# bwmgr em0 -x 50000 -name GroupA -b -bwin 512000 -bwout 512000

Creates a balanced group that will share 512000 bps. "-b" can only be assigned to a group, not a regular rule.

-bwlink NAME

Add rule to group NAME

# bwmgr em0 -x 800 -addr -bwlink GroupA

Creates rule 800 and adds it to GroupA

-ppsin PPS

Limit incoming Packets/second

-ppsout PPS

Limit outgoing Packets/second

-ppshi PPS

Allow burst to PPS packets/second

-priority ARG

Assign Priority ( 1=lowest, 10=highest )

# bwmgr em0 -ipprot p2p -priority 1

Set priority for p2p traffic to 1


Matches site/server name in http headers

# bwmgr em0 -site facebook.com

Matches connections to facebook.com


Add a comment to a rule

bwmgr em0 -addr -comment "Stealth Bot Detected on this Address"


Enable statistical collection on this rule, to enable usage graphs, quotas. -name also required

# bwmgr -x 100 -name AllTraffic -global -stats

Enable stats on the rule.

Note that this creates an entry in the stats table for this -name. Name is required for rules with stats enabled.


Match a MAC protocol

# bwmgr em0 -mprot arp

Match ARP packets.

-ipprot PROTOCOL

Match IP Protocol

# bwmgr em0 -ipprot smtp

Matches SMTP

Matches protocols defined either internally or in protocols from load protocols.


Reverse Rule - create dynamic IP rules using optional criteria from packets that match this rule

# bwmgr em0 -i -addr -r

Create a dynamic rule when incoming traffic for is detected; by default matching the source IP address of the packet that matched the original rule.


Reverse MAC Rule - create a dynamic MAC rule using optional criteria that match this rule


Set the idle timeout for the rules created by this reverse rule.


Use the source IP address as the matching criteria for the dynamic rule


Use the destination IP address as the matching criteria for the dynamic rule


Add the source IP port to the dynamic rule match criteria


Add the destination IP port to the dynamic rule match criteria


Use the protocol in the reverse rule.

-t [-ruletmo TIMEOUT, -fixedtmo TIMEOUT] | -tf

Temporary Rule Settings

# bwmgr -x 5000 -addr -l -t -ruletmo 120

Creates a rule that logs traffic for The rule will be deleted when it is idle for 120 seconds.

# bwmgr -x 5000 -t -addr -t -fixedtmo 120

Creates a temporary rule that will be deleted in 120 seconds, regardless of activity. You can also use the short-hand -tf which sets a fixed timeout with one parameter:

# bwmgr -x 5000 -addr -tf 120


Apply settings to interface specified, rather than creating a rule on the interface

# bwmgr em0 -ifac -bwin 512000 -bwout 512000

Sets the maximum bandwidth for em0 to 512000bps, without creating a rule index.

-ifac -o

Set the "outside" flag on the specified interface. This identifies the interface connected to your upstream provider, and allows the BWMGR to differentiate incoming vs. outgoing traffic. A required setting.

# bwmgr em3 -ifac -o


Set this interface as the "outside" interface

# bwmgr em0 -ifac -o

-autothresh_in ARG, -autothresh_out ARG

Enable Auto-Shaping on an interface. See the v5.0 User Guide for more information about Auto-Shaping

-autoperiod_in ARG, -autoperiod_out ARG

Set the period of time over which usage is averaged for Auto-Shaping.

-min_window ARG

Set the minimum window size to ARG bytes, useful when using Auto-Shaping to prevent over-limiting individual streams.