Metadata-Version: 2.3
Name: bwflow
Version: 0.1.0
Summary: Bandwidth manager for Linux
Author: Blake Axon
License: MIT
Requires-Dist: typer>=0.24.1
Requires-Dist: rich>=14.3.3
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# bwflow

Egress bandwidth manager for Linux. Tracks monthly traffic via [vnstat](https://humdi.net/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                              |

```bash
# Ubuntu / Debian
sudo apt install vnstat iproute2

# Amazon Linux / RHEL
sudo yum install vnstat iproute2

# Alpine
apk add vnstat iproute2
```

Enable the vnstat daemon:

```bash
sudo systemctl enable --now vnstat
```

## Installation

```bash
pip install bwflow
```

Verify:

```bash
bwflow --help
```

## Quick start

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

```bash
sudo bwflow init
```

**2. Review the config:**

```toml
# /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:**

```bash
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:**

```bash
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.
