This document describes the ET/BWMGR v5.0 Command Line Interface (CLI)
Syntax
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 192.168.0.4 -bwprofile default
This simple syntax sets a rule to use the default bandwidth profile on address 192.168.0.4. You can also specify the specific controls:
bwmgr igb0 -x 500 -addr 192.168.0.4 -bwin 512000 -bwout 512000 -bwburst 2048000 -bursttrig 4mbTrigger
For a full description, see the section titled Adding Rules.
add_protocol
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
Example:
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
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.
bridge
Add an interface to an existing bridge
# bwmgr BRIDGE bridge addif INTERFACE ff learning
Example:
bwmgr bridge0 createbridge
bwmgr bridge0 bridge addif em0
bwmgr bridge0 bridge addif em0
Adds em0 and em1 to the bridge named bridge0
createbridge
Create a bridge. Specify ADDRESS to set the bridge MAC address
# bwmgr INTERFACE createbridge [address]
clearcounters
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
delrule
Delete a a rule
# bwmgr [INTERFACE] delrule index
Example:
bwmgr em0 delrule 300
disable
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
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.
flush
Clear all rules (or firewall rules) from an interface
# bwmgr INTERFACE flush fw all
flushdb
Clear entries from the database
# bwmgr flushdb
getbridges
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
)
getifac
Show the list of ethernet interfaces, with link status
# bwmgr getifac ifname
getfwrule
Show the firewall rules on INTERFACE. Or, list the firewall rule matching INDEX.
# bwmgr INTERFACE getfwrule index
Example:
bwmgr em0 getfwrule 1200
getprot
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.
getrule
Get Info about a Bandwidth Management Rule
# bwmgr INTERFACE getrule INDEX | NAME
Example:
# bwmgr em0 getrule AllTraffic
stdClass Object
(
[ruleinfo] => stdClass Object
(
[ifname] => igb0
[incoming] => 1
[outgoing] => 1
[global] => 1
[createtime] => 1544486707
[age] => 3880231
[idle] => 0
[stats] => 1
[index] => 1
[idx] => 8192
[hits] => 240218856
[drops] => 0
[priority] => Normal
[name] => AllTraffic
[bwinfo] => stdClass Object
(
)
[burstthresh_in] => 10000000
[burstperiod_in] => 20
[burstthresh_out] => 10000000
[burstperiod_out] => 20
[bps] => stdClass Object
(
[bps_in] => 25792
[bps_out] => 27248
[bps] => 53040
[pps_in] => 14
[pps_out] => 9
)
)
[cmd] => getrule
)
getstats
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
)
fwlevel
Set the Firewall Indexlevel
# bwmgr INTERFACE fwlevel level
# bwmgr em0 fwlevel 3
Sets the Firewall indexlevel on em0 to 3.
indexlevel
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.
loadprotocols
Load the protocol definitions
bwmgr loadprotocols FILE
Where FILE is a file with protocol and tag specifications. See bwmgr-protocols example file.
Example:
# bwmgr loadprotocols /etc/bwmgr-myprotocols
Loads protocols from /etc/bwmgr-myprotocols file.
loadprotocols
Load the protocol definitions
bwmgr loadprotocols FILE
Where FILE is a file with protocol and tag specifications. See bwmgr-protocols example file.
Example:
# bwmgr loadprotocols /etc/bwmgr-myprotocols
Loads protocols from /etc/bwmgr-myprotocols file.
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
Example:
# bwmgr load_agent_config
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
Example:
# bwmgr load_agent_config
rebuild
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
rebuildbridging
Print the bridge configuration in CLI format
# bwmgr rebuildbridging
register_protfile
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.
Example:
# 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
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.
setkeyifac
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
Show the settings and rules for INTERFACE
# bwmgr INTERFACE show
# bwmgr em2 show
Dumps the rules currently active on the specified interface.
showbridges
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.
showfw
Show firewall rules on INTERFACE
# bwmgr INTERFACE showfw index|name
Shows the firewall rule specified (See getrule).
shownics
Prints a list of ethernet interfaces and their link status
# bwmgr shownics
# bwmgr shownics
stdClass Object
(
[igb0] => stdClass Object
(
[period] => 2
[irqs] => 18
[media_status] => stdClass Object
(
[link_status] => active
[duplex] => full
[speed] => 1000
)
)
[igb1] => stdClass Object
(
[period] => 2
[irqs] => 0
[media_status] => stdClass Object
(
[link_status] => down
)
)
[igb2] => stdClass Object
(
[period] => 2
[irqs] => 1
[media_status] => stdClass Object
(
[link_status] => down
)
)
[igb3] => stdClass Object
(
[period] => 2
[irqs] => 1
[media_status] => stdClass Object
(
[link_status] => down
)
)
)
status
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
Stop the ET/BWMGR
# bwmgr stop
Stops the Bandwidth Managers. All rule processing stops.
version
Print the ET/BWMGR version
# bwmgr version
Example:
# bwmgr version
5.0.36
# bwmgr -v
5.0.36
Adding Rules
If no other command is given, the default is to add a new rule.
-x
Specify the index for a rule
# bwmgr em0 -x 100 -addr 192.168.11.4 -bwprofile default
Creates a rule with index 100
-add_before
Use first available index numbered less than INDEX
# bwmgr em0 -addr 11.1.1.1 -bwprofile default -add_before GroupA
Will insert the rule in the first index available below GroupA
-fw
Rule is a firewall rule
# bwmgr em0 -x 100 -addr 15.1.1.1 -fw -priority Allow
Creates an Allow rule at index 100
-name
Rule Name
# bwmgr em0 -x 800 -name JoeSmith
-global
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 10.1.1.1 -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.
-i
Match Incoming Traffic
-o
Match outgoing traffic
# bwmgr em0 -o -port 80
Match only traffic on port 80 in outgoing direction.
-d
Match no traffic (disable rule)
# bwmgr em0 -x 100 -d
Sets the disable flag for rule 100 on em0
-l
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 10.1.1.1
Matches traffic with 10.1.1.1 as the source or destination address.
-addrmsk MASK
Address subnet mask for -addr
# bwmgr em0 -x 100 -addr 10.1.1.1 -addrmsk 255.255.255.0
Specifies a /24 subnet mask for the 10.1.1.1 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 15.1.1.1
-saddrmsk MASK
Address mask for -saddr
# bwmgr em0 -x 100 -saddr 10.1.1.1 -saddrmsk 255.255.255.0
-maddr
Match a MAC hardware address
# bwmgr em -x 100 -maddr 00:01:02:03:04:05
-dmaddr
Match destination MAC address
# bwmgr em -x 100 -dmaddr 10:fe:24:22:04:de
-smaddr
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.
-tag
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.
-bwin BANDWIDTH
Limit incoming bandwidth (bits/second)
# bwmgr em0 -x 100 -addr 155.1.1.1 -bwin 56000
Limit Incoming bandwidth to 56000 bps
-bwout BANDWIDTH
Limit outgoing bandwidth (bits/second)
# bwmgr em0 -x 100 -addr 155.1.1.1 -bwout 56000
Limit outgoing bandwidth to 56000 bps
-bwboth BANDWIDTH
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.
-bwmin BANDWIDTH
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 10.1.1.1 -bwprofile default
Apply profile default to traffic matching address 10.1.1.1
-tod TIME_PROFILE
Apply Time-of-Day profile TIME_PROFILE to rule
# bwmgr em0 -x 100 -addr 10.1.1.1 -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
Description
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"
-b
"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 11.1.1.1 -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
-site SITENAME
Matches site/server name in http headers
# bwmgr em0 -site facebook.com
Matches connections to facebook.com
-comment
Add a comment to a rule
bwmgr em0 -addr 132.17.1.1 -comment "Stealth Bot Detected on this Address"
-stats
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.
-mprot PROTOCOL
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.
-r
Reverse Rule - create dynamic IP rules using optional criteria from packets that match this rule
# bwmgr em0 -i -addr 14.1.1.1 -r
Create a dynamic rule when incoming traffic for 14.1.1.1 is detected; by default matching the source IP address of the packet that matched the original rule.
-rm
Reverse MAC Rule - create a dynamic MAC rule using optional criteria that match this rule
-revtmo
Set the idle timeout for the rules created by this reverse rule.
-usesaddr
Use the source IP address as the matching criteria for the dynamic rule
-usedaddr
Use the destination IP address as the matching criteria for the dynamic rule
-usesport
Add the source IP port to the dynamic rule match criteria
-usedport
Add the destination IP port to the dynamic rule match criteria
-useprot
Use the protocol in the reverse rule.
-t [-ruletmo TIMEOUT, -fixedtmo TIMEOUT] | -tf
Temporary Rule Settings
# bwmgr -x 5000 -addr 15.1.1.1 -l -t -ruletmo 120
Creates a rule that logs traffic for 15.1.1.1. The rule will be deleted when it is idle for 120 seconds.
# bwmgr -x 5000 -t -addr 15.1.1.1 -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 15.1.1.1 -tf 120
-ifac
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
-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.