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.