bwflow 0.1.0

Bandwidth manager for Linux

bwflow

Egress bandwidth manager for Linux. Tracks monthly traffic via vnstat and enforces rate limits using tc when your budget runs out.

How it works

At the start of each month, bwflow credits a configurable burst allowance (e.g. 50 GB) immediately. The remaining budget drips in continuously over the month. If egress exceeds the available tokens, a tc TBF rate limit is applied to your network interface. When the next month starts, the limit is lifted automatically.

Prerequisites

Package	Purpose
vnstat ≥ 2.6	Traffic accounting (source of truth)
iproute2 (tc)	Applies rate limits to the interface
Python ≥ 3.13	Runtime

# Ubuntu / Debian
sudo apt install vnstat iproute2

# Amazon Linux / RHEL
sudo yum install vnstat iproute2

# Alpine
apk add vnstat iproute2

Enable the vnstat daemon:

sudo systemctl enable --now vnstat

Installation

pip install bwflow

Verify:

bwflow --help

Quick start

1. Initialise (creates /etc/bwflow/config.toml, offers to patch vnstat.conf):

sudo bwflow init

2. Review the config:

# /etc/bwflow/config.toml

[bandwidth]
monthly_budget_gb = 100   # total monthly egress budget
pre_charge_gb = 50        # burst tokens available from day 1
billing_day = 1           # reset on the 1st of each month

[network]
interface = "eth0"        # interface to monitor and throttle

[daemon]
poll_interval_seconds = 15

3. Install and start the systemd service:

sudo cp /usr/local/lib/python3.x/site-packages/bwflow/contrib/bwflow.service \
     /etc/systemd/system/
# or from a source checkout:
sudo cp contrib/bwflow.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now bwflow

4. Check logs:

journalctl -u bwflow -f

Commands

Command	Description
sudo bwflow init	First-time setup: config + vnstat.conf patch
sudo bwflow run	Start the daemon (called by systemd)
bwflow report	Show monthly traffic report
sudo bwflow run --verbose	Debug logging (shows every 15 s tick)

Notes

• billing_day must be 1 in v0.1 (calendar-month only). Arbitrary billing days are planned.
• bwflow requires UseUTC 1 in /etc/vnstat.conf on non-UTC systems. bwflow init offers to patch this automatically.
• Rate limiting uses Linux tc TBF (Token Bucket Filter) and requires CAP_NET_ADMIN. The simplest setup is to run as root; see contrib/bwflow.service for a least-privilege alternative.