# `flyoverhead.openwrt.pbr`

OpenWRT `Policy-Based Routing` configuration
- create and configure pbr rules and routes

## Role Variables

| Variable | Descritpion | Status | Type | Default/Example |
| :--- | :--- | :--- | :--- | :--- |
| `pbr_pkgs` | List of PBR packages to be installed | `required` | `list` | `["pbr", "luci-app-pbr"]` |
| `dnsmasq_full_required_version` | Dnsmasq-full package version required for dnsmasq nft sets support | `required` | `string` | `2.89` |
| `pbr_service` | PBR service configuration settings to be applied |  | `dictionary` |  |
|  `enabled` | Enable pbr service | `required` | `boolean` | `1` |
|  `verbosity` | Console and system log output verbosity (`0`, `1` or `2`) | `optional` | `integer` | `2` |
|  `strict_enforcement` | Enforce policies when their interface is down | `required` | `boolean` | `1` |
|  `resolver_set` | Resolver’s set support for domains (`none`, `adguardhome.ipset`, `dnsmasq.ipset` or `dnsmasq.nftset`) | `required` | `string` | `dnsmasq.nftset` |
|  `resolver_instance` | List of resolver’s set support instances (available for `dnsmasq.ipset` and `dnsmasq.nftset`) | `optional` | `string` | `*` |
|  `ipv6_enabled` | Enable IPv6 support | `optional` | `boolean` | `0` |
|  `supported_interface` | List of network interfaces to be explicitly supported by the pbr service | `optional` | `list` | `["lan", "wan"]` |
|  `ignored_interface` | List of network interfaces to be ignored by the pbr service | `optional` | `list` | `["vpnserver", "wgserver"]` |
|  `boot_timeout` | Time in seconds for pbr service to wait for WAN gateway discovery on boot | `optional` | `integer` | `30` |
|  `rule_create_option` | Policy rule creation option (`add` or `insert`) | `required` | `string` | `add` |
|  `icmp_interface` | Default ICMP protocol network interface | `optional` | `string` | `wan` |
|  `wan_mark` | Firewall mark for marks used by the pbr service | `optional` | `string` | `010000` |
|  `fw_mask` | Firewall mask used by the pbr service | `optional` | `string` | `ff0000` |
|  `secure_reload` | Enable killing router traffic (activates killswitch) during service start/restart/reload operations to prevent traffic leaks on unwanted interface (`experimental`) | `optional` | `boolean` | `0` |
|  `webui_show_ignore_target` | Show `ignore` in the list of interfaces | `optional` | `boolean` | `0` |
|  `webui_supported_protocol` | List of protocols to display in the `Protocol` column for policies (`all`, `tcp`, `udp` or `icmp`) | `optional` | `list` | `0` |
| `pbr_policies` | List of PBR policies |  | `list of dictionaries` |  |
|  `id` | Unique policy ID | `mandatory` | `string` | `example_policy` |
|  `name` | Unique policy name | `mandatory` | `string` | `Example policy` |
|  `state` | Policy status (`present` or `absent`) | `required` | `string` | `present` |
|  `enabled` | Enable policy | `required` | `boolean` | `1` |
|  `interface` | Policy associated network interface | `mandatory` | `string` | `vpn0` |
|  `src_addr` | List of local/source IP addresses, CIDRs, hostnames, mac addresses, local physical devices or URLs to list of addresses (not compatible with the `secure_reload` option) | `required` | `list` | `["192.168.1.0/24"]` |
|  `src_port` | List of space-separated local/source ports or port-ranges | `required` | `list` | `["22", "8000-9000"]` |
|  `dest_addr` | List of remote/target IP addresses, CIDRs, hostnames/domain names or URLs to list of addresses | `required` | `list` | `["192.168.2.0/24"]` |
|  `dest_port` | List of space-separated remote/target ports or port-ranges | `required` | `list` | `["22", "8000-9000"]` |
|  `proto` | Policy protocol (any valid protocol from `/etc/protocols` for CLI/uci or selected from the values set in `webui_supported_protocol`) | `required` | `string` | `auto` |
|  `chain` | Policy chain (`forward`, `input`, `prerouting`, `postrouting` or `output`) | `required` | `string` | `prerouting` |

## Dependencies

| Name | Description |
| :--- | :--- |
| `Ansible Role: openwrt` | [Ansible role by gekmihesg](https://github.com/gekmihesg/ansible-openwrt) for managing OpenWRT and derivatives |

## Example Playbook

```yaml
- hosts: openwrt
  roles:
      - role: flyoverhead.openwrt.pbr
```

## Example Vars

```yaml
pbr_service:
  enabled: "1"
  verbosity: "0"
  strict_enforcement: "0"
  resolver_set: "dnsmasq.nftset"
  ipv6_enabled: "0"
  ignored_interface: ["vpnserver"]
  boot_timeout: "30"
  rule_create_option: "add"
  webui_show_ignore_target: "0"
  webui_supported_protocol: ["all", "tcp", "udp", "tcp udp", "icmp"]
pbr_policies:
  - id: "example_policy"
    name: "Example policy"
    state: "present"
    enabled: "1"
    interface: "vpn0"
    dest_addr: ["blocked.example.com", "blocked.com"]
    chain: "prerouting"
```

## License

[GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.txt)

## Author Information

fly0v3rH34D

## References

- https://openwrt.org/docs/guide-user/network/routing/pbr_app
- https://docs.openwrt.melmac.net/pbr/#a-word-about-default-routing