Metadata-Version: 2.1
Name: mmpg-rout-pbr
Version: 0.1.0
Summary: Motor de Policy-Based Routing (PBR) para gateway Linux institucional -- decide o caminho de rede por CIDR (ip rule/ip route/nftables), com backup e rollback automaticos.
Author-email: Valfrido Novais <novaisufvjm@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ValfridoNovais/mmpg-rout-pbr
Project-URL: Repository, https://github.com/ValfridoNovais/mmpg-rout-pbr
Project-URL: Issues, https://github.com/ValfridoNovais/mmpg-rout-pbr/issues
Project-URL: Autor, https://mmpg.online
Keywords: policy-based-routing,pbr,nftables,iproute2,linux,gateway,networking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: Systems Administration
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0

# mmpg-rout-pbr

Motor de *Policy-Based Routing* (PBR) para gateways Linux institucionais:
decide automaticamente, por bloco CIDR de destino, se o tráfego sai pela
rede institucional (ex.: PRODEMGE) ou pela internet geral — sem exigir
troca manual de gateway nas estações clientes.

## Contexto

Em ambientes onde as estações precisam alternar manualmente o gateway
IPv4 entre uma rede institucional e a internet geral, dependendo do
destino, este motor centraliza essa decisão em um servidor Linux
configurado como gateway, usando os mecanismos nativos `ip rule`,
`ip route` e `nftables`.

## Premissas obrigatórias

1. A regra principal do PBR é baseada em **CIDR**, nunca em FQDN.
2. IPs institucionais externos e redes privadas institucionais ficam em
   listas separadas, adicionadas de forma explícita e validada — nunca
   se adiciona um bloco privado amplo sem confirmação formal.
3. A rota padrão é sempre a rede de internet geral — nunca a
   institucional.
4. Conexões já estabelecidas não mudam de rota durante a sessão
   (`ct state established,related` restaura a marca salva no conntrack).
5. Toda implantação precisa de modo de validação (dry-run), backup e
   rollback.
6. O monitoramento é uma evolução posterior ao núcleo funcional — fora
   de escopo deste pacote.

Os endereços de gateway e o bloco institucional são parâmetros de
`config.yaml`, não constantes do projeto — cada implantação tem sua
própria topologia de rede. Ver `config/config.example.yaml` para o
formato completo.

## Instalação

```bash
pip install mmpg-rout-pbr
```

Requer Linux com `ip` (iproute2) e `nft` (nftables) instalados.
`validate` e `plan` não tocam no sistema e rodam em qualquer máquina;
`apply`, `rollback` e `uninstall` exigem privilégio de root.

## Uso

```bash
# copie config/config.example.yaml, ajuste para sua topologia real
mmpg-rout-pbr validate --config /etc/mmpg-rout/config.yaml
mmpg-rout-pbr plan     --config /etc/mmpg-rout/config.yaml

sudo mmpg-rout-pbr apply     --config /etc/mmpg-rout/config.yaml
sudo mmpg-rout-pbr rollback                     # desfaz o último apply
sudo mmpg-rout-pbr uninstall [--purge]          # remove o que foi aplicado
```

Para produção, `scripts/install.sh` orquestra a instalação completa
(checagem de privilégios/ferramentas, encaminhamento IPv4, serviço
systemd para reaplicar a política no boot).

## Artefato principal

- **motor de PBR** (`motor/`): validação de config e listas de rede,
  geração determinística de `ip rule`/`ip route`/regras nftables, diff
  idempotente contra o estado atual do sistema, backup e rollback
  automático.
- **instalador** (`scripts/install.sh` + `scripts/mmpg-rout-pbr.service`):
  orquestra o motor num servidor Linux real, incluindo o serviço
  systemd que reaplica a política no boot.
- **listas de rede homologadas** (`config/*.txt`): blocos institucionais,
  exceções e redes privadas validadas.

## Limites de segurança

- Não implantar diretamente em produção sem laboratório.
- Não utilizar blocos privados amplos sem validação.
- Não alterar a rota de gerenciamento sem mecanismo de rollback.
- Não registrar credenciais, tokens ou conteúdo sensível em logs.
- Não afirmar que failover garante acesso quando o destino exige origem
  institucional.

## Autor

Valfrido Novais — [mmpg.online](https://mmpg.online) — novaisufvjm@gmail.com
