packages Documentation

Technical Documentation: openwrt/packages

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

OpenWrt packages feed

Description Copy Chapter

This is the OpenWrt "packages"-feed containing community-maintained build scripts, options and patches for applications, modules and libraries used within OpenWrt.

Installation of pre-built packages is handled directly by the opkg utility within your running OpenWrt system or by using the OpenWrt SDK on a build system.

Usage Copy Chapter

This repository is intended to be layered on-top of an OpenWrt buildroot. If you do not have an OpenWrt buildroot installed, see the documentation at: OpenWrt Buildroot – Installation on the OpenWrt support site.

This feed is enabled by default. To install all its package definitions, run:

./scripts/feeds update packages
./scripts/feeds install -a -p packages

License Copy Chapter

See LICENSE file.

Package Guidelines Copy Chapter

See CONTRIBUTING.md file.

Overview (`lang/python/README.md`) Copy Section

Python packages folder

Table of contents Copy Chapter

1. Description
2. Introduction
3. Python 2 end-of-life
4. Using Python in external/other package feeds
5. Build considerations
6. General folder structure
7. Building a Python package
   1. Include python3-package.mk
   2. Add Package/ OpenWrt definitions
   3. Python package dependencies
   4. Wrapping things up so that they build
   5. Customizing things
   6. Host-side Python packages for build

Description Copy Chapter

This section describes specifics for the Python packages that are present in this repo, and how things are structured.

In terms of license, contributing guide, etc, all of that information is described in the top README.md file, and it applies here as well. This document attempts to cover only technical aspects of Python packages, and maybe some explanations about how things are (and why they are as they are).

Introduction Copy Chapter

This sub-tree came to exist after a number of contributions (Python packages) were made to this repo, and the lang subtree grew to a point where a decision was made to move all Python packages under lang/python.

It contains the Python 3 interpreter and Python packages. Most of the Python packages are downloaded from pypi.org. Python packages from pypi.org are typically preferred when adding new packages.

If more packages (than the ones packaged here) are needed, they can be downloaded via pip. Note that the versions of pip & setuptools [available in this repo] are the ones that are packaged inside the Python package (yes, Python comes packaged with pip & setuptools).

Python 2 end-of-life Copy Chapter

Python 2 will not be maintained past 2020. All Python 2 packages have been removed from the packages feed (this repo) and archived in the abandoned packages feed.

Using Python in external/other package feeds Copy Chapter

In the feeds.conf (or feeds.conf.default file, whatever is preferred), the packages repo should be present.

Example

src-git packages https://git.openwrt.org/feed/packages.git
src-git luci https://git.openwrt.org/project/luci.git
src-git routing https://git.openwrt.org/feed/routing.git
src-git telephony https://git.openwrt.org/feed/telephony.git
#
#
src-git someotherfeed https://github.com/<github-user>/<some-other-package>

Assuming that there are Python packages in the <some-other-package>, they should include python3-package.mk like this:

include $(TOPDIR)/feeds/packages/lang/python/python3-package.mk

Same rules apply for python3-package.mk as the Python packages in this repo.

One important consideration:: if the local name is not packages, it's something else, like openwrt-packages. And in feeds.conf[.default] it's:

src-git openwrt-packages https://git.openwrt.org/feed/packages.git

Then, the inclusions also change:

include $(TOPDIR)/feeds/openwrt-packages/lang/python/python3-package.mk

Each maintainer[s] of external packages feeds is responsible for the local name, and relative inclusion path back to this feed (which is named packages by default).

In case there is a need/requirement such that the local package feed is named something else than packages, one approach to make the package flexible to change is:

PYTHON3_PACKAGE_MK:=$(wildcard $(TOPDIR)/feeds/*/lang/python/python3-package.mk)

# verify that there is only one single file returned
ifneq (1,$(words $(PYTHON3_PACKAGE_MK)))
ifeq (0,$(words $(PYTHON3_PACKAGE_MK)))
$(error did not find python3-package.mk in any feed)
else
$(error found multiple python3-package.mk files in the feeds)
endif
else
$(info found python3-package.mk at $(PYTHON3_PACKAGE_MK))
endif

include $(PYTHON3_PACKAGE_MK)

This should solve the corner-case where the python3-package.mk can be in some other feed, or if the packages feed will be named something else locally.

Build considerations Copy Chapter

In order to build the Python interpreter, a host Python interpreter needs to be built, in order to process some of the build for the target Python build. The host Python interpreter is also needed so that Python bytecodes are generated, so the host interpreter needs to be the exact version as on the target. And finally, the host Python interpreter also provides pip, so that it may be used to install some Python packages that are required to build other Python packages.
That's why you'll also see a Python build & staging directories.

As you're probably thinking, this sounds [and is] somewhat too much complication [just for packaging], but the status of things is-as-it-is, and it's probably much worse than what's currently visible on the surface [with respect to packaging Python & packages].

As mentioned earlier, Python packages are shipped with bytecodes, and the reason for this is simply performance & size.
The thought/discussion matrix derives a bit like this:

• shipping both Python source-code & bytecodes takes too much space on some devices ; Python source code & byte-code take about similar disk-size
• shipping only Python source code has a big performance penalty [on some lower end systems] ; something like 500 msecs (Python source-only) -> 70 msecs (Python byte-codes) time reduction for a simple "Hello World" script
• shipping only Python byte-codes seems like a good trade-off, and this means that python3-src can be provided for people that want the source code

By default, automatic Python byte-code generation is disabled when running a Python script, in order to prevent a disk from accidentally filling up. Since some disks reside in RAM, this also means not filling up the RAM. If someone wants to convert Python source to byte-code then he/she is free to compile it [directly on the device] manually via the Python interpreter & library.

General folder structure Copy Chapter

The basis of all these packages is:

• lang/python/python3 - The Python 3.x.y interpreter

This is a normal OpenWrt package, which will build the Python interpreter. This also provides python3-pip & python3-setuptools. Each Python package is actually split into multiple sub-packages [e.g. python3-urllib, python3-sqlite3, etc]. This can be viewed inside lang/python/python3/files.

The reason for this splitting, is purely to offer a way for some people to package Python in as-minimal-as-possible-and-still-runable way, and also to be somewhat maintainable when packaging. A standard Python installation can take ~20-30 MBs of disk, which can be somewhat big for some people, so there is the python3-base package which brings that down to ~5 MBs. This seems to be good enough (and interesting) for a number of people.

The Python interpreter is structured like this:

• python3-base, which is just the minimal package to startup Python and run basic commands
• python3 is a meta-package, which installs almost everything (python3-base [plus] Python library [minus] some unit-tests & some windows-y things)
• python3-light is python3 [minus] packages that are in lang/python/python3/files ; the size of this package may be sensible (and interesting) to another group of people

All other Python packages (aside from the intepreter) typically use these files:

• python3-host.mk - this file contains paths and build rules for running the Python interpreter on the host-side; they also provide paths to host interprete, host Python lib-dir & so on
• python3-package.mk
  • includes python3-host.mk
  • contains all the default build rules for Python packages; these will be detailed below in the Building a Python package section

Note that Python packages don't need to use these files (i.e. python3-package.mk & python3-host.mk), but they do provide some ease-of-use & reduction of duplicate code. And they do contain some learned-lessons about packaging Python packages, so it's a good idea to use them.

Building a Python package Copy Chapter

Include python3-package.mk Copy Section

Add this after include $(INCLUDE_DIR)/package.mk

include ../python3-package.mk

This will make sure that build rules for Python can be specified and picked up for build.

Include pypi.mk (optional) Copy Section

pypi.mk is an include file that makes downloading package source code from pypi.org simpler.

To use pypi.mk, add this before include $(INCLUDE_DIR)/package.mk:

include ../pypi.mk

pypi.mk has several PYPI_* variables that can/must be set (see below); these should be set before pypi.mk is included, i.e. before the include ../pypi.mk line.

pypi.mk also provides default values for PKG_SOURCE and PKG_SOURCE_URL, so these variables may be omitted.

Required variables:

• PYPI_NAME: Package name on pypi.org. This should match the PyPI name exactly.

  For example (from the python-yaml package):

  text Copy

  PYPI_NAME:=PyYAML

Optional variables:

• PYPI_SOURCE_NAME: Package name component of the source tarball filename
  Default: Same value as PYPI_NAME

• PYPI_SOURCE_EXT: File extension of the source tarball filename
  Default: tar.gz

pypi.mk constructs the default PKG_SOURCE value from these variables (and PKG_VERSION):

PKG_SOURCE?=$(PYPI_SOURCE_NAME)-$(PKG_VERSION).$(PYPI_SOURCE_EXT)

Add Package/ OpenWrt definitions Copy Section

This part is similar to default OpenWrt packages.

Example:

define Package/python3-lxml
  SECTION:=lang
  CATEGORY:=Languages
  SUBMENU:=Python
  TITLE:=Pythonic XML processing library
  URL:=https://lxml.de
  DEPENDS:=+python3-light +libxml2 +libxslt +libexslt
endef

define Package/python3-lxml/description
  The lxml XML toolkit is a Pythonic binding
  for the C libraries libxml2 and libxslt.
endef

Some considerations here (based on the example above):

• typically the package is named Package/python3-<something> ; this convention makes things easier to follow, though it could work without naming things this way
• TITLE can be something a bit more verbose/neat ; typically the name is short as seen above

Python package dependencies Copy Section

Aside from other libraries and programs, every Python package will depend on at least one of these three types of packages:

• The Python interpreter: All Python packages should depend on one of these three interpreter packages:

  • python3-light is the best default for most Python packages.

  • python3-base should only be used as a dependency if you are certain the bare interpreter is sufficient.

  • python3 is useful if many (more than three) Python standard library packages are needed.

• Python standard library packages: As noted above, many parts of the Python standard library are packaged separate from the Python interpreter. These packages are defined by the files in lang/python/python3/files.

  To find out which of these separate standard library packages are necessary, after completing a draft Makefile (including the $(eval ...) lines described in the next section), run make with the configure target and PY3=stdlib V=s in the command line. For example:

  text Copy

  make package/python-lxml/configure PY3=stdlib V=s

  If the package has been built previously, include the clean target to trigger configure again:

  text Copy

  make package/python-lxml/{clean,configure} PY3=stdlib V=s

  This will search the package for module imports and generate a list of suggested dependencies. Some of the found imports may be false positives, e.g. in example or test files, so examine the matches for more information.

• Other Python packages: The easiest way to find these dependencies is to look for the install_requires keyword inside the package's setup.py file (it will be a keyword argument to the setup() function). This will be a list of run-time dependencies for the package.

  There may already be packages in the packages feed that provide these dependencies. If not, they will need to be packaged for your Python package to function correctly.

  Any packages in a setup_requires keyword argument are build-time dependencies that may need to be installed on the host (host Python inside of OpenWrt buildroot, not system Python that is part of the outer computer system). To ensure these build-time dependencies are present, see Host-side Python packages for build. (Note that Setuptools is already installed as part of host Python.)

Wrapping things up so that they build Copy Section

If all the above prerequisites have been met, all that's left is:

$(eval $(call Py3Package,python3-lxml))
$(eval $(call BuildPackage,python3-lxml))

The $(eval $(call Py3Package,python3-lxml)) part will instantiate all the default Python build rules so that the final Python package is packaged into an OpenWrt.
And $(eval $(call BuildPackage,python3-lxml)) will bind all the rules generated with $(eval $(call Py3Package,python3-lxml)) into the OpenWrt build system.

These packages will contain byte-codes and binaries (shared libs & other stuff).

If a user wishes to ship source code, adding one more line creates one more package that ship Python source code:

$(eval $(call Py3Package,python3-lxml))
$(eval $(call BuildPackage,python3-lxml))
$(eval $(call BuildPackage,python3-lxml-src))

The name *-src must be the Python package name; so for python3-lxml-src a equivalent python3-lxml name must exist.

Customizing things Copy Section

Some packages need custom build rules (because they do).

The default package build and install processes are defined in python3-package.mk.

Building

The default build process calls setup.py install inside the directory where the Python source package is extracted (PKG_BUILD_DIR). This "installs" the Python package to an intermediate location (PKG_INSTALL_DIR) where it is used by the default install process.

There are several Makefile variables that can be used to customize this process (all optional):

• PYTHON3_PKG_SETUP_DIR: Path where setup.py can be found, relative to the package directory (PKG_BUILD_DIR).
  Default: empty value (setup.py is in the package directory)
• PYTHON3_PKG_SETUP_VARS: Additional environment variables to set for the call to setup.py. Should be in the form of VARIABLE1=value VARIABLE2=value ....
  Default: empty value
• PYTHON3_PKG_SETUP_GLOBAL_ARGS: Additional command line arguments to pass to setup.py, before / in front of the install command.
  Default: empty value
• PYTHON3_PKG_SETUP_ARGS: Additional command line arguments to pass to setup.py, after the install command.
  Default: --single-version-externally-managed

Conceptually, these variables are used in this way:

cd $(PKG_BUILD_DIR)/$(PYTHON3_PKG_SETUP_DIR)
$(PYTHON3_PKG_SETUP_VARS) python3 setup.py $(PYTHON3_PKG_SETUP_GLOBAL_ARGS) install $(PYTHON3_PKG_SETUP_ARGS)

The default build process can be completely overridden by defining a custom Py3Build/Compile rule in the package Makefile.

Installing

The default install process copies some/all of the files from PKG_INSTALL_DIR, placed there by the build process, to a location passed to the install rule as the first argument ($(1)). The OpenWrt build system will then take those files and create the actual .ipk package archives.

This default process uses 2 build rules:

• Py3Package//filespec which are Python library files relative to /usr/lib/pythonX.Y ; by default this is /usr/lib/python$(PYTHON3_VERSION)/site-packages (PYTHON3_PKG_DIR) ; most Python packages generate files that get installed in this sub-folder
• Py3Package//install is similar to Package//install ; this allows binary (or other files) to be installed on the target

Both the 2 above rules generate a Package//install build rule, which gets picked up by the build system. Both can be used together (they are not mutually exclusive), and provide a good enough flexibility for specifying Python packages.

The Py3Package//filespec rule contains one or more lines of the following format (whitespace added for clarity):

<one of: +-=> | <file/directory path> | <file permissions>

The initial character controls the action that will be taken:

• +: Install the given path. If the path is a directory, all files and subdirectories inside are installed.
  • If file permissions is specified (optional), then the file or directory (and all files and subdirectories) are assigned the given permissions; if omitted, then the file or directory retains its original permissions.
• -: Remove the given path. Useful when most of a directory should be installed except for a few files or subdirectories.
  • File permissions is not used / ignored in this case.
• =: Assign the given file permissions to the given path. File permissions is required in this case.

As mentioned, the default Py3Package//filespec installs PYTHON3_PKG_DIR:

define Py3Package/python3-example/filespec
+|$(PYTHON3_PKG_DIR)
endef

If the package installs a example_package directory inside PYTHON3_PKG_DIR, and there is an examples directory and test_*.py files that can be omitted to save space, this can be specified as:

define Py3Package/python3-example/filespec
+|$(PYTHON3_PKG_DIR)
-|$(PYTHON3_PKG_DIR)/example_package/examples
-|$(PYTHON3_PKG_DIR)/example_package/test_*.py
endef

Host-side Python packages for build Copy Section

These can be installed via pip and ideally they should only be installed like this, because it's a bit simpler than running them through the OpenWrt build system.

Requirements files

All host-side Python packages are installed with pip using requirements files, with hash-checking mode enabled. These requirements files are stored in the host-pip-requirements directory.

Each requirements file is named after the Python package it installs and contains the package's pinned version and --hash option. The --hash option value is the SHA256 hash of the package's source tarball; this value can be found on pypi.org.

For example, the requirements file for setuptools-scm (setuptools-scm.txt) contains:

setuptools-scm==4.1.2 --hash=sha256:a8994582e716ec690f33fec70cca0f85bd23ec974e3f783233e4879090a7faa8

If the Python package to be installed depends on other Python packages, those dependencies, with their pinned versions and --hash options, also need to be specified in the requirements file. For instance, cffi.txt includes information for pycparser because pycparser is a dependency of cffi and will be installed with cffi.

There are two types of requirements files in host-pip-requirements:

• Installs the latest version of a Python package.

  A requirements file of this type is named with the package name only (for example, setuptools-scm.txt) and is used when there is no strict version requirement.

  These files will be updated as newer versions of the Python packages are available.

• Installs a specific version of a Python package.

  A requirements file of this type is named with the package name and version number (for example, Django-1.11.txt) and is used when a specific (usually older) version is required.

  Installing the latest versions of packages is preferred over specific versions whenever possible.

Installing host-side Python packages

Set HOST_PYTHON3_PACKAGE_BUILD_DEPENDS to the names of one or more requirements files in host-pip-requirements, without the directory path or ".txt" extension.

For example:

HOST_PYTHON3_PACKAGE_BUILD_DEPENDS:=setuptools-scm

The Python package will be installed in $(STAGING_DIR_HOSTPKG)/lib/pythonX.Y/site-packages.

Non-Python packages installing host-side Python packages

Non-Python packages can also install host-side Python packages using the same mechanism:

• Set HOST_PYTHON3_PACKAGE_BUILD_DEPENDS (see above for details).

• Include python3-package.mk (set PYTHON3_PKG_BUILD:=0 to avoid using the default Python package build recipes).

• Call Py3Build/InstallBuildDepends to initiate the installation.

For example:

PYTHON3_PKG_BUILD:=0
HOST_PYTHON3_PACKAGE_BUILD_DEPENDS:=setuptools-scm

include $(INCLUDE_DIR)/package.mk
include ../../lang/python/python3-package.mk
# If outside of the packages feed:
# include $(TOPDIR)/feeds/packages/lang/python/python3-package.mk

define Build/Compile
	$(call Py3Build/InstallBuildDepends)
	$(call Build/Compile/Default)
endef

Overview (`net/adblock-fast/README.md`) Copy Section

adblock-fast

A fast, lightweight DNS-based ad-blocker for OpenWrt that works with dnsmasq, smartdns, or unbound.
It runs once to process and install blocklists, then exits — keeping memory usage low.

Features Copy Chapter

• Minimal runtime memory use
• Parallel blocklist download and processing
• Persistent cache support
• Optional Web UI for custom block/allow lists
• Reverts if DNS resolution fails after restart

📚 Full documentation:
https://docs.mossdef.org/adblock-fast/

Overview (`net/adblock/README.md`) Copy Section

DNS based ad/abuse domain blocking

Table of Contents Copy Chapter

• Description
• Quick Start
• Main Features
• Prerequisites
• Installation & Usage
• Adblock CLI interface
• Adblock Config Options
• Examples
• Best practice and tweaks
• Troubleshooting & debug options
• Support
• Removal
• Donations

Description Copy Chapter

A lot of people already use adblocker plugins within their desktop browsers, but what if you are using your (smart) phone, tablet, watch or any other (wlan) gadget!? Getting rid of annoying ads, trackers and other abuse sites (like facebook) is simple: block them with your router.

When the DNS server on your router receives DNS requests, you will sort out queries that ask for the resource records of ad servers and return a simple NXDOMAIN. This is nothing but Non-eXistent Internet or Intranet domain name, if a domain name cannot be resolved using the DNS server, a condition called the NXDOMAIN occurred.

Quick Start Copy Chapter

For a typical setup these few steps are enough to get adblock up and running — see the sections below for details:

1. Install the LuCI companion package: apk update && apk add luci-app-adblock (this pulls in the adblock backend as a dependency).
2. Enable the adblock system service under System → Startup, then open LuCI under Services → Adblock, tick Enabled and (recommended) set a Startup Trigger Interface to your WAN interface(s).
3. Keep the small, pre-selected default feed selection to start with (e.g. adguard, adguard_tracking and certpl, ≈280K domains).
4. Start and verify the service:

/etc/init.d/adblock start
/etc/init.d/adblock status

Please note: don't blindly enable (too) many feeds at once — on low memory devices this will sooner or later lead to OOM conditions.

Main Features Copy Chapter

Support of the following fully pre-configured domain blocklist feeds (free for private usage, for commercial use please check their individual licenses)

Please note: Feeds marked with size VAR (1Hosts, hagezi, ipfire_dbl, stevenblack, utcapitole) additionally require a category selection via the options adb_hst_feed, adb_hag_feed, adb_ipf_feed, adb_stb_feed and adb_utc_feed (or via the LuCI feed configuration). Without a category the feed is skipped during processing.

• List of supported and fully pre-configured adblock sources, already active sources are pre-selected.
  To avoid OOM errors, please do not select too many lists!
  List size information with the respective domain ranges as follows:
  • S (-10k), M (10k-30k) and L (30k-80k) should work for 128 MByte devices
  • XL (80k-200k) should work for 256-512 MByte devices
  • XXL (200k-) needs more RAM and Multicore support, e.g. x86 or raspberry devices
  • VAR (50k-900k) variable size depending on the selection
• Zero-conf like automatic installation & setup, usually no manual changes needed
• Simple but yet powerful adblock engine: adblock does not use error prone external iptables rulesets, http pixel server instances and things like that
• Supports six different DNS backend formats: dnsmasq, unbound, named (bind), kresd, smartdns or raw (e.g. used by dnscrypt-proxy)
• Supports three different SSL-enabled download utilities: uclient-fetch, full wget or curl
• Supports SafeSearch for google, bing, brave, duckduckgo, yandex, youtube and pixabay
• Fast downloads & list processing as they are handled in parallel running background jobs with multicore support
• The download engine supports ETAG headers to download only updated feeds
• Supports a wide range of router modes, even AP modes are supported
• Full IPv4 and IPv6 support
• Provides top level domain compression (tld compression), this feature removes thousands of needless host entries from the blocklist and lowers the memory footprint for the DNS backend
• Packs multiple domains per dnsmasq 'local=' line (max. 1000 characters), this reduces the size of the final blocklist by ~30% and speeds up the dnsmasq start
• Provides a DNS Blocklist Shift, where the generated final DNS blocklist is moved to the backup directory and only a soft link to this file is set in memory. As long as your backup directory is located on an external drive, you should activate this option to save valuable RAM.
• Feed parsing by a very fast & secure domain validator, all domain rules and feed information are placed in an external JSON file (/etc/adblock/adblock.feeds)
• Overall duplicate removal in generated blocklist file adb_list.overall
• Additional local allowlist for manual overrides, located in /etc/adblock/adblock.allowlist
• Additional local blocklist for manual overrides, located in /etc/adblock/adblock.blocklist
• Implements firewall‑based DNS Control to force DNS interfaces/ports and to redirect to external unfiltered/filtered DNS server
• Includes firewall‑based Remote DNS Allow, a CGI-Interface to allow certain MACs temporary bypass the local adblock DNS
• Supports firewall‑based temporary DNS Bridging, to ensure a Zero‑Downtime during adblock-related DNS Restarts
• Connection checks during blocklist update to ensure a reliable DNS backend service
• Minimal status & error logging to syslog, enable debug logging to receive more output
• Procd based init system support (start, stop, restart, reload, enable, disable, running, status, suspend, resume, search, report)
• Auto-Startup via procd network interface trigger or via classic time based startup
• Suspend & Resume adblock temporarily without blocklist re-processing
• Provides comprehensive runtime information
• Provides a detailed DNS Report with DNS related information about client requests, top (blocked) domains and more
• Provides a powerful search function to quickly find blocked (sub-)domains, e.g. to allow certain domains
• Implements a jail mode - only domains on the allowlist are permitted, all other DNS requests are rejected
• Automatic blocklist backup & restore: backups are used on start/restart and as a fallback on download errors — feeds are only actually refreshed via reload
• Send notification E-Mails, see example configuration below
• Add new adblock feeds on your own with the Custom Feed Editor in LuCI or via CLI, see example below
• Strong LuCI support, all relevant options are exposed to the web frontend

Prerequisites Copy Chapter

• OpenWrt, latest stable release or a development snapshot
• A usual setup with a working DNS backend
• A download utility with SSL support: wget, uclient-fetch with one of the libustream-* ssl libraries or curl is required
• A certificate store such as ca-bundle or ca-certificates, as adblock checks the validity of the SSL certificates of all download sites by default
• For E-Mail notifications you need to install and setup the additional msmtp package
• For DNS reporting you need to install the additional package tcpdump-mini or tcpdump

Please note:

• Devices with less than 128MB of RAM are not supported
• For performance reasons, adblock depends on gnu sort and gawk
• Before update from former adblock releases please make a backup of your local allow- and blocklists. In the latest adblock these lists have been renamed to /etc/adblock/adblock.allowlist and /etc/adblock/adblock.blocklist. There is no automatic content transition to the new files.
• The uci configuration of adblock is automatically migrated during package installation via the uci-defaults mechanism using a housekeeping script
• Only reload actually refreshes the feeds (ETag check plus download of changed feeds). start, restart — and boot/resume — restore the existing blocklist backups and only download feeds that have no backup yet; they do not re-fetch already cached feeds. To update your blocklists (e.g. from a cron job) always use reload

Installation & Usage Copy Chapter

• Make a backup and update your local opkg/apk repository
• Install the LuCI companion package luci-app-adblock which also installs the main adblock package as a dependency
• Enable the adblock system service (System -> Startup) and enable adblock itself (adblock -> General Settings)
• It's strongly recommended to use the LuCI frontend to easily configure all aspects of adblock, the application is located in LuCI under the Services menu
• It's also recommended to configure a Startup Trigger Interface to depend on your WAN interface events during boot or restart of your router. Listing IPv6 interfaces (wan6) is fine as well: a trigger only starts a run if the last one did not succeed or if its blocklist is gone, so the chatty netifd update events no longer cause repeated downloads

Adblock CLI interface Copy Chapter

• The most important adblock functions are accessible via CLI as well.

~# /etc/init.d/adblock
Syntax: /etc/init.d/adblock [command]

Available commands:
	start           Start the service
	stop            Stop the service
	restart         Restart the service
	reload          Reload configuration files (or restart if service does not implement reload)
	enable          Enable service autostart
	disable         Disable service autostart
	enabled         Check if service is started on boot
	suspend         Suspend adblock processing
	resume          Resume adblock processing
	search          <domain> Search active blocklists and backups for a specific domain
	report          [<cli>|<mail>|<gen>|<json>] Print DNS statistics
	running         Check if service is running
	status          Service status
	trace           Start with syscall trace
	info            Dump procd service info

The report sub-command accepts an output mode: cli (default, human-readable table printed to the console), json (machine-readable output, incl. GeoIP map data when adb_map=1), mail (send the report via msmtp) and gen (regenerate the report data files in the background, used by the LuCI frontend).

Adblock Config Options Copy Chapter

• Usually the auto pre-configured adblock setup works quite well and no manual overrides are needed

Examples Copy Chapter

Change the DNS backend to unbound:
No further configuration is needed, adblock deposits the final blocklist adb_list.overall in /var/lib/unbound by default.
To preserve the DNS cache after adblock processing please install the additional package unbound-control.

Change the DNS backend to bind:
Adblock deposits the final blocklist adb_list.overall in /var/lib/bind by default.
To preserve the DNS cache after adblock processing please install the additional package bind-rndc.
To use the blocklist please modify /etc/bind/named.conf:

in the `options` namespace add:
  response-policy { zone "rpz"; };

and at the end of the file add:
  zone "rpz" {
    type master;
    file "/var/lib/bind/adb_list.overall";
    allow-query { none; };
    allow-transfer { none; };
  };

Change the DNS backend to kresd:
Adblock deposits the final blocklist adb_list.overall in /tmp/kresd, no further configuration needed.

Change the DNS backend to smartdns:
No further configuration is needed, adblock deposits the final blocklist adb_list.overall in /tmp/smartdns by default.

Service status output:
In LuCI you'll see the realtime status in the Runtime section on the overview page.
To get the status in the CLI, just call /etc/init.d/adblock status or /etc/init.d/adblock status_service:

root@blackhole:~# /etc/init.d/adblock status
::: adblock runtime information
  + adblock_status  : enabled
  + frontend_ver    : 4.5.2-r4
  + backend_ver     : 4.5.2-r4
  + blocked_domains : 888 135
  + active_feeds    : 1hosts, adguard, adguard_tracking, bitcoin, certpl, doh_blocklist, hagezi, ipfire_dbl, phishing_army, smarttv_tracking, stevenblack, winspy
  + dns_backend     : unbound (1.24.2-r1), /mnt/data/adblock/backup, 346.57 MB
  + run_ifaces      : trigger: wan, report: br-lan
  + run_information : base: /mnt/data/adblock, dns: /var/lib/unbound, backup: /mnt/data/adblock/backup, report: /mnt/data/adblock/report, error: /dev/null
  + run_flags       : shift: ✔, custom feed: ✘, ext. DNS (std/prot/remote/bridge): ✘/✔/✔/✔, force: ✔, flush: ✘, tld: ✔, search: ✘, report: ✔, mail: ✔, jail: ✘, debug: ✘
  + last_run        : mode: reload, 2026-03-12T19:08:41+01:00, duration: 0m 57s, 1337.01 MB available
  + system_info     : cores: 4, fetch: curl, Bananapi BPI-R3, mediatek/filogic, OpenWrt SNAPSHOT (r33360-ab0872a734)

Best practice and tweaks Copy Chapter

Recommendation for low memory systems
adblock keeps all working data in RAM to avoid unnecessary flash wear. The number of parallel processing jobs and the sort buffer size are automatically scaled to the available memory, so on constrained devices adblock already throttles itself during feed processing. On devices with only 128–256 MB RAM, you can further reduce memory pressure with the following optimizations:

• Limit CPU parallelism: the auto-detected core count is capped to the available memory; set adb_cores=1 to force single-threaded processing with minimal peak memory. A manually set value is always used as-is — it is never lowered, so raising it on a constrained device is at your own risk
• Use external storage: with the defaults the feed backups (adb_backupdir) and the final blocklist (adb_dnsdir) are kept in RAM permanently, not only during feed processing, e.g. 72 MB backups and a 53 MB blocklist with 1.1M entries. Set adb_basedir, adb_backupdir and adb_reportdir to a USB drive or SSD to offload the temporary and persistent data
• Enable blocklist shifting: activate adb_dnsshift to store the generated blocklist in the backup directory on external storage and keep only a symlink in RAM
• Use firewall‑based DNS redirection: Route DNS queries via nftables to external filtered DNS resolvers and keep only a minimal local blocklist active
• Use compressed swap: install the zram-swap package so the kernel can page out cold memory into compressed RAM under pressure (see below)

Top level domain compression (adb_tld)
The top level domain compression is enabled by default. It removes all subdomains of already blocked domains (e.g. ads.example.com if example.com is blocked as well), for this it needs an additional label reversal per feed and an extra pass over the merged blocklist. How much it saves depends on the selected feeds: curated feeds like hagezi or oisd are largely compressed already, feeds with many plain host entries are not. Some measurements on 2-core routers:

• Large feed selection with many host entries (1hosts, adguard, adguard_tracking, certpl, doh_blocklist, hagezi, ipfire_dbl, stevenblack, winspy), unbound, x86: the processing time rises from 78 to 109 seconds, but the blocklist shrinks from 2.94M to 1.07M entries (-64%). unbound loads it in 15 instead of 57 seconds and needs 400 MB instead of 1.1 GB RAM, including the restart of the DNS backend the whole run is even faster with adb_tld=1
• Small feed selection (anti_ad, hagezi, yoyo), dnsmasq, ARM: the processing time rises by 2 seconds, the blocklist shrinks from 113k to 82k entries (-27%), dnsmasq needs 2.3 MB less RAM
• Curated feeds only (hagezi pro, oisd big), dnsmasq: the processing time drops from 14.5 to 7.5 seconds with adb_tld=0, the blocklist grows by 1.3% (~4,700 entries)

Recommendation: keep the default. Only on slow CPUs with curated, already compressed feeds adb_tld=0 can save processing time at the cost of a slightly larger blocklist. To check it for your own feed selection, compare the number of blocked domains in the adblock status with and without the compression.

Use compressed swap (zram-swap) on low memory devices
The simplest way to survive the memory peak during feed processing is to give the kernel a compressed swap device and let it page out cold memory under pressure. The zram-swap package sets this up automatically at boot — no scripting, no changes to adblock, and adblock benefits transparently. Because the swap lives in compressed RAM rather than on flash, this incurs no flash wear.

apk add zram-swap

Size the swap device relative to your physical RAM — a sensible rule of thumb is half to one times the installed RAM. Note that the compressed pages occupy RAM themselves, so do not oversize it on very small devices:

The device size is configured in /etc/config/system via LuCI (System -> ZRam Settings) or via CLI:

uci set system.@system[0].zram_size_mb='128'
uci commit system
/etc/init.d/zram restart

A running zram device cannot be resized in place, so the restart is required for a changed size to take effect.
To make the kernel reclaim into zram more eagerly during the short processing peak, raise the swappiness and persist it across reboots, e.g.:

echo 'vm.swappiness=100' >> /etc/sysctl.conf
sysctl -p

Please note: zram covers the short memory peak during feed processing, it does not replace external storage for the backups and the shifted blocklist (see above): without it, they occupy RAM permanently, and the gzip compressed backups can't be compressed any further by zram. On very small devices (128 MB) compressed swap helps, but heavy swapping costs CPU — if RAM is truly marginal, the more honest fix is to activate fewer feeds.

Sensible choice of blocklists
Don`t just blindly activate too many feeds at once, sooner or later this will lead to OOM conditions.The following feeds are just my personal recommendation as an initial setup:

• adguard, adguard_tracking and certpl

In total, this feed selection blocks about 280K domains. It may also be useful to include compilations like hagezi, stevenblack or oisd.

DNS reporting, enable the GeoIP Map
adblock includes a powerful reporting tool on the DNS Report tab which shows the latest DNS statistics generated by tcpdump. To get the latest statistics always press the "Refresh" button.

In addition to a tabular overview adblock reporting includes a GeoIP map in a modal popup window/iframe that shows the geolocation of your own uplink addresses (in green) and the locations of blocked domains in red. To enable the GeoIP Map set the following option in "Advanced Report Settings" config tab: set adb_map to 1 to include the external components listed below and activate the GeoIP map.

To make this work, adblock uses the following external components:

• Leaflet is a lightweight open-source JavaScript library for interactive maps
• The free and quite fast IP Geolocation API to resolve the required IP/geolocation information (max. 45 blocked Domains per request)

The basemap is no longer pulled from a tile service. CARTO started to require an API key for the raster basemaps at basemaps.cartocdn.com and watermarks every unauthenticated tile request, and a key is bound to a single customer, so it cannot be shipped with a package that lands on every installation. adblock therefore draws the basemap from country outlines that come with luci-app-adblock: Natural Earth 1:110m, public domain and stripped of all attributes. The map page issues no request to a third party, works without a WAN connection and leaks no part of the admin session to a CDN. The outlines are enough to locate an IP, so the map does not zoom in beyond level 6 and labels the continents rather than the countries.

Optional: a higher detail basemap

The shipped 1:110m outlines are coarse around Scandinavia, the Greek islands and the smaller island states. If you want sharper coastlines, build the 1:50m variant with mapshaper and drop it next to the shipped file. LuCI looks for it on every map run and falls back to the shipped outlines when it is missing, no config option is involved:

curl -sSLo ne50.geojson https://raw.githubusercontent.com/nvkelso/natural-earth-vector/v5.1.2/geojson/ne_50m_admin_0_countries.geojson
mapshaper ne50.geojson -filter-fields -simplify 5% keep-shapes -o force precision=0.01 format=geojson world-50m.json
scp world-50m.json root@openwrt:/www/luci-static/resources/view/adblock/

The result is roughly 105 kB, about three times the shipped file. This file is not part of any package, so it is removed on sysupgrade unless you add its path to /etc/sysupgrade.conf, and it stays behind when luci-app-adblock is uninstalled.

DNS reporting, limit the tcpdump capture
adb_repfilter takes a regular tcpdump/BPF expression which is logically ANDed to the internal reporting port filter. It narrows the capture for every adb_repiface setting, not just for any, e.g. to skip a single noisy client or to limit the report to certain network segments.

The most common use case is a capture with adb_repiface set to any, where tcpdump also picks up DNS traffic on outbound interfaces, e.g. requests that originate from the router itself and are routed through a VPN client interface. Those packets are captured correctly, but they are redundant, they clutter the report and they consume the limited pcap ring buffer configured via adb_repchunkcnt and adb_repchunksize. Some examples:

Please note:

• the expression must not drop one direction of a DNS transaction. A report line is only emitted once the answer to a pending query has been seen, so filters like inbound, src net ... or dst port 53 compile fine but result in an empty report
• net 10.0.0.1 is not a subnet, without a prefix length libpcap assumes /32 and the expression becomes equivalent to host 10.0.0.1
• not host A or not host B does not skip both hosts, it only skips the traffic between A and B. Use not (host A or host B) instead
• address, network and port primitives work with every interface, but the vlan and ether primitives require an ethernet based capture. They are rejected with adb_repiface set to any (linux cooked mode) as well as on tunnel or ppp interfaces like wg0 or pppoe-wan
• the expression can only narrow the capture, additional ports have to be added via adb_repport
• a too narrow expression still compiles and tcpdump starts normally, it just yields an empty report. Keep that in mind when adb_repiface is changed while a filter is set, the active filter is part of the runtime status

External adblock test
In addition to the built‑in DNS reporting and GeoIP map, adblock users can verify the effectiveness of their configuration with an external test page. The Adblock Test provides a simple way to check whether your current adblock setup is working as expected. It loads a series of test elements (ads, trackers, and other resources) and reports whether they are successfully blocked by your configuration.

The test runs entirely in the browser and does not require additional configuration. For best results, open the page in the same environment where adblock is active and review the results displayed.

Firewall‑Based DNS Control
adblock provides several advanced firewall‑integrated features that allow you to enforce DNS policies directly at the network layer. These mechanisms operate independently of the local DNS resolver and ensure that DNS traffic follows your filtering rules, even when clients attempt to bypass them.

• Unfiltered external DNS Routing: routes DNS queries from selected devices or interfaces to an external unfiltered DNS resolver
• Filtered external DNS Routing: routes DNS queries from selected devices or interfaces to an external filtered DNS resolver
• Force DNS: blocks or redirects all external DNS traffic to ensure that clients use the local resolver

The DNS routing allows you to apply external DNS (unfiltered and/or filtered) to specific devices or entire network segments. DNS queries from these targets are transparently redirected to a chosen external resolver (IPv4 and/or IPv6):

• MAC‑based targeting for individual devices
• Interface/VLAN targeting for entire segments
• Separate IPv4/IPv6 resolver selection
• Transparent DNS redirection without client‑side configuration
  This mode is ideal for guest networks, IoT devices, or environments where certain clients require stricter/lesser DNS filtering.

force DNS ensures that all DNS traffic on your network by specific devices or entire network segments is processed by the local resolver. Any attempt to use external DNS servers is blocked or redirected.

• Blocks external DNS on port 53 and redirects DNS queries to the local resolver when appropriate
• Also prevents DNS bypassing by clients with hardcoded DNS settings on other ports, e.g. on port 853
  This mode guarantees that adblock’s filtering pipeline is always applied.

adblock's firewall rules are based on nftables in a separate isolated nftables table (inet adblock) and chains (prerouting), with MAC addresses stored in a nftables set. The configuration is carried out centrally in LuCI on the ‘Firewall Settings’ tab in adblock.

Remote DNS Allow (Temporary MAC‑Based Bypass)
This additional firewall feature lets selected client devices temporarily bypass local DNS blocking and use an external, unfiltered DNS resolver. It is designed for situations where a device needs short‑term access to content normally blocked by the adblock rules.

A lightweight CGI endpoint handles the workflow:

• The client opens the URL, e.g. http(s)://<ROUTER-IP>/cgi-bin/adblock (preferably transferred via QR code shown in LuCI)
• The script automatically detects the device’s MAC address
• If the MAC is authorized, the script displays the current status:
  • Not in the nftables set → option to request a temporary allow (“Bypass”)
  • Already active → shows remaining timeout
• When renewing, the CGI adds the MAC to an nftables Set with a per‑entry timeout

The CGI interface is mobile‑friendly and includes a LuCI‑style loading spinner during the renew process, giving immediate visual feedback while the nftables entry is created. All operations are atomic and safe even when multiple devices renew access in parallel.

Temporary DNS Bridging (Zero‑Downtime during DNS Restarts)
Adblock can optionally enable a temporary DNS bridging mode to avoid DNS downtime during DNS backend restarts.
When this feature is enabled, all DNS queries from LAN clients are briefly redirected to an external fallback resolver until the local DNS backend becomes available again. This ensures that DNS resolution continues to work seamlessly for all clients, even while adblock reloads blocklists or restarts the DNS service. Just set the options adb_nftbridge, adb_bridgednsv4 and adb_bridgednsv6 accordingly.

Jail mode (allowlist-only):
Enforces a strict allowlist‑only DNS policy in which only domains listed in the allowlist file are resolved, while every other query is rejected. This mode is intended for highly restrictive environments and depends on a carefully maintained allowlist, typically managed manually.

Download options
By default adblock uses the following pre-configured download options:

* curl: --connect-timeout 20 --retry-delay 10 --retry 4 --retry-max-time 80 --retry-all-errors --fail --silent --show-error --location -o
    * wget: --no-cache --no-cookies --timeout=20 --waitretry=10 --tries=5 --retry-connrefused -O
    * uclient-fetch: --timeout=20 -O

To override the default set adb_fetchretry, adb_fetchinsecure or globally adb_fetchparm to your needs.

Enable E-Mail notification via msmtp:
To use the email notification you have to install & configure the package msmtp.
Modify the file /etc/msmtprc:

[...]
defaults
auth on
tls on
tls_certcheck off
timeout 5
syslog LOG_MAIL
[...]
account adb_notify
host smtp.gmail.com
port 587
from [email protected]
user dev.adblock
password xxx

Finally enable E-Mail support, add a valid E-Mail receiver address in LuCI and setup an appropriate cron job.

Automatic adblock feed updates and E-Mail reports
For a regular, automatic update of the used feeds or other regular adblock tasks set up a cron job. Use reload here — start/restart would only restore the backups instead of fetching fresh feeds. In LuCI you find the cron settings under System => Scheduled Tasks. On the command line the cron file is located at /etc/crontabs/root:

Example 1

# update the adblock feeds every morning at 4 o'clock
00 04 * * * /etc/init.d/adblock reload

Example 2

# update the adblock feeds every hour
0 */1 * * * /etc/init.d/adblock reload

Example 3

# send an adblock E-Mail report every morning at 3 o'clock
00 03 * * * /etc/init.d/adblock report mail

Change/add adblock feeds
The adblock default blocklist feeds are stored in an external JSON file /etc/adblock/adblock.feeds. This file is shipped with the package and is overwritten on every package update, so never edit it directly. All of your custom changes belong in the separate JSON file /etc/adblock/adblock.custom.feeds (empty by default), which is preserved across updates. It's recommended to use the LuCI based Custom Feed Editor (Custom Feed Editor tab), which validates the JSON for you.

Please note: if /etc/adblock/adblock.custom.feeds exists and is non-empty, it is loaded instead of the shipped adblock.feeds — it replaces the feed set, it does not merge with it. A custom feed file must therefore contain every feed you want active, not just your additions. The Custom Feed Editor handles this for you by working on a full copy.

A feed is a single JSON object, keyed by a unique feed name (no spaces, no special characters). Example:

[...]
	"stevenblack": {
		"url": "https://raw.githubusercontent.com/StevenBlack/hosts/master/",
		"rule": "feed 0.0.0.0 2",
		"size": "VAR",
		"descr": "compilation"
	},
	[...]

The object supports the following fields:

The rule field
The rule consists of max. 4 individual, space separated parameters:

1. type: always feed (required). adblock only supports the feed type for external sources; any source whose rule does not start with feed is skipped.
2. prefix: an optional search term (a literal string, not a regex) that a line must contain to be treated as a valid entry. Use it to pick the relevant rows of a hosts-style file, e.g. 0.0.0.0. Omit it for a plain list with one bare domain per line.
3. column: the 1-based column that holds the domain within a matching line, e.g. 2 for a 0.0.0.0 example.com hosts file or 1 for a bare list (required). When no prefix is used, give the column directly, e.g. feed 1.
4. separator: an optional field separator; default is the whitespace character class [[:space:]]+. Pass a literal character such as , for comma-separated sources.

Examples:

• feed 1 — plain list, one domain per line, domain in column 1
• feed 0.0.0.0 2 — hosts-style file, keep only 0.0.0.0 lines, domain in column 2
• feed 1 , — comma-separated source, domain in the first field

Category-based feeds (size VAR)
The feeds marked VAR in the feed table (1hosts, hagezi, ipfire_dbl, stevenblack, utcapitole) are built-in feeds that require an additional category selection via the dedicated options adb_hst_feed, adb_hag_feed, adb_ipf_feed, adb_stb_feed and adb_utc_feed (or the LuCI feed configuration). For these, the url is a base URL to which the selected category is appended at download time. This category mechanism is wired to those specific feed names in the backend, so it cannot be reused for arbitrary new feeds — a custom feed you add yourself should point url at a single, complete list URL.

After editing /etc/adblock/adblock.custom.feeds, reload adblock (/etc/init.d/adblock reload) and check the Log View tab (or logread -e adblock-). With adb_debug enabled, a malformed JSON object or a wrong column/separator typically shows up there as a feed that produces zero domains.

Troubleshooting & debug options Copy Chapter

Adblock provides an optional debug mode that writes diagnostic information to the system log and captures internal error output in a dedicated error logfile - by default located in the adblock base directory as /tmp/adb_error.log. The log file is automatically cleared at the beginning of each run. Under normal conditions, all error messages are discarded to keep regular runs clean and silent. To enable debug mode, set the option adb_debug to 1. When enabled, the script produces significantly more log output to assist with troubleshooting.

Whenever you encounter adblock related processing problems, please enable debug logging, restart adblock and check the Log View tab in LuCI (or the syslog via logread -e adblock-).

Support Copy Chapter

Please join the adblock discussion in this forum thread or contact me by mail [email protected]

Removal Copy Chapter

Stop all adblock related services with /etc/init.d/adblock stop and remove the adblock package if necessary, e.g.:

/etc/init.d/adblock stop
apk del luci-app-adblock adblock
rm -f /etc/config/adblock
rm -rf /tmp/luci-*

Donations Copy Chapter

You like this project - is there a way to donate? Generally speaking "No" - I have a well-paying full-time job and my OpenWrt projects are just a hobby of mine in my spare time.

If you still insist to donate some bucks ...

• I would be happy if you put your money in kind into other, social projects in your area, e.g. a children's hospice
• Let's meet and invite me for a coffee if you are in my area, the “Markgräfler Land” in southern Germany or in Switzerland (Basel)
• Send your money to my PayPal account and I will collect your donations over the year to support various social projects in my area

No matter what you decide - thank you very much for your support!

Have fun!
Dirk

Overview (`net/apfree-wifidog/README.md`) Copy Section

ApFree WiFiDog: A high performance captive portal solution for HTTP(s) Copy Chapter

ApFree WiFiDog is a high performance captive portal solution for HTTP(s), which mainly used in (LEDE & OpenWrt) platform.

中文介绍

Enhancement of apfree-wifidog Copy Chapter

In fact, the title should be why we choose apfree-wifidog, the reason was the following:

Stable

apfree-wifidog was widely used in tens of thousands device, which were running in business scene. In order to improve its stable, we rewrite all iptables rule by api instead of fork call, which will easily cause deadlock in multithread-fork running environment. we also re-write the code and replace libhttpd (which is unmaintained for years) with libevent

Performance

apfree-wifidog's http request-response is more quick, u can find statistic data in our test document

HTTPs redirect

apfree-wifidog support https redirect, in current internet environment, captive portal solution without supporting https redirect will become unsuitable gradually

More features

apfree-wifidog support mac temporary-pass, ip,domain,pan-domain,white-mac,black-mac rule and etc. all these rules can be applied without restarting wifidog

MQTT support

by enable mqtt support, u can remotely deliver such as trusted ip, domain and pan-domain rules to apfree wifidog

Compilable with wifidog protocol

u don't need to modify your wifidog authentication server to adapt apfree-wifidog; if u have pression on server-side, apfree wifidog's improved protocol can greatly relieve it, which disabled by default

Getting started Copy Chapter

before starting apfree-wifidog, we must know how to configure it. apfree-wifidog use OpenWrt standard uci config system, all your apfree-wifidog configure information stored in /etc/confg/wifidogx, which will be parsed by /etc/init.d/wifidogx to /tmp/wifidog.conf, apfree-wifidog's real configure file is /tmp/wifidog.conf

The default apfree-wifidog UCI configuration file like this:

config wifidog
    option  gateway_interface   'br-lan'
    option  auth_server_hostname    'wifidog.kunteng.org.cn'
    option  auth_server_port    443
    option  auth_server_path    '/wifidog/'
    option  check_interval      60
    option  client_timeout      5
    option  apple_cna           1
    option  thread_number       5
    option  wired_passed        0
    option  enable      0

auth_server_hostname was apfree-wifidog auth server, it can be domain or ip; wifidog.kunteng.org.cn is a free auth server we provided, it was also open source

apple_cna 1 apple captive detect deceive; 2 apple captive detect deceive to disallow portal page appear

wired_passed means whether LAN access devices need to auth or not, value 1 means no need to auth

enable means whether start apfree-wifidog when we executed /etc/init.d/wifidogx start, if u wanted to start apfree-wifidog, you must set enable to 1 before executing /etc/init.d/wifidogx start

How to support https redirect Copy Section

In order to support https redirect, apfree-wifidog need x509 pem cert and private key, u can generate yourself like this:

PX5G_BIN="/usr/sbin/px5g"
OPENSSL_BIN="/usr/bin/openssl"
APFREE_CERT="/etc/apfree.crt"
APFREE_KEY="/etc/apfree.key"

generate_keys() {
    local days bits country state location commonname

    # Prefer px5g for certificate generation (existence evaluated last)
    local GENKEY_CMD=""
    local UNIQUEID=$(dd if=/dev/urandom bs=1 count=4 | hexdump -e '1/1 "%02x"')
    [ -x "$OPENSSL_BIN" ] && GENKEY_CMD="$OPENSSL_BIN req -x509 -sha256 -outform pem -nodes"
    [ -x "$PX5G_BIN" ] && GENKEY_CMD="$PX5G_BIN selfsigned -pem"
    [ -n "$GENKEY_CMD" ] && {
        $GENKEY_CMD \
            -days ${days:-730} -newkey rsa:${bits:-2048} -keyout "${APFREE_KEY}.new" -out "${APFREE_CERT}.new" \
            -subj /C="${country:-CN}"/ST="${state:-localhost}"/L="${location:-Unknown}"/O="${commonname:-ApFreeWiFidog}$UNIQUEID"/CN="${commonname:-ApFreeWiFidog}"
        sync
        mv "${APFREE_KEY}.new" "${APFREE_KEY}"
        mv "${APFREE_CERT}.new" "${APFREE_CERT}"
    }
}

or when u start /etc/init.d/wifidogx start, it will generate it automatically

For more information, please refer to the upstream project page

Overview (`net/banip/README.md`) Copy Section

banIP - ban incoming and outgoing IP addresses/subnets via Sets in nftables

Table of Contents Copy Chapter

• Description
• Quick Start
• Main Features
• Prerequisites
• Installation and Usage
• banIP CLI interface
• banIP config options
• Examples
• Best practise and tweaks
• Troubleshooting & debug options
• Support
• Removal
• Donations

Description Copy Chapter

IP address blocking is commonly used to protect against brute force attacks, prevent disruptive or unauthorized address(es) from access or it can be used to restrict access to or from a particular geographic area — for example. Further more banIP scans the log file via logread and bans IPs that make too many password failures, e.g. via ssh.

Quick Start Copy Chapter

For a typical setup these few steps are enough to get banIP up and running — see the sections below for details:

1. Install the LuCI companion package: apk update && apk add luci-app-banip (this pulls in the banip backend as a dependency).
2. Open LuCI under Services → banIP, tick Enabled and (recommended) set a Startup Trigger Interface to your WAN interface(s).
3. Activate a small, sensible feed selection to start with, e.g. cinsscore, debl, turris and doh in their default chains (≈20K IPs).
4. Start and verify the service:

/etc/init.d/banip start
/etc/init.d/banip status

Please note: don't blindly enable (too) many feeds at once — on low memory devices this will sooner or later lead to OOM conditions.

Main Features Copy Chapter

• banIP supports the following fully pre-configured IP blocklist feeds (free for private usage, for commercial use please check their individual licenses).
  Please note: By default, each feed blocks the packet flow in the chain(s) shown in the table below. Inbound combines the chains WAN-Input and WAN-Forward, Outbound represents the LAN-FWD chain:

  • WAN-INP chain applies to packets from internet to your router
  • WAN-FWD chain applies to packets from internet to other local devices (not your router)
  • LAN-FWD chain applies to local packets going out to the internet (not your router)

  How to read the default direction: most reputation feeds list the source IPs of attackers, scanners and spammers — those are blocked inbound, because the unwanted connection is initiated from the internet towards you. A second group of feeds lists IPs that your own clients should never talk to (malware hosting, command-and-control servers, threat/DoH/DNS endpoints); those are blocked outbound in the LAN-FWD chain, because the connection is initiated from your LAN. Feeds where both risks apply (e.g. spamhaus, emerging threats, tor, proxy, vpn) default to both directions. This distinction matters: a feed of malware-download or C2 IPs in the inbound chain alone provides little protection, because your LAN client is the one initiating the connection — see the country/asn note in the Best practise section for the common "block a country" case.

  The listed standard assignments can be changed to your needs under the Feed/Set Settings config tab (options ban_feedin, ban_feedout, ban_feedinout and ban_feedreset).

• Zero-conf like automatic installation & setup, usually no manual changes needed
• All Sets are handled in a separate nft table/namespace banIP
• Full IPv4 and IPv6 support
• Supports nft atomic Set loading
• Supports blocking by ASN numbers and by iso country codes
• Block countries dynamically by Regional Internet Registry (RIR), e.g. all countries related to ARIN. Supported service regions are: AFRINIC, ARIN, APNIC, LACNIC and RIPE
• Supports local allow- and blocklist with MAC/IPv4/IPv6 addresses or domain names
• Supports concatenation of local MAC addresses with IPv4/IPv6 addresses, e.g. to enforce dhcp assignments
• All local input types support ranges in CIDR notation
• Auto-add the uplink subnet or uplink IP to the local allowlist
• Prevent common ICMP, UDP and SYN flood attacks and drop spoofed tcp flags & invalid conntrack packets (DoS attacks) in an additional prerouting chain
• Provides a background log monitor to ban unsuccessful login attempts in real-time (like fail2ban, crowdsec etc.) with three-tier IP deduplication, dynamic cache management and optional RDAP-based subnet blocking
• Auto-add unsuccessful LuCI, Asterisk or ssh login attempts to the local blocklist
• Auto-add entire subnets to the blocklist Set based on an additional RDAP request with the monitored suspicious IP
• Fast feed processing as they are handled in parallel as background jobs (on capable multi-core hardware)
• Per feed it can be defined whether the inbound chain (wan-input, wan-forward) or the outbound chain (lan-forward) should be blocked
• Automatic blocklist backup & restore, the backups will be used in case of download errors or during startup
• Automatically selects one of the following download utilities with ssl support: curl, uclient-fetch or full wget
• Provides HTTP ETag support to download only resources that have been updated on the server side, to speed up banIP reloads and to save bandwidth
• Supports an allowlist only mode, this option restricts the internet access only to specific, explicitly allowed IP segments
• Optionally screens the allowed IP segments in allowlist only mode as well, i.e. the log monitor may ban attackers from an explicitly allowed segment while the local allowlist entries stay exempt (see ban_monitorallowed)
• Supports external allowlist URLs to reference additional IPv4/IPv6 feeds
• Optionally always allow certain protocols/destination ports in the inbound chain
• Deduplicate IPs across all Sets (single IPs only, no intervals)
• Implements BCP38 ingress filtering to prevent IP address spoofing
• Provides comprehensive runtime information
• Provides a detailed Set report, incl. a map that shows the geolocation of your own uplink addresses (in green) and the location of potential attackers (in red), drawn from local country outlines without any tile service
• Provides a Set search engine for certain IPs
• Feed parsing by fast & flexible regex rulesets
• Minimal status & error logging to syslog, enable debug logging to receive more output
• Procd based init system support (start/stop/restart/reload/status/report/search/content)
• Procd network interface trigger support
• Add new or edit existing banIP feeds on your own with the LuCI integrated custom feed editor
• Supports destination port & protocol limitations for external feeds (see the feed list above). To change the default assignments just use the custom feed editor
• Supports allowing / blocking of certain VLAN forwards
• Provides an option to transfer logging events on remote servers via cgi interface

Prerequisites Copy Chapter

• OpenWrt, latest stable release or a development snapshot with nft/firewall 4 support
• A download utility with SSL support: curl, full wget or uclient-fetch with one of the libustream-* SSL libraries, the latter one doesn't provide support for ETag HTTP header
• A certificate store like ca-bundle, as banIP checks the validity of the SSL certificates of all download sites by default
• For E-Mail notifications you need to install and setup the additional msmtp package

Please note:

• Devices with less than 256MB of RAM are not supported
• After system upgrades it's recommended to start with a fresh banIP default config
• Only reload actually refreshes the feeds (ETag check plus download of changed feeds). start, restart — and boot/resume — restore the existing blocklist backups and only download feeds that have no backup yet; they do not re-fetch already cached feeds. To update your blocklists (e.g. from a cron job) always use reload.

Installation and Usage Copy Chapter

• Update your router's apk repository (apk update)
• Install the LuCI companion package luci-app-banip which also installs the main banIP package as a dependency
• Enable the banIP system service (System -> Startup) and enable banIP itself (banIP -> General Settings)
• It's strongly recommended to use the LuCI frontend to easily configure all aspects of banIP, the application is located in LuCI under the Services menu
• It's also recommended to configure a Startup Trigger Interface to depend on your WAN interface events during boot or restart of your router. Listing IPv6 interfaces (wan6) is fine as well: an interface event that only changed the uplink addresses refreshes the auto-allowed uplink entries in place, without a full banIP restart. This keeps the allowlist in sync with a dynamic IPv6 prefix
• To be able to use banIP in a meaningful way, you must activate the service and possibly also activate a few blocklist feeds
• If you're using a complex network setup, e.g. special tunnel interfaces, then untick the Auto Detection option under the General Settings tab and set the required options manually
• Start the service with /etc/init.d/banip start and check everything is working by running /etc/init.d/banip status, also check the Processing Log tab

banIP CLI interface Copy Chapter

• All important banIP functions are accessible via CLI, too. If you're going to configure banIP via CLI, edit the config file /etc/config/banip and enable the service, add pre-configured feeds and add/change other options to your needs, see the options reference table below.

~# /etc/init.d/banip
Syntax: /etc/init.d/banip [command]

Available commands:
	start           Start the service
	stop            Stop the service
	restart         Restart the service
	reload          Reload configuration files (or restart if service does not implement reload)
	enable          Enable service autostart
	disable         Disable service autostart
	enabled         Check if service is started on boot
	report          [text|json|mail|gen] Print banIP related Set statistics
	search          [<IPv4 address>|<IPv6 address>] Check if an element exists in a banIP Set
	content         [<Set name>] [true|false] Listing of all or only elements with hits of a given banIP Set
	running         Check if service is running
	status          Service status
	trace           Start with syscall trace
	info            Dump procd service info

The report sub-command accepts an output mode: text (default, human-readable table), json (machine-readable output, incl. GeoIP map data when ban_map=1), mail (send the report via msmtp) and gen (regenerate the report data files in the background, used by the LuCI frontend).

banIP config options Copy Chapter

Examples Copy Chapter

banIP report information

/* Detailed source-code truncated for AI context efficiency. */

banIP runtime information

~# /etc/init.d/banip status
::: banIP runtime information
  + status            : active (nft: ✔, monitor: ✔)
  + frontend_ver      : 1.9.0-r1
  + backend_ver       : 1.9.0-r1
  + element_count     : 111 582 (chains: 7, sets: 21, rules: 50)
  + active_feeds      : allowlist.v4MAC, allowlist.v6MAC, allowlist.v4, allowlist.v6, cinsscore.v4, debl.v4, country.v6, debl.v6, doh.v4, doh.v6, spamhaus.v4, ipthreat.v4, country.v4, spamhaus.v6, threat.v4, turris.v4, turris.v6, blocklist.v4MAC, blocklist.v6MAC, blocklist.v4, blocklist.v6
  + active_devices    : trigger: wan / wan: pppoe-wan / wan-if: wan, wan_6 / vlan-allow: - / vlan-block: -
  + active_uplink     : 46.167.33.169, 2a04:5700:304:ea66:e1fa:9a7f:ff78:ec41
  + nft_info          : ver: 1.1.6-r4, priority: -100, policy: performance, loglevel: warn, expiry: 2h, limit (icmp/syn/udp): 25/10/100, loglimit (rate/burst): 10/5
  + run_info          : base: /mnt/data/banIP, backup: /mnt/data/banIP/backup, report: /mnt/data/banIP/report, error: /mnt/data/banIP/error
  + run_flags         : auto: ✔, proto (4/6): ✔/✔, bcp38: ✔, log (pre/in/out): ✘/✘/✘, count: ✔, dedup: ✔, split: ✘, custom feed: ✘, allowed only: ✘, debug: ✔
  + last_run          : mode: restart, date / time: 2026-09-19 15:27:29, duration: 0m 28s, memory: 1122.99 MB available
  + system_info       : cores: 4, log: logread, fetch: curl, Bananapi BPI-R3, mediatek/filogic, OpenWrt SNAPSHOT (r36370-5369699684)

banIP search information

~# /etc/init.d/banip search 8.8.8.8
:::
::: banIP Search
:::
    Looking for IP '8.8.8.8' on 2025-01-13 22:13:36
    ---
    IP found in Set 'country.v4'
    IP found in Set 'doh.v4'

banIP Set content information
List all elements of a given Set with hit counters, e.g.:

~# /etc/init.d/banip content turris.v4
:::
::: banIP Set Content
:::
    List elements of the Set 'turris.v4' on 2025-06-08 23:28:55
    ---
1.4.228.135, packets:  0
1.23.16.3, packets:  0
1.33.35.42, packets:  0
1.33.231.132, packets:  0
1.34.29.158, packets:  0
1.34.231.106, packets:  0
1.52.91.174, packets:  0
1.64.149.142, packets:  0
1.69.243.13, packets:  0
1.70.139.250, packets:  0
1.70.171.246, packets:  0
1.82.191.114, packets:  0
[...]

List only elements with hits of a given Set with hit counters, e.g.:

~# /etc/init.d/banip content turris.v4 true
:::
::: banIP Set Content
:::
    List elements of the Set 'turris.v4' on 2025-06-08 23:30:59
    ---
74.50.211.178, packets:  1
109.205.213.115, packets:  18
109.205.213.123, packets:  35
109.205.213.248, packets:  29
109.205.213.250, packets:  20
109.205.213.252, packets:  30
122.222.152.65, packets:  1
186.91.25.141, packets:  2
190.203.106.113, packets:  2
200.123.238.20, packets:  1

Best practise and tweaks Copy Chapter

Recommendation for low memory systems
nftables supports the atomic loading of firewall rules (incl. elements), which is cool but unfortunately is also very memory intensive. To reduce the memory pressure on low memory systems (i.e. those with 256-512MB RAM), you should optimize your configuration with the following options:

• point ban_basedir, ban_reportdir, ban_backupdir and ban_errordir to an external usb drive or ssd
• set ban_cores to 1 (only useful on a multicore system) to force sequential feed processing. The autodetected value is additionally capped to the available memory; a manually set value is always used as-is and is never lowered
• set ban_splitsize e.g. to 1024 to split the load of an external Set after every 1024 lines/elements
• set ban_nftcount to 0 to deactivate the CPU- and memory-intensive creation of counter elements at chain / Set level. With this setting, all packet counters are disabled, the Set Reporting will show zero values for these even when the protection rules are actively dropping traffic. Only the DoS protection counters (syn-flood, udp-flood, icmp-flood, etc.) are always enabled.

Sensible choice of blocklists
The following feeds are just my personal recommendation as an initial setup:

• cinsscore, debl, turris and doh in their default chains

In total, this feed selection blocks about 20K IP addresses. It may also be useful to include some countries to the country feed.
Please note: don't just blindly activate (too) many feeds at once, sooner or later this will lead to OOM conditions.

Feed direction (inbound vs. outbound) — and the country/ASN case
This is the single most common source of confusion, so it's worth understanding the model before you pick feeds.

banIP filters on the connection level (source/destination IP), not on content. The default chain of a feed therefore has to match who initiates the unwanted connection:

• Inbound (WAN-Input + WAN-Forward): blocks connections that come from the internet towards you. This is the right direction for the large majority of reputation feeds, which list the source IPs of attackers, scanners, brute-forcers and spam senders (cinsscore, debl, dshield, firehol*, bruteforceblock, uceprotect*, …). A fail2ban-style feed only makes sense inbound.
• Outbound (LAN-Forward): blocks connections your own LAN clients initiate towards a listed IP. This is the right direction for feeds that list destinations your devices should never reach: malware-download hosts, command-and-control servers, DoH/DNS bypass endpoints and threat IPs (doh, dns, hagezi, feodo, urlhaus, urlvir, webclient).
• Both: feeds where the risk genuinely exists in both directions default to inout (spamhaus, threat, threatview, tor, proxy, vpn, vpndc).

The classic mistake: enabling a malware-URL / C2 feed like urlhaus in the inbound chain and expecting it to stop a LAN client from downloading malware. It won't — the client is the one opening the connection, so only the outbound chain can intercept it. These feeds ship with sensible defaults (outbound or both), but if you maintain your own custom feeds, keep this rule of thumb in mind.

The country/ASN case: the country and asn feeds default to the inbound chain. This blocks traffic from the selected country/ASN towards you — the typical "keep attackers from region X out" use case. If your goal is instead to stop your own clients from reaching a country or ASN (the recurring "block all connections to country X" request), inbound alone does nothing for you. Switch the feed to the outbound or both chain:

• via LuCI: Feed/Set Settings → move the feed into Outbound or Inbound + Outbound
• via CLI in /etc/config/banip:

# block outbound connections to the selected countries as well as inbound
list ban_feedinout 'country'

# or restrict the country feed exclusively to the outbound (LAN-FWD) chain
list ban_feedout 'country'

Be aware that bidirectional country blocking on large countries quickly inflates element counts and memory usage; consider ban_countrysplit/ban_asnsplit and the low-memory tweaks above.

Log Terms for logfile parsing
Like fail2ban and crowdsec, banIP supports logfile scanning and automatic blocking of suspicious attacker IPs.
In the default config only the log terms to detect failed login attempts via dropbear and LuCI are in place. The following search patterns have been tested as well:

dropbear : 'Exit before auth from'
LuCI     : 'luci: failed login'
sshd1    : 'error: maximum authentication attempts exceeded'
sshd2    : 'sshd.*Connection closed by.*\[preauth\]'
asterisk : 'SecurityEvent=\"InvalidAccountID\".*RemoteAddress='
openvpn  : 'TLS Error: could not determine wrapping from \[AF_INET\]'
AdGuard  : 'AdGuardHome.*\[error\].*/control/login: from ip'
Remote   : 'received a suspicious remote IP'

Source IP position
For every matched line banIP picks the attacker's address out of the log entry. By default it uses the last IP in the line, which is correct for all login-style formats above: the service always appends the real remote address as the final field, after any user-supplied data (such as a login name). This stays robust even when an attacker puts an IP-like string into a username or similar field.

Some formats instead lead with the source IP — most notably web-server access logs, where the client address is the first field. For those, prefix the term with first::

nginx : 'first:"[A-Z]+ /wp-login\.php[^"]*" 40[13]'

The first:/last: prefix is parsed off before matching and applies only to that single term, so terms with different anchors can be mixed freely.

Please note: first: only fits formats where the source IP is genuinely the first address in the line. Do not use it for Suricata fast.log (its leading [1:2013:7] signature id) or netfilter LOG lines (their leading MAC= field), as that leading field would be picked instead of the source — keep those on the default last.

You find the Log Terms option in LuCI under the Log Settings tab. Feel free to add more log terms to meet your needs and protect additional services.

Allow-/Blocklist handling
banIP supports local allow- and block-lists, MAC/IPv4/IPv6 addresses (incl. ranges in CIDR notation) or domain names. These files are located in /etc/banip/banip.allowlist and /etc/banip/banip.blocklist.
Unsuccessful login attempts or suspicious requests will be tracked and added to the local blocklist (see the ban_autoblocklist option). The blocklist behaviour can be further tweaked with the ban_nftexpiry option.
Elements added by the log monitor, including the RDAP ranges of an offending address, expire after ban_nftexpiry, but every new hit within an existing range resets its timeout. As the Sets use auto-merge, overlapping or adjacent ranges are also combined into a single larger element. A network under continuous attack can therefore stay in the blocklist far beyond the configured expiry and grow over time - this is intended behaviour, not a stale entry.
Depending on the options ban_autoallowlist and ban_autoallowuplink the uplink subnet or the uplink IP will be added automatically to local allowlist.
Entries in CIDR notation always refer to the whole network - set host bits are masked by nftables, e.g. 192.168.1.5/24 ends up as 192.168.1.0/24 in the Set and 2001:db8::e65f:1:2:3/64 as 2001:db8::/64. To allow or block a single host omit the prefix length or use /32 resp. /128.
Furthermore, you can reference external Allowlist URLs with additional IPv4 and IPv6 feeds (see ban_allowurl).
Both local lists also accept domain names as input to allow IP filtering based on these names. The corresponding IPs (IPv4 & IPv6) will be extracted and added to the Sets.

Allowlist-only mode
banIP supports an "allowlist only" mode. This option restricts Internet access only to certain, explicitly permitted IP segments - and blocks access to the rest of the Internet. All IPs that are not listed in the allowlist or in the external allowlist URLs are blocked. In this mode it might be useful to limit the allowlist feed to the inbound chain, to still allow outbound communication to the rest of the world.

In this mode the allowlist Sets define the permitted address scope, they do not act as an accept precedence - the blocklist Set is still evaluated and still applies. By default the log monitor nevertheless treats every allowlisted IP as exempt, therefore attackers coming from a permitted segment (e.g. a country-wide external allowlist feed) are never banned. Enable the ban_monitorallowed option to restrict the log monitor to the entries of the local allowlist. banIP then processes an additional local feed which provides the allowlist.local.v4/allowlist.local.v6 Sets, built from /etc/banip/banip.allowlist only - including the automatically added uplink. These Sets are not referenced by any rule, they are solely used by the log monitor: local entries stay exempt, IPs which are merely covered by an external allowlist feed can be banned. This allows a "permit my own country, but still screen it" setup. The option has no effect unless ban_allowlistonly is enabled, and the additional Sets are removed automatically as soon as it is switched off.

External feeds are skipped in this mode as far as they are redundant: the allowlist emits an inverted and therefore terminal drop rule in every chain it covers, so a feed rule in exactly these chains can never match. With the default allowlist direction all external feeds are skipped. If the allowlist is limited to a single chain - e.g. to the inbound chain - only the feeds of that chain are skipped, feeds which also cover the opposite chain are still processed.

MAC/IP-binding
banIP supports concatenation of local MAC addresses/ranges with IPv4/IPv6 addresses, e.g. to enforce dhcp assignments or to free connected clients from outbound blocking.
The following notations in the local allow- and block-list are supported:

MAC-address only:
C8:C2:9B:F7:80:12                                  => this will be populated to the v4MAC- and v6MAC-Sets with the IP-wildcards 0.0.0.0/0 and ::/0

MAC-address range:
C8:C2:9B:F7:80:12/24                               => this populate the MAC-range C8:C2:9B:00:00:00", "C8:C2:9B:FF:FF:FF to the v4MAC- and v6MAC-Sets with the IP-wildcards 0.0.0.0/0 and ::/0

MAC-address with IPv4 concatenation:
C8:C2:9B:F7:80:12 192.168.1.10                     => this will be populated only to v4MAC-Set with the certain IP, no entry in the v6MAC-Set

MAC-address with IPv6 concatenation:
C8:C2:9B:F7:80:12 2a02:810c:0:80:a10e:62c3:5af:f3f => this will be populated only to v6MAC-Set with the certain IP, no entry in the v4MAC-Set

MAC-address with IPv4 and IPv6 concatenation:
C8:C2:9B:F7:80:12 192.168.1.10                     => this will be populated to v4MAC-Set with the certain IP
C8:C2:9B:F7:80:12 2a02:810c:0:80:a10e:62c3:5af:f3f => this will be populated to v6MAC-Set with the certain IP

MAC-address with IPv4 and IPv6 wildcard concatenation:
C8:C2:9B:F7:80:12 192.168.1.10                     => this will be populated to v4MAC-Set with the certain IP
C8:C2:9B:F7:80:12                                  => this will be populated to v6MAC-Set with the IP-wildcard ::/0

MAC-address logging in nftables
The MAC-address logging format in nftables is a little bit unusual. It is generated by the kernel's NF_LOG module and places all MAC-related data into one flat field, without separators or labels. For example, the field MAC=7e:1a:2f:fc:ee:29:68:34:21:1f:a7:b1:08:00 is actually a concatenation of the following:

[Source MAC (6 bytes)] + [Destination MAC (6 bytes)] + [EtherType (2 bytes)]
7e:1a:2f:fc:ee:29 → the source MAC address
68:34:21:1f:a7:b1 → the destination MAC address
08:00 → the EtherType for IPv4 (0x0800)

BCP38
BCP38 (Best Current Practice, RFC 2827) defines ingress filtering to prevent IP address spoofing. In practice, this means:

• dropping packets arriving on the WAN whose source address is not valid or routable via that interface
• dropping packets leaving LAN => WAN whose source address does not belong to the local/internal prefixes

In banIP, the BCP38 implementation uses nftables’ FIB lookup to enforce this. It checks whether the packet’s source address is not valid for the incoming interface or whether the routing table reports no route for this source on this interface. Packets that fail this check are dropped.

Reporting Counter behavior
The ban_nftcount option globally controls all Reporting counters in the banIP table — both per-Set element counters and chain rule counters. Default is 0 (disabled) to keep memory usage and CPU overhead low on constrained devices. Only the DoS protection counters (cnt_synflood, cnt_udpflood, cnt_icmpflood, cnt_tcpinvalid, cnt_ctinvalid, cnt_bcp38) become always populated and visible in /etc/init.d/banip report.

When enabled (ban_nftcount=1):

• every Set element gets its own packet/byte counter (memory cost: ~16 bytes per element, so ~1.6 MB for a 100k-element feed)
• all chain rules count packets and bytes
• the GeoIP Map (ban_map=1) becomes available, as it requires per-element counters to identify hit IPs

When disabled (ban_nftcount=0):

• memory footprint is minimal, suitable for low memory routers
• the Set Reporting still works structurally, but packet counts will all read as zero
• the GeoIP Map cannot be enabled

For most modern routers with ≥512 MB RAM, enabling ban_nftcount is recommended for full visibility into what banIP is actually blocking.

Log Limit / Options
All log rules (prerouting flood protection, inbound and outbound feeds) share a single nft limit named loglimit. The default of 10/second with burst 5 is intentionally aligned with typical kernel printk rate limits, so banIP log messages are not dropped by the kernel. Tune via ban_logratelimit and ban_logburstlimit accordingly if you have adjusted the kernel defaults. Set the ban_logratelimit to 0 to disable rate limiting entirely, e.g. when using ulogd or other userspace log handlers without printk constraints.

Set reporting, enable the GeoIP Map
banIP includes a powerful reporting tool on the Set Reporting tab which shows the latest NFT banIP Set statistics. To get the latest statistics always press the "Refresh" button.
In addition to a tabular overview banIP reporting includes a GeoIP map in a modal popup window/iframe that shows the geolocation of your own uplink addresses (in green) and the locations of potential attackers (in red). To enable the GeoIP Map set the following options (in "Feed/Set Settings" config tab):

• set ban_nftcount to 1 to enable the nft counter for every Set element
• set ban_map to 1 to include the external components listed below and activate the GeoIP map

To make this work, banIP uses the following external components:

• Leaflet is a lightweight open-source JavaScript library for interactive maps
• The free and quite fast IP Geolocation API to resolve the required IP/geolocation information

The basemap is no longer pulled from a tile service. CARTO started to require an API key for the raster basemaps at basemaps.cartocdn.com and watermarks every unauthenticated tile request, and a key is bound to a single customer, so it cannot be shipped with a package that lands on every installation. banIP therefore draws the basemap from country outlines that come with luci-app-banip: Natural Earth 1:110m, public domain, stripped of all attributes and simplified to 36 kB. No tile service is contacted anymore, but the map page still loads the Leaflet library from unpkg.com (integrity-checked via SRI and requested without cookies), so it needs a WAN connection. The outlines are enough to locate an IP, so the map does not zoom in beyond level 6 and labels the continents rather than the countries.

Optional: a higher detail basemap

The shipped 1:110m outlines are coarse around Scandinavia, the Greek islands and the smaller island states. If you want sharper coastlines, build the 1:50m variant with mapshaper and drop it next to the shipped file. LuCI looks for it on every map run and falls back to the shipped outlines when it is missing, no config option is involved:

curl -sSLo ne50.geojson https://raw.githubusercontent.com/nvkelso/natural-earth-vector/v5.1.2/geojson/ne_50m_admin_0_countries.geojson
mapshaper ne50.geojson -filter-fields -simplify 5% keep-shapes -o force precision=0.01 format=geojson world-50m.json
scp world-50m.json root@openwrt:/www/luci-static/resources/view/banip/

The result is roughly 105 kB, about three times the shipped file. Please note: this file is not part of any package, so it is removed on sysupgrade unless you add its path to /etc/sysupgrade.conf, and it stays behind when luci-app-banip is uninstalled.

Please note: the free ip-api.com batch endpoint is rate limited to 15 requests per minute per source IP. Requests beyond that limit are throttled with HTTP 429, and constantly exceeding the limit gets the IP banned for an hour — in both cases the affected part of the map stays empty and banIP logs an info message. To stay below the limit banIP collects the top listed elements of all Sets, deduplicates them and resolves them in batch requests of 100 IPs each (the maximum the endpoint accepts), capped at 15 requests per report run. Elements beyond ~1500 are left out of the map and banIP logs an info message. A report regenerated within 60 seconds of the last geo lookup reuses its map data instead of querying the service again. Please note that other clients behind the same public IP count against the same limit.

CGI interface to receive remote logging events
banIP ships a basic cgi interface in /www/cgi-bin/banip to receive remote logging events (disabled by default). The cgi interface evaluates logging events via GET or POST request (see examples below). To enable the cgi interface set the following options:

• set ban_remotelog to 1 to enable the cgi interface
• set ban_remotetoken to a secret transfer token, allowed token characters consist of '[A-Za-z]', '[0-9]', '.' and ':'
• add the remote logging event to the logterm

Examples to transfer remote logging events from an internal server to banIP via cgi interface:

• POST request: curl --insecure --data "=<suspicious IP>" https://192.168.1.1/cgi-bin/banip
• GET request: wget --no-check-certificate https://192.168.1.1/cgi-bin/banip?=<suspicious IP>

Please note: for security reasons use this cgi interface only internally and only encrypted via https transfer protocol.

Download options
By default banIP uses the following pre-configured download options:

* curl: --connect-timeout 20 --speed-time 20 --retry-delay 10 --retry 4 --retry-all-errors --fail --silent --globoff --show-error --location -o
    * wget: --no-cache --no-cookies --timeout=20 --waitretry=10 --tries=5 --retry-connrefused -O
    * uclient-fetch: --timeout=20 -O

The retry-related values shown above are derived from ban_fetchretry (default 5): for curl --retry is ban_fetchretry - 1, for wget --tries equals ban_fetchretry. To override the defaults set ban_fetchretry, ban_fetchinsecure or globally ban_fetchparm to your needs.

Configure E-Mail notifications via msmtp
To use the email notification you must install and configure the package msmtp.
Modify the file /etc/msmtprc, e.g.:

[...]
defaults
auth            on
tls             on
tls_certcheck   off
timeout         5
syslog          LOG_MAIL
[...]
account         ban_notify
host            smtp.gmail.com
port            587
from            <address>@gmail.com
user            <gmail-user>
password        <password>

Finally add a valid E-Mail receiver address in banIP.

Send status E-Mails and update the banIP lists via cron job
For a regular, automatic update of the used feeds or other regular banIP tasks (e.g. status mailing) set up a cron job. Use reload here — start/restart would only restore the backups instead of fetching fresh feeds. In LuCI you find the cron settings under System => Scheduled Tasks. On the command line the cron file is located at /etc/crontabs/root:

55 03 * * * /etc/init.d/banip report mail
00 04 * * * /etc/init.d/banip reload

Redirect asterisk security logs to syslog/logread
By default banIP scans the logfile via logread, so to monitor attacks on asterisk, its security log must be available via logread. To do this, edit /etc/asterisk/logger.conf and add the line syslog.local0 = security, then run asterisk -rx reload logger to update the running asterisk configuration.

Change/add banIP feeds and set optional feed flags
The banIP default blocklist feeds are stored in an external JSON file /etc/banip/banip.feeds. This file is shipped with the package and is overwritten on every package update, so never edit it directly. All of your custom changes belong in the separate JSON file /etc/banip/banip.custom.feeds (empty by default), which is preserved across updates. It's recommended to use the LuCI based Custom Feed Editor (Custom Feed Editortab), which validates the JSON for you.

A feed is a single JSON object, keyed by a unique feed name (no spaces, no special characters). Example:

[...]
	"doh":{
		"url_4": "https://raw.githubusercontent.com/dibdot/DoH-IP-blocklists/master/doh-ipv4.txt",
		"url_6": "https://raw.githubusercontent.com/dibdot/DoH-IP-blocklists/master/doh-ipv6.txt",
		"rule": "feed 1",
		"chain": "out",
		"descr": "public DoH-Server",
		"flag": "tcp udp 80 443"
	},
	[...]

The object supports the following fields:

The url_4 / url_6 fields
Each address family is fetched and processed independently. Three cases:

• IPv4-only source: set url_4 only, omit url_6
• separate IPv4 and IPv6 files: set both to their respective URLs (e.g. doh, spamhaus)
• a single dual-stack file that mixes v4 and v6 entries: point both url_4 and url_6 at that same URL. banIP fetches it only once and process it for each family and the per-family regex extracts the matching addresses; the non-matching lines are simply ignored. (e.g. threatview, which ships v4 and v6 in one file).

The country and asn feeds are special: banIP fetches one file per selected country code / ASN, so their URLs are templates. The placeholder is replaced by the configured value as-is, so country codes have to be lowercase, just like in banip.countries. The placeholder {country} is replaced by the lowercase ISO country code, {asn} by the bare AS number, e.g. https://www.ipdeny.com/ipblocks/data/aggregated/{country}-aggregated.zone or https://asn.ipinfo.app/api/text/list/AS{asn}. A URL without placeholder is treated as a base path and gets the legacy suffix appended (<cc>-aggregated.zone resp. AS<asn>), so older custom feed files keep working. The placeholder can sit anywhere in the URL, which allows to switch the country source to a differently structured one. Example for a GeoLite2-based alternative, which ships IPv4 and IPv6 in one file per country:

"country":{
		"url_4": "https://raw.githubusercontent.com/Loyalsoldier/geoip/release/text/{country}.txt",
		"url_6": "https://raw.githubusercontent.com/Loyalsoldier/geoip/release/text/{country}.txt",
		"rule": "feed 1",
		"chain": "in",
		"descr": "country blocks (GeoLite2)"
	},

Pointing url_4 and url_6 at the same file is the dual-stack case described above, so each country file is downloaded only once and processed for both address families. This source includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com - its use is subject to the MaxMind GeoLite End User License Agreement.

Keep in mind that alternative sources come with their own license terms, which you have to check yourself, and that they differ in semantics (geolocation vs. RIR allocation), granularity (set sizes and memory footprint may grow considerably) and code coverage (a missing country file only logs a download failure for that code).

The rule field
The rule consists of max. 4 individual, space separated parameters:

1. type: feed or suricata (required)
   • feed: a plain IP/CIDR list, one entry per line (the common case)
   • suricata: a Suricata/Snort-style ruleset; banIP extracts the IPs out of the rule lines
2. prefix: an optional search term (a literal string, not a regex) that a line must contain to be considered a valid entry. Use it to skip comment/header lines or to pick only the relevant rows. Omit it if every data line is a bare IP.
3. column: the 1-based column that holds the IP within a matching line, e.g. 1 for a bare list or 13 for the dshield block file (required)
4. separator: an optional field separator; default is the whitespace character class [[:space:]]. Pass a literal character such as , for comma-separated sources (e.g. turris).

The chain field
Defines the default blocking direction. See the Best practise feed-direction note for the reasoning behind each value:

• in: inbound only (WAN-Input + WAN-Forward). Use for source-IP reputation feeds (attackers, scanners, spam senders).
• out: outbound only (LAN-Forward). Use for destination feeds your own clients should never reach (malware hosts, C2, DoH/DNS endpoints).
• inout: both directions. Use when the risk genuinely exists on both sides (e.g. spamhaus, tor, proxy, vpn).

This is only the default; a user can always override it at runtime per feed via ban_feedin / ban_feedout / ban_feedinout, or strip a feed's port/protocol limitation via ban_feedreset — without touching the feed JSON.

The flag field (optional)
A space separated list of extra options:

• gz: the source is gzip-compressed and will be decompressed before parsing (e.g. backscatterer, ipthreat, uceprotect*)
• protocol/port limitation — one or both of tcp / udp followed by one or more destination ports or port ranges. This restricts the feed's rules to those destination ports, which is mainly useful for outbound feeds to cut false positives.
  Examples:
  • tcp udp 80 443: limit to HTTP/HTTPS (e.g. doh, hagezi, feodo, urlhaus, urlvir, webclient)
  • tcp udp 53 853: limit to plain DNS and DNS-over-TLS (e.g. dns)
  • tcp 22: limit to SSH
  • tcp 5060-5061 udp 5060: mix of single ports and ranges
  • gz and a port limitation can be combined, e.g. gz tcp udp 80 443

After editing /etc/banip/banip.custom.feeds, reload banIP (/etc/init.d/banip reload) and check the Processing Log tab — a malformed JSON object or a wrong column/separator typically shows up there as a feed that loads zero elements.

Troubleshooting & debug options Copy Chapter

banIP provides an optional debug mode that writes diagnostic information to the system log and captures internal error output in a dedicated error logfile - by default located in the banIP base directory as /tmp/ban_error.log. The log file is automatically cleared at the beginning of each run. Under normal conditions, all error messages are discarded to keep regular runs clean and silent.

Whenever you encounter banIP related processing problems, please enable Verbose Debug Logging, restart banIP and check the Processing Log tab.
Typical symptoms:

• The nftables initialization failed: untick the Auto Detection option in the General Settings config section and set the required device and tools options manually
• A blocklist feed does not work: maybe a temporary server problem or the download URL has been changed. In the latter case, just use the Custom Feed Editor to point this feed to a new URL

In case of a nft processing error, banIP creates an error directory (by default /tmp/banIP-error) with the faulty nft load files.
For further troubleshooting, you can try to load such an error file manually to determine the exact cause of the error, e.g.: nft -f error.file.nft.

Whenever you encounter firewall problems, enable the logging of certain chains in the Log Settings config section, restart banIP and check the Firewall Log tab.
Typical symptoms:

• A feed blocks a legit IP: disable the entire feed or add this IP to your local allowlist and reload banIP
• A feed (e.g. doh) interrupts almost all client connections: check the feed table above for reference and reset the feed to the defaults in the "Feed/Set Settings" config tab section
• The allowlist doesn't free a certain IP/MAC address: check the current content of the allowlist with the "Set Content" under the "Set Reporting" tab to make sure that the desired IP/MAC is listed - if not, reload banIP

Support Copy Chapter

Please join the banIP discussion in this forum thread or contact me by mail [email protected]
If you want to report an error, please describe it in as much detail as possible - with (debug) logs, the current banIP status, your banIP configuration, etc.

Removal Copy Chapter

Stop all banIP related services with /etc/init.d/banip stop and remove the banip package if necessary.

Donations Copy Chapter

You like this project - is there a way to donate? Generally speaking "No" - I have a well-paying full-time job and my OpenWrt projects are just a hobby of mine in my spare time.

If you still insist to donate some bucks ...

• I would be happy if you put your money in kind into other, social projects in your area, e.g. a children's hospice
• Let's meet and invite me for a coffee if you are in my area, the “Markgräfler Land” in southern Germany or in Switzerland (Basel)
• Send your money to my PayPal account and I will collect your donations over the year to support various social projects in my area

No matter what you decide - thank you very much for your support!

Have fun!
Dirk

Overview (`net/etherwake-nfqueue/README.md`) Copy Section

OpenWrt package feed for etherwake-nfqueue

Wake up computers on netfilter match Copy Chapter

This repository contains the OpenWrt package feed for
etherwake-nfqueue,
a fork of the etherwake Wake-on-LAN client, with support to send magic
packets only after a queued packet is received from the Linux nfnetlink_queue
subsystem.

When running etherwake-nfqueue on a residential gateway or other type of
router, it can wake up hosts on its network based on packet filtering rules.

For instance, when your set-top box wants to record a TV programme and
tries to access a network share on your NAS, which is in sleep or standby mode,
etherwake-nfqueue can wake up your NAS. Or when you set up port forwarding
to a host on your home network, etherwake-nfqueue can wake up your host
when you try to access it over the Internet.

The documentation below is mostly OpenWrt specific. For more information on
etherwake-nfqueue itself and use case examples, please consult its
Readme.

Building the package Copy Chapter

Currently, no pre-built packages are provided. The following assumes that you
already have a working OpenWrt build system for your target device.

If you haven't, you can follow one of these guides:

• If you only want to compile packages, and no firmware image:
  Build system – Installation and
  Using the SDK

• To quickly build a firmware image off a development snapshot:
  Quick Image Building Guide

• Or when you are completely new to using build systems:
  Beginners guide to building your own firmware

Dependencies Copy Section

etherwake-nfqueue depends on these OpenWrt packages:

• libnetfilter-queue
• iptables-mod-nfqueue

They will be automatically selected and compiled for you. If they are not
installed on your target device, opkg will try to resolve dependencies with
packages in the repositories.

Adding the package feed Copy Section

First, you need to add the etherwake-nfqueue package feed to your build
system. In the root directory of your OpenWrt build system, find the file
feeds.conf (or feeds.conf.default if the former shouldn't exist) and add
the following line to it:

src-git ethernfq https://github.com/mister-benjamin/etherwake-nfqueue-openwrt.git

Then update and install the package feed:

user@host:~/openwrt$ scripts/feeds update ethernfq
user@host:~/openwrt$ scripts/feeds install -a -p ethernfq

After that, enter OpenWrt's configuration menu

user@host:~/openwrt$ make menuconfig

and enable etherwake-nfqueue in the Network sub-menu. It can either be selected
as built-in (*) or module (M), depending on your decision to include it into a
firmware image or just build the opkg package for installation.

Then you should be able to compile the package:

user@host:~/openwrt$ make package/etherwake-nfqueue/compile

The path of the resulting package depends on your selected Target System.
In case of the Linksys WRT1200AC, it can be found here:

bin/packages/arm_cortex-a9_vfpv3/ethernfq/etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk

Installation Copy Chapter

One way to install the package is by simply copying it over to the device with scp:

user@host:~$ scp etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk root@gateway:~

And then, install it on the device:

root@gateway:~# opkg install etherwake-nfqueue_2019-09-10-67e9d4ca-1_arm_cortex-a9_vfpv3.ipk

Configuration Copy Chapter

WoL Targets Copy Section

After a fresh installation, no target is configured. Targets are referred
to as the hosts to wake up. Multiple targets can coexist.

Targets can be configured with OpenWrt's UCI.

For example, to add a target called nas, with MAC address
00:25:90:00:d5:fd, which is reachable over the VLAN configured
on eth0.3, issue this command sequence on your router:

uci add etherwake-nfqueue target
uci set etherwake-nfqueue.@target[-1].name=nas
uci set etherwake-nfqueue.@target[-1].mac=00:25:90:00:d5:fd
uci set etherwake-nfqueue.@target[-1].interface=eth0.3
uci commit

For each target, one instance of etherwake-nfqueue will be started.

Each instance should bind to a different nfnetlink_queue. A queue can
be referenced by its queue number. Counting starts from 0, which is the default.
To use a different queue, provide the nfqueue_num option. The
following could have been added to the sequence above to use queue 1 instead
of 0:

uci set etherwake-nfqueue.@target[-1].nfqueue_num=1

The necessity of a queue number will probably become clear, when the iptables
rules are configured in section Setup firewall rules.

The full list of options for a target is:

After committing your changes, the settings are persisted to
/etc/config/etherwake-nfqueue. This is an illustrative example:

config etherwake-nfqueue 'setup'
        option sudo 'off'
        option debug 'off'

config target
        option name 'nas'
        option mac '00:25:90:00:d5:fd'
        option interface 'eth0.3'

config target
        option name 'xyz-board'
        option mac '00:25:90:00:d5:fc'
        option nfqueue_num '1'
        option enabled 'false'

config target
        option name 'ip-camera'
        option mac '00:25:90:00:d5:fb'
        option nfqueue_num '2'
        option interface 'eth0.3'
        option broadcast 'on'
        option password '00:25:90:00:d5:fb'

When all target(s) are configured, restart the etherwake-nfqueue service:

/etc/init.d/etherwake-nfqueue restart

Setting up filters Copy Section

Without any firewall rules which tell the kernel to match and add packets
to a nfnetlink_queue, etherwake-nfqueue will never send out a magic
packet to wake its target.

Prerequisites

In order to let the netfilter framework of the kernel see the packets,
they need to pass through the router. This is usually not the case when
hosts are on the same subnet and don't require network layer routing.
The data will only pass through the router's switch on the link layer.

As a consequence, we can only use packets as a trigger which need to be
routed or bridged by the router. Packets being forwarded between WAN
and LAN are of that type. For other SOHO use cases, partitioning your
network by means of subnets or VLANs might be necessary. The latter
is often used to set up a DMZ.

For VLANs:

• There's a mini howto referring to the LuCI Web Interface
  (Network -> Switch) way of configuring VLANs:
  How-To: Creating an additional virtual switch on a typical home router

• The manual approach is documented here:
  VLAN

Guides to setup a DMZ can be found here:

• Guide to set up DMZ via LUCI

• fw3 DMZ Configuration Using VLANs

The physical switch layout is device specific. E.g. the layout for the Linksys
WRT AC Series is documented
here.

Using two LANs or VLANs with the same network address and bridging them again
is a trick to setup a transparent (or bridging) firewall on the same subnet.
This way, packets can be seen by netfilter on the router even if the
packets are not routed. Unfortunately this doesn't help when the host
which we want to wake up is offline, as the ARP requests for the destination
IP address are not answered and thus the client trying to reach out to its
destination will not send any network layer packets. We could use arptables
instead to wake the host when someone requests its MAC address, but this
would probably happen too often and no fine-grained control would be possible.

As a workaround, it might be possible to configure a static ARP entry on your
router (untested), e.g. with:

ip neigh add 192.168.0.10 lladdr 00:25:90:00:d5:fd nud permanent dev eth0.3

Note that this requires the ip-full OpenWrt package to be installed.

To make your firewall rules work with bridging, you need to install the
kmod-br-netfilter package and add net.bridge.bridge-nf-call-iptables=1
to /etc/sysctl.conf.

Setup firewall rules

One way to setup custom firewall rules in OpenWrt is through its
/etc/firewall.user script. This file can also be edited by means of
the LuCI Web Interface (Network -> Firewall -> Custom Rules).

The file is interpreted as a shell script, so we can simply use iptables
to add our custom firewall rules.

Notice the comment

# Internal uci firewall chains are flushed and recreated on reload, so
# put custom rules into the root chains e.g. INPUT or FORWARD or into the
# special user chains, e.g. input_wan_rule or postrouting_lan_rule.

Refer to Packet flow
for usable chains. In the example below, the chains forwarding_lan_rule and
forwarding_wan_rule are used. To inspect the rule sets of the different tables, one can
use

iptables --list                  # default is --table filter
iptables --table nat --list
iptables --table mangle --list
iptables --table raw --list      # requires kmod-ipt-raw

The following is an example of what could be added to /etc/firewall.user:

/* Detailed source-code truncated for AI context efficiency. */

In this example, packets are filtered based on the protocol, their input
and output interfaces, their destination (IP address) and their destination
port(s).

The option --match conntrack --ctstate NEW only matches packets of a new
connection and --match limit --limit 3/hour --limit-burst 1 limits the
amount of packets that are matched. The latter option roughly matches
only one packet per 20 minutes. The intention here is to not be too intrusive
and avoid sending a lot of magic packets.

The --jump NFQUEUE --queue-num 0 options tell the netfilter
framework to enqueue a matching packet to the NFQUEUE number 0. In this
example, all four rules send the matching packets into queue 0. The
additional option --queue-bypass helps in the situation, when
etherwake-nfqueue isn't running. Packets will then be handled
as if the rule wasn't present.

Disabling targets Copy Chapter

To disable targets, first find their index:

uci show etherwake-nfqueue

Then set its enabled option to false and restart the service.
For index 0, it can be done like this:

uci set etherwake-nfqueue.@target[0].enabled=false
/etc/init.d/etherwake-nfqueue restart

Troubleshooting Copy Chapter

Debug mode Copy Section

In order to see what's going on in syslog and get some debug output when
starting the service, enable etherwake-nfqueue's debug mode:

uci set etherwake-nfqueue.setup.debug=on

In another user session tail the log:

logread -f

And then restart the service:

/etc/init.d/etherwake-nfqueue restart

Inspect netfilter Copy Section

To inspect the working of your firewall rules, you can print statistics
of the chains you used, e.g.:

iptables --verbose --list forwarding_lan_rule

If you happen to have the procps-ng-watch package installed, you can watch
them:

watch iptables --verbose --list forwarding_lan_rule

To see, if your queues are in place, use:

cat /proc/net/netfilter/nfnetlink_queue

Potential improvements Copy Chapter

• Add LuCI Web Interface configuration frontend for targets and filter rules
• Add an option to set nice values for instances

Overview (`net/family-dns/Readme.md`) Copy Section

Package: net/family-dns

This package configures your router to block access to adult websites.

The default settings are designed to be appropriate for most businesses, schools, and families.

Enabled and disable Family DNS by editing /etc/config/family-dns. To make
your changes active, run family-dns-update.

• Default DNS Filter
  • CleanBrowsing.org Adult Filter
    • https://cleanbrowsing.org/filters#adult
    • Blocks access to all adult, pornographic and explicit sites. It does not block proxy or VPNs, nor mixed-content sites. Sites like Reddit are allowed. Google and Bing are set to the Safe Mode. Malicious and Phishing domains are blocked.
• Alternate DNS Filters:
  • CleanBrowsing.org Family Filter
    • https://cleanbrowsing.org/filters#family
    • Blocks access to all adult, pornographic and explicit sites. It also blocks proxy and VPN domains that are used to bypass the filters. Mixed content sites (like Reddit) are also blocked. Google, Bing and Youtube are set to the Safe Mode. Malicious and Phishing domains are blocked.
  • Cisco Family Shield
    • https://www.opendns.com/home-internet-security/
    • https://www.opendns.com/setupguide/#familyshield
    • FamilyShield will block domains that are categorized as: Tasteless, Proxy/Anonymizer, Sexuality and Pornography.

Overview (`net/geoip-shell/OpenWrt-README.md`) Copy Section

geoip-shell on OpenWrt Copy Chapter

Currently geoip-shell fully supports OpenWrt, both with firewall3 + iptables and with firewall4 + nftables, while providing the same user interface and features as on any other Linux system. So usage is the same as described in the main README.md file, while some parts of the backend (namely persistence implementation), some defaults and the location of the data directory are different.

The geoip-shell-iptables package is for firewall3+iptables OpenWrt systems, while the geoip-shell package is for firewall4+nftables OpenWrt systems.

A LuCi interface has not been implemented (yet). As on any other Linux system, all user interface is via a command line (but my goal is to make this an easy experience regardless). If this discourages you from using geoip-shell, please let me know. A few people asking for this feature may motivate me to prioritize it.

Usage after installation via ipk Copy Chapter

After installing the ipk package, geoip-shell will be inactive until you configure it. To do so, run geoip-shell configure and follow the interactive setup. You can also run geoip-shell -h before that to find out about configuration options and then append certain options after the configure action, for example: geoip-shell configure -c "de nl" -m whitelist to configure geoip-shell in whitelist mode for countries Germany and Netherlands. The interactive setup will ask you about all the important options but some niche options are only available non-interactively (for example if you want to configure geoblocking for certain selection of ports). You can always change these settings after initial configuration via the same geoip-shell configure command.

Uninstallation of geoip-shell if installed via ipk Copy Chapter

• For nftables-based systems: opkg remove geoip-shell
• For iptables-based systems: opkg remove geoip-shell-iptables

Resources management on OpenWrt Copy Chapter

Because OpenWrt typically runs on embedded devices with limited memory and very small flash storage, geoip-shell implements some techniques to conserve these resources as much as possible:

• During installation on OpenWrt, comments and the debug code are stripped from the scripts to reduce their size.
• Only the required modules are installed, depending on the system (iptables- or nftables- based).
• I've researched the most memory-efficient way for loading ip lists into nftables sets. Currently, nftables has some bugs related to this process which may cause unnecessarily high memory consumption. geoip-shell works around these bugs as much as possible.
• To avoid unnecessary flash storage wear, all filesystem-related tasks geoip-shell does which do not require permanent storage are done in the /tmp directory which in the typical OpenWrt installation is mounted on the ramdisk.
• Some defaults on OpenWrt are different to further minimize flash storage wear (read below).

Scripts size Copy Section

Typical geoip-shell installation on an OpenWrt system currently consumes around 120kB. The distribution folder itself weighs quite a bit more (mainly because of documentation) but you can install via an ipk which doesn't remain in storage after installation, or if installing via the -install script, delete the distribution folder and free up space taken by it. geoip-shell does not install its documentation into the system.
I have some plans to reduce that size by compressing certain scripts which provide user interface and implementing automatic extraction to /tmp when the user wants to access them, but this is not yet implemented.

To view all installed geoip-shell scripts in your system and their sizes, run ls -lh /usr/bin/geoip-shell-* /usr/lib/geoip-shell/*.

Persistence on OpenWrt Copy Chapter

• Persistence of geoip firewall rules and ip sets works differenetly on OpenWrt than on other Linuxes, since geoip-shell has an OpenWrt-specific procd init script.
• The cron job which implements persistence on other Linuxes and runs at reboot is not created on OpenWrt.
• geoip-shell integrates into firewall3 or firewall4 via what's called a "firewall include". On OpenWrt, a firewall include is a setting which tells firewall3 or firewall4 to do something specific in response to certain events.
• The only task of the init script for geoip-shell is to call the geoip-shell-mk-fw-include.sh script, which makes sure that the firewall include exists and is correct, if not then creates the include.
• The firewall include is what does the actual persistence work. geoip-shell firewall include triggers on firewall reload (which happens either at reboot or when the system decides that a reload of the firewall is necessary, or when initiated by the user).
• When triggered, the include script calls the -run script with the "restore" action.
• The -run script verifies that geoip nftables/iptables rules and ip sets exist, and if not then it restores them from backup, or (if backup doesn't exist) initiates re-fetch of the ip lists and then re-creates the rules and the ip sets.
• By default, geoip-shell does not create backups on OpenWrt because typically the permanent storage is very small and prone to wear.
• Automatic updates of ip lists on OpenWrt are triggered from a cron job like on other Linuxes.

Defaults for OpenWrt Copy Chapter

Generally the defaults are the same as for other systems, except:

• the data directory which geoip-shell uses to store the status file and the backups is by default in /tmp/geoip-shell-data, rather than in /var/lib/geoip-shell as on other Linux systems. This is to avoid flash wear. You can change this by running the install script with the -a option, or after installation via the command geoip-shell configure -a .
• the 'nobackup' option is set to 'true', which configures geoip-shell to not create backups of the ip lists. With this option, geoip-shell will work as usual, except after reboot (and for iptables-based systems, after firewall restart) it will re-fetch the ip lists, rather than loading them from backup. You can change this by running the -install script with the -o false option (-o stands for nobackup), or after installation via the command geoip-shell configure -o false. To have persistent ip list backups, you will also need to change the data directory path as explained above.
• if using geoip-shell on a router with just a few MB of embedded flash storage, consider either leaving the nobackup and datadir path defaults as is, or connecting an external storage device to your router (preferably formatted to ext4) and configuring a directory on it as your geoip-shell data directory, then enabling automatic backups. For example, if your external storage device is mounted on /mnt/somedevice, you can do all this via this command: geoip-shell configure -a /mnt/somedevice/geoip-shell-data -o false.
• the default ip lists source for OpenWrt is ipdeny (rather than ripe). While ipdeny is a 3rd party, they provide aggregated lists which consume less memory (on nftables-based systems the ip lists are automatically optimized after loading into memory, so there the source does not matter, but a smaller initial ip lists size will cause a smaller memory consumption spike while loading the ip list).

This is about it for this document. Much more information is available in the main README.md and in the extra .md files inside the Documentation directory. If you have any questions, contact me in this thread:
https://forum.openwrt.org/t/geoip-shell-flexible-geoip-blocker-for-linux-now-supports-openwrt/189611

If you use this project, I will be happy to hear about your experience in the above thread. If for some reason geoip-shell is not working for you, I will want to know that as well so I can improve it.

Overview (`net/geoip-shell/README.md`) Copy Section

**geoip-shell**

Geoip blocker for Linux. Supports both nftables and iptables firewall management utilities.

The idea of this project is making geoip blocking easy on (almost) any Linux system, no matter which hardware, including desktop, server, VPS or router, while also being reliable and providing flexible configuration options for the advanced users.

Supports running on OpenWrt. Supports ipv4 and ipv6.

Table of contents Copy Chapter

• Main Features
• Usage
• Pre-requisites
• Notes
• In detail
• OpenWrt
• Privacy

**Main Features** Copy Chapter

• Core functionality is creating either a whitelist or a blacklist in the firewall using automatically downloaded ip lists for user-specified countries.

• ip lists are fetched either from RIPE (regional Internet registry for Europe, the Middle East and parts of Central Asia) or from ipdeny. Both sources provide updated ip lists for all regions.

• All firewall rules and ip sets required for geoip blocking to work are created automatically during installation or setup.

• Implements optional (enabled by default) persistence of geoip blocking across system reboots and automatic updates of the ip lists.

• After installation, a utility is provided to check geoip status and firewall rules or change country codes and geoip-related config.

**Reliability**: Copy Section

• Downloaded ip lists go through validation which safeguards against application of corrupted or incomplete lists to the firewall.

Read more:

• With nftables, utilizes nftables atomic rules replacement to make the interaction with the system firewall fault-tolerant and to completely eliminate time when geoip is disabled during an automatic update.
• All scripts perform extensive error detection and handling.
• All user input is validated to reduce the chance of accidental mistakes.
• Verifies firewall rules coherence after each action.
• Automatic backup of geoip-shell state (optional, enabled by default except on OpenWrt).
• Automatic recovery of geoip-shell firewall rules after a reboot (a.k.a persistence) or in case of unexpected errors.
• Supports specifying trusted ip addresses anywhere on the Internet which will bypass geoip blocking to make it easier to regain access to the machine if something goes wrong.

**Efficiency**: Copy Section

• Utilizes the native nftables sets (or, with iptables, the ipset utility) which allows to create efficient firewall rules with thousands of ip ranges.

Read more:

• With nftables, optimizes geoip blocking for low memory consumption or for performance, depending on the RAM capacity of the machine and on user preference. With iptables, automatic optimization is implemented.
• Ip list parsing and validation are implemented through efficient regex processing which is very quick even on slow embedded CPU's.
• Implements smart update of ip lists via data timestamp checks, which avoids unnecessary downloads and reconfiguration of the firewall.
• Uses the "prerouting" hook in kernel's netfilter component which shortens the path unwanted packets travel in the system and may reduce the CPU load if any additional firewall rules process incoming traffic down the line.
• Supports the 'ipdeny' source which provides aggregated ip lists (useful for embedded devices with limited memory).
• Scripts are only active for a short time when invoked either directly by the user or by the init script/reboot cron job/update cron job.

**User-friendliness**: Copy Section

• Good command line interface and useful console messages.

Read more:

• Extensive and (usually) up-to-date documentation.
• Sane settings are applied during installation by default, but also lots of command-line options for advanced users or for special corner cases are provided.
• Provides a utility (symlinked to 'geoip-shell') for the user to change geoip config (turn geoip on or off, change country codes, change geoip blocking mode, change ip lists source, change the cron schedule etc).
• Provides a command ('geoip-shell status') to check geoip blocking status, which also reports if there are any issues.
• In case of an error or invalid user input, provides useful error messages to help with troubleshooting.
• All main scripts display detailed 'usage' info when executed with the '-h' option.
• The code should be fairly easy to read and includes a healthy amount of comments.

**Compatibility**: Copy Section

• Since the project is written in POSIX-compliant shell code, it is compatible with virtually every Linux system (as long as it has the pre-requisites). It even works well on simple embedded routers with 8MB of flash storage and 128MB of memory (for nftables, 256MB is recommended if using large ip lists such as the one for US until the nftables team releases a fix reducing memory consumption).

Read more:

• Supports running on OpenWrt.
• The project avoids using non-common utilities by implementing their functionality in custom shell code, which makes it faster and compatible with a wider range of systems.

**Usage** Copy Chapter

If you want to change geoip blocking config or check geoip blocking status, you can do that via the provided utilities.
A selection of options is given here, for additional options run geoip-shell -h or read NOTES.mdand DETAILS.md.

To check current geoip blocking status: geoip-shell status. For a list of all firewall rules in the geoip chain and for a detailed count of ip ranges in each ip list: geoip-shell status -v.

To add or remove ip lists for countries: geoip-shell <add|remove> -c <"country_codes">

Examples:

• example (to add ip lists for Germany and Netherlands): geoip-shell add -c "DE NL"
• example (to remove the ip list for Germany): geoip-shell remove -c DE

To enable or disable geoip blocking: geoip-shell <on|off>

To change ip lists source: geoip-shell configure -u <ripe|ipdeny>

To change geoip blocking mode: geoip-shell configure -m <whitelist|blacklist>

To have certain trusted ip addresses or subnets bypass geoip blocking: geoip-shell configure -t <["ip_addresses"]|none>. none removes previously set trusted ip addresses.

To have certain LAN ip addresses or subnets bypass geoip blocking: geoip-shell configure -l <["ip_addresses"]|auto|none>. auto will automatically detect LAN subnets (only use this if the machine has no dedicated WAN interfaces). none removes previously set LAN ip addresses. This is only needed when using geoip-shell in whitelist mode, and typically only if the machine has no dedicated WAN network interfaces. Otherwise you should apply geoip blocking only to those WAN interfaces, so traffic from your LAN to the machine will bypass the geoip filter.

To change protocols and ports geoblocking applies to: geoip-shell configure -p <[tcp|udp]:[allow|block]:[all|]>

(for detailed description of this feature, read NOTES.md, sections 9-11)

To enable or change the automatic update schedule: geoip-shell configure -s <"schedule_expression">

Example

geoip-shell configure -s "1 4 * * *"

To disable automatic updates of ip lists: geoip-shell configure -s disable

To update or re-install geoip-shell: run the -install script from the (updated) distribution directory. It will first run the -uninstall script of the older/existing version, then install the new version.

On OpenWrt, if installed via an ipk package: opkg uninstall <geoip-shell|geoip-shell-iptables>

**Pre-requisites** Copy Chapter

• Linux. Tested on Debian-like systems and on OpenWrt, should work on any desktop/server distribution and possibly on some other embedded distributions.

• POSIX-compliant shell. Works on most relatively modern shells, including bash, dash, ksh93, yash and ash (including Busybox ash). Likely works on mksh and lksh. Other flavors of ksh may or may not work (please let me know if you try them). Does not work on tcsh and zsh.

• nftables - firewall management utility. Supports nftables 1.0.2 and higher (may work with earlier versions but I do not test with them).

• OR iptables - firewall management utility. Should work with any relatively modern version.

• for iptables, requires the ipset utility - install it using your distribution's package manager

• standard Unix utilities including tr, cut, sort, wc, awk, sed, grep, pgrep, pidof and logger which are included with every server/desktop linux distribution (and with OpenWrt). Both GNU and non-GNU versions are supported, including BusyBox implementation.

• wget or curl or uclient-fetch (OpenWrt-specific utility).

• for the autoupdate functionality, requires the cron service to be enabled.

**Notes** Copy Chapter

For some helpful notes about using this suite, read NOTES.md.

**In detail** Copy Chapter

For specifics about each script, read DETAILS.md.

**OpenWrt** Copy Chapter

For information about OpenWrt support, read the OpenWrt README.

**Privacy** Copy Chapter

geoip-shell does not share your data with anyone.
If you are using the ipdeny source then note that they are a 3rd party which has its own data privacy policy.

Overview (`net/https-dns-proxy/README.md`) Copy Section

https-dns-proxy

A lightweight, RFC8484-compliant DNS-over-HTTPS (DoH) proxy service for OpenWrt.
Includes optional integration with dnsmasq, automatic fallback, and canary domain support.

Features Copy Chapter

• Small footprint (~40KB installed)
• Seamless dnsmasq integration and fallback
• Optional LuCI Web UI with 40+ built-in resolvers

Full documentation:

https://docs.mossdef.org/https-dns-proxy/

Based on @aarond10's excellent https_dns_proxy

Overview (`net/modemmanager/README.md`) Copy Section

OpenWrt ModemManager

Description Copy Chapter

Cellular modem control and connectivity

Optional libraries libmbim and libqmi are available.
Your modem may require additional kernel modules and/or the usb-modeswitch
package.

Usage Copy Chapter

Once installed, you can configure the 2G/3G/4G modem connections directly in
/etc/config/network as in the following example:

config interface 'broadband'
    option device      '/sys/devices/platform/soc/20980000.usb/usb1/1-1/1-1.2/1-1.2.1'
    option proto       'modemmanager'
    option apn         'ac.vodafone.es'
    option allowedauth 'pap chap'
    option username    'vodafone'
    option password    'vodafone'
    option pincode     '7423'
    option iptype      'ipv4'
    option plmn        '214001'
    option lowpower    '1'
    option signalrate  '30'
    option allow_roaming '1'
    option force_connection '1'
    option init_epsbearer '<modem|network|connection|custom>'
    option timeout     '120'

Only 'device' and 'proto' are mandatory options, the remaining ones are all
optional.

The 'allowedauth' option allows limiting the list of authentication protocols.
It is given as a space-separated list of values, including any of the
following: 'pap', 'chap', 'mschap', 'mschapv2' or 'eap'. It will default to
allowing all protocols.

The 'iptype' option supports any of these values: 'ipv4', 'ipv6' or 'ipv4v6'.
It will default to 'ipv4' if not given.

The 'plmn' option allows to set the network operator MCCMNC.

The 'signalrate' option set's the signal refresh rate (in seconds) for the device.
You can call signal info with command: mmcli -m 0 --signal-get

The 'timeout' option set's the command timeout (in seconds) for the long
running 'mmcli' calls ('enable', 'simple-connect',
3gpp-register-in-operator' and '3gpp-set-initial-eps-bearer-settings')
in the modemmanager protohandler. The default value is 120 seconds, if
no value is configured.

The 'force_connection' option is designed to ensure that the modem automatically
attempts to reconnect regardless of any errors encountered during the
connection process.

On 4G and 5G networks, the modem attaches to the network with an initial
EPS bearer, before the data connection is established. The 'init_epsbearer'
option selects where the settings for this initial EPS bearer come from:

• modem: Leave the initial EPS bearer settings stored on the modem
  unchanged (default). These are usually provided by the carrier
  firmware or set by a previous configuration.
• network: Set an empty initial EPS bearer, so the network assigns the APN.
  Use this to override settings left on the modem, e.g. after
  swapping the SIM card.
• connection: Use the options 'apn', 'iptype', 'allowedauth', 'username' and
  'password', the same options as for the data connection.
• custom: Use separate options, prefixed with 'init_': 'init_apn',
  'init_iptype', 'init_allowedauth', 'init_username' and
  'init_password'.

The values 'none' and 'default' are deprecated aliases for 'modem' and
'connection'.

The initial EPS bearer settings stored on the modem can also be cleared once
manually:

mmcli -m <modem> --3gpp-set-initial-eps-bearer-settings=""

Overview (`net/netifyd/README.md`) Copy Section

Netify Agent

Copyright ©2015-2020 eGloo Incorporated (www.egloo.ca)

Network Intelligence - Simplified Copy Chapter

The Netify Agent is a deep-packet inspection server. The Agent is built on top of nDPI (formerly OpenDPI) to detect network protocols and applications. Detections can be saved locally, served over a UNIX or TCP socket, and/or "pushed" (via HTTP POSTs) to a remote third-party server. Flow metadata, network statistics, and detection classifications are stored using JSON encoding.

Optionally, the Netify Agent can be coupled with a Netify Cloud subscription for further cloud processing, historical storage, machine-learning analysis, event notifications, device detection/identification, along with the option (on supported platforms) to take an active role in policing/bandwidth-shaping specific network protocols and applications.

Download Packages Copy Chapter

Supported platforms with installation instructions can be found here.

Alternatively, binary packages are available for the following OS distributions (manual install):

• CentOS
• ClearOS
• Debian
• FreeBSD
• NethServer
• OpenWrt/LEDE
• pfSense
• Raspbian
• RHEL
• Ubuntu

Runtime Requirements Copy Section

• [Linux] Ensure that the nfnetlink and nf_conntrack_netlink kernel modules are loaded if NAT detection is enabled.

Download Source Copy Chapter

When cloning the source tree, ensure you use --recursive to include all
sub-modules.

Build Requirements Copy Section

Netify requires the following third-party packages:

• libcurl
• libpcap
• zlib
• [Linux] libmnl
• [Linux] libnetfilter-conntrack

Optional:

• google-perftools/gperftools/libtcmalloc (will use bundled version when not available)

Configuring/Building From Source Copy Section

Read the appropriate documentation in the doc directory, prefixed with: BUILD-*

Generally the process is:

./autogen.sh
./configure
make

Online Documentation Copy Chapter

Further user and developer documentation can be found here.

License Copy Chapter

This software is licenced under the GPLv3:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Overview (`net/ntpd/README.md`) Copy Section

Configuring NTPD with UCI

Precedent Copy Chapter

Sysntpd is the lightweight implementation of the NTP protocol under
Busybox. It supports many (but not all) of the same parameters.

It is configured as a config timeserver ntp section in /etc/config/system,
below.

Configuration Copy Chapter

A sample configuration looks like:

/etc/config/system:

config timeserver ntp
	option enabled 1
	option enable_server 1
	list server tick.udel.edu
	list server tock.udel.edu
	list interface eth0
	list interface eth1
	list interface eth2

If you want to temporarily disable the service without deleting all of the
configuration state, this is done by clearing the enabled parameter. If
this parameter is 1 (the default), the service is enabled.

The service can run as a stand-alone client (enable_server 0, the default)
or it can also operate as a server in turn to local clients, by setting this
parameter to 1.

The parameter(s) server enumerate a list of servers to be used for
reference NTP servers by the local daemon. At least one is required,
and two or more are recommended (unless you have an extremely available
local server). They should be picked to be geographically divergent,
and preferably reachable via different network carriers to protect
against network partitions, etc. They should also be high-quality
time providers (i.e. having stable, accurate clock sources).

The interface parameter enumerates the list of interfaces on which
the server is reachable (see enable_server 1 above), and may be a
subset of all of the interfaces present on the system. For security
reasons, you may elect to only offer the service on internal networks.
If omitted, it defaults to all interfaces.

Differences with `sysntpd` Copy Chapter

Busybox sysntpd supports configuring servers based on DHCP
provisioning (option 6, per the DHCP and BOOTP
Parameter
list from IANA). This functionality is enabled (in Busybox) with the
use_dhcp boolean parameter (default 1), and the dhcp_interface
list parameter, which enumerates the interfaces whose provisioning
is to be utilized.

Considerations for DHCP-provisioned NTP servers Copy Section

Most terrestrial and satellite ISPs have access to very high-quality
clock sources (these are required to maintain synchronization on T3,
OC3, etc trunks or earth terminals) but seldom offer access to those
time sources via NTP in turn to their clients, mostly from a misplaced
fear that their time source might come under attack (a slave closely
tied to the master could also provide extremely high-quality time
without the risk of network desynchronization should it come under
sophisticated attack).

As a result, the NTP servers that your ISP may point you at are
often of unknown/unverified quality, and you use them at your own
risk.

Early millennial versions of Windows (2000, XP, etc) used NTP only
to initially set the clock to approximately 100ms accuracy (and
not maintain synchronization), so the bar wasn't set very high.
Since then, requirements for higher-quality timekeeping have
arisen (e.g. multi-master SQL database replication), but most ISPs
have not kept up with the needs of their users.

Current releases of Windows use Domain Controllers for time
acquisition via the NT5DS protocol
when domain joined.

Because of the unreliable quality of NTP servers DHCP-provisioned by
ISPs, support for this functionality was deemed unnecessary.

Overview (`net/openthread-br/README.md`) Copy Section

OpenThread Border Router

This package contains the OpenThread Border Router.

Requirements Copy Chapter

To use this package, you need a Thread Radio Co-Processor (RCP). Testing of
this package was done with Nordic Semiconductor nRF52840 USB dongles.

Building and flashing the dongle with the Thread RCP firmware is out of scope
of this document.

One caveat for this dongle is worth mentioning here. The nRF52840 USB dongle
seems to come with the U2F bootloader. To get it in mass storage mode to copy a
firmware file, you need to plug it in while pressing the reset button. However,
after the initial flash with the ot-rcp firmware, this method stops working.
Instead, you need to double press the reset button after plugging in the dongle.

Packaging decisions Copy Chapter

Configurable package build Copy Section

OpenThread is complex software. Adding config options to change the build of
the package will likely result in more bug reports. As the package and its
dependencies are unlikely to fit in any router with small flash (16MB or less),
I don't see much point in making things configurable for reducing size either.

Firewall support Copy Section

OpenWrt uses firewall4 with nftables by default, but the OpenThread firewall
implementation uses IPTables and IPset. While we still support firewall3 with
IPTables, it's not a good idea to add new dependencies to old things.
Therefore, firewall support is disabled completely.

This can be revised once the following feature request is implemented:
https://github.com/openthread/ot-br-posix/issues/1675

mDNSResponder Copy Section

The package depends on mDNSResponder. The alternative, Avahi, depends on D-Bus,
which is not something I feel comfortable with running on any router. While
there are Avahi packages without D-Bus support, using OpenThread Border Router
with Avahi requires libavahi-client, and this requires Avahi to be built with
D-Bus support.

REST Server Copy Section

The REST server is enabled to make this package compatible with Home Assistant.

TREL support Copy Section

Thread Radio Encapsulation Link support is enabled, as it allows Border Routers
to communicate over other links (e.g. Ethernet), reducing traffic over the
802.15.4 radios.

The following Github discussion contains a good explanation of TREL:
https://github.com/openthread/openthread/discussions/8478

UCI/netifd support Copy Section

The package contains a minimal netifd protocol handler. This allows configuring
the Thread network in /etc/config/network. The agent will be started by netifd,
rather than using an init script.

OpenThread does not store prefix information in non-volatile storage. As a
result, every time the agent is restarted, a different prefix would be used.
This is not very nice, and makes it very difficult to run the OpenThread Border
Router on a device that is not your main router. Therefore, prefixes can be
configured in /etc/config/network. This way, you can add a static route to the
Thread prefix(es) in your main router, making it possible to access devices on
the Thread network from your entire network.

Create network Copy Chapter

When starting the OpenThread Border Router for the first time, a Thread network
must be created.

As the agent is started by netifd, we first need to create an interface in
/etc/config/network:

config interface 'thread'
        option device 'wpan0'
        option proto 'openthread'
        option backbone_network 'lan'
        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
        list prefix 'fd6f:5772:5468:7200::/64 paros'
        option verbose '0'

Prefix and verbose are optional. Everything else is required. The protocol
handler will fail if a required setting is missing. If something isn't working,
check ifstatus for the OpenThread interface:

# ifup thread
# ifstatus thread
{
        "up": false,
        "pending": false,
        "available": true,
        "autostart": false,
        "dynamic": false,
        "proto": "openthread",
        "data": {

        },
        "errors": [
                {
                        "subsystem": "openthread",
                        "code": "MISSING_BACKBONE_NETWORK"
                }
        ]
}

In the above example, the backbone_network option is missing.

The protocol handler will automatically start the the Thread network, so we
need to bring it down for the initial setup. This only needs to be done once.

ubus call otbr threadstop

LuCI Copy Section

Creating a network in LuCI appears to be broken for the moment.

CLI Copy Section

ot-ctl dataset init new
ot-ctl dataset panid 0x12ab
ot-ctl dataset extpanid 12ab12ab12ab12ab
ot-ctl dataset networkname OpenWrThread
ot-ctl dataset networkkey ddf429af1c52d1735ffaf36fae343ee8
ot-ctl dataset commit active
ot-ctl ifconfig up
ot-ctl thread start
ot-ctl netdata register

Configure route Copy Section

Before you can join a device to your new Thread network, you must add a route
to the Thread prefix on the commissioner device via the OpenWrt router running
the OpenThread Border Router.

Get the prefix:

ot-ctl prefix

Example output:

fd6b:a92f:c531:1::/64 paros low f000
Done

Configuring the route is out of scope of this document, but it must be done, or
joining Thread devices will fail.

Get hex-encoded operational dataset TLV Copy Section

This is needed to join devices to the Thread Network.

ot-ctl dataset active -x

Example output:

0e080000000000010000000300001035060004001fffe00708fd488c6a892ec30c04106e220c964a14a7e10e9004691920ec390c0402a0f7f80102ffff030b5468726541646c6576696f0208ffffffffffffffff0510ddf429af1c52d1735ffaf36fae343ee8

Join another OpenThread Border Router Copy Chapter

Simply configure the active dataset in /etc/config/network:

config interface 'thread'
        option device 'wpan0'
        option proto 'openthread'
        option backbone_network 'lan'
        option dataset '0e080000000000010000000300000f35060004001fffe0020836b86cd9746ab3080708fd9850cbe719b1d205101f11a11320828c7a6ebc2f2e675c0dca030e686f6d652d617373697374616e740102716f041025804ed78614258ebedf4e2db37b3b6e0c0402a0f7f8'
        list prefix 'fd6f:5772:5468:7200::/64 paros'
        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
        option verbose '0'

Afterwards, bring up the interface:

ifup thread

Join a Thread device via Matter Copy Chapter

ESP32 Copy Section

The following procedure has been tested with an ESP32-C6 using the Matter
lighting-app example.
Building and flashing that app is out of scope of this document.

During startup, the lighting app will print the SetupQRCode to the serial
console:

I (1614) chip[SVR]: SetupQRCode: [MT:Y.K9042C00KA0648G00]
I (1624) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1634) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY.K9042C00KA0648G00
I (1644) chip[SVR]: Manual pairing code: [34970112332]

Decide on a node ID for the device.

./chip-tool pairing code-thread 0x65737933320000 hex:0e080000000000010000000300001035060004001fffe00708fd488c6a892ec30c04106e220c964a14a7e10e9004691920ec390c0402a0f7f80102ffff030b5468726541646c6576696f0208ffffffffffffffff0510ddf429af1c52d1735ffaf36fae343ee8 MT:Y.K9042C00KA0648G00 --paa-trust-store-path /path/to/connectedhomeip/credentials/test/attestation/

Overview (`net/openvswitch/README.md`) Copy Section

Which packages to install

Install openvswitch if you need OpenFlow virtual switch function. It
contains ovs-vswitchd, ovsdb-server and helper utilities such as ovs-vsctl,
ovs-ofctl, ovs-ctl etc.

Linux kernel datapath module openvswitch.ko will also be installed along with
package openvswitch. Tunnel encap support for gre, geneve, vxlan can be
included by installing kmod-openvswitch-{gre,geneve,vxlan} respectively

For OVN deployment

• Install openvswitch-ovn-north for ovs-northd, ovsdb-server, ovn helper utitlies
• Install openvswitch-ovn-host for ovn-controller and openvswitch

How to use them

Open vSwitch provides a few very useful helper script in
/usr/share/openvswitch/scripts/. A simple initscript is provided. It's
mainly a wrapper around ovs-ctl and ovn-ctl with simple knobs from
/etc/config/openvswitch. Procd is not used here.

/etc/init.d/openvswitch start
/etc/init.d/openvswitch stop
/etc/init.d/openvswitch stop north
/etc/init.d/openvswitch restart ovs
/etc/init.d/openvswitch status

Use ovs-ctl and ovn-ctl directly for more functionalities

Open vSwitch in-tree Linux datapath modules

The Open vSwitch build system uses regexp and conditional-compilation
heuristics to support building the shipped kernel module source code against a
wide range of kernels, as of openvswitch-2.10, the list is supposed to include
vanilla linux 3.10 to 4.15, plus a few distro kernels.

It may NOT work

• Sometimes the code does not compile
• Sometimes the code compiles but insmod will fail
• Sometimes modules are loaded okay but actually does not function right

For these reasons, the in-tree datapath modules are NOT visible/enabled by
default.

Building and using in-tree datapath modules requires some level of devel
abilities to proceed. You are expected to configure build options and build
the code on your own

E.g. pair openvswitch userspace with in-tree datapath module

CONFIG_DEVEL=y
CONFIG_PACKAGE_openvswitch=y
# CONFIG_PACKAGE_kmod-openvswitch is not set
CONFIG_PACKAGE_kmod-openvswitch-intree=y

E.g. replace in-tree datapath module with upstream version

opkg remove --force-depends kmod-openvswitch-intree
opkg install kmod-openvswitch
ovs-ctl force-reload-kmod

UCI configuration options

There are 5 config section types in package openvswitch:
ovs ovn_northd, ovn_controller & ovs_bridge.

Each of these supports a disabled option, which should be
set to 0 to launch the respective daemons.

The ovs section section also supports the options below, to configure a set of
SSL CA, certificate and private key. After adding these to Open vSwitch, you
may specify ssl: connection methods for e.g. the OpenFlow controller. Note that
Open vSwitch only reads these files during startup, so it needs to be restarted
after adding or changing these options.

The ovs_bridge section also supports the options below,
for initialising a virtual bridge with an OpenFlow controller.

The ovs_port section can be used to add ports to a bridge. It supports the options below.

Overview (`net/pbr/README.md`) Copy Section

Policy-Based Routing (pbr)

Flexible policy-based routing (PBR) framework for OpenWrt.
Allows routing specific traffic (by IP, MAC, port, protocol, or domain) through a specific WAN, VPN, or tunnel.

Features Copy Chapter

• Route by IP, MAC, port, or domain name
• Works with WAN, VPNs (WireGuard, OpenVPN), or tunnels
• Lightweight shell-based implementation
• Optional Web UI integration via LuCI

Full documentation:
https://docs.openwrt.melmac.ca/pbr/

Overview (`net/pppossh/README.md`) Copy Section

This package will add the so-called pppossh protocol support to OpenWrt. The idea is mainly from pvpn project (poor man's VPN over SSH).

PPPoSSH is generally not considered a network setup for production use mainly due to the TCP-over-TCP styles of traffic transport, but it can be quite handy for personal use. And with what's already in OpenWrt, it is really easy and takes little extra space to configure it up and running.

Prerequisites and dependency. Copy Chapter

pppossh depends on either dropbear or openssh-client; dropbear is normally enabled in OpenWrt by default.

The following requirements need to be fulfilled for it to work.

• A SSH account on the remote machine with CAP_NET_ADMIN capability is required.

• Public key authentication must be enabled and setup properly.

  Public key of the one generated automatially by dropbear can be induced by the following command. But you can always use your own (dropbear can work with OpenSSH public key).

  text Copy

  dropbearkey -y -f /etc/dropbear/dropbear_rsa_host_key

• SSH server's fingerprint has to be present in ~/.ssh/known_hosts for the authentication to proceed in an unattended way.

  Manually logging in at least once to the remote server from OpenWrt should do this for you.

How to use it. Copy Chapter

The protocol name to use in /etc/config/network is pppossh. Options are as described below.

• server, SSH server name
• port, SSH server port (defaults to 22).
• sshuser, SSH login username
• identity, list of client private key files. ~/.ssh/id_{rsa,dsa} will
  be used if no identity file was specified and at least one of them must be
  valid for the public key authentication to proceed.
• ipaddr, local ip address to be assigned.
• peeraddr, peer ip address to be assigned.
• ssh_options, extra options for the ssh client.
• peer_pppd_options, extra options for the pppd command run on the peer side.
• use_hostdep, set it to 0 to disable the use of proto_add_host_dependency. This is mainly for the case that the appropriate route to server is not registered to netifd and thus causing a incorrect route being setup.

Tips Copy Chapter

An uci batch command template for your reference. Modify it to suite your situation.

uci batch <<EOF
delete network.fs
set network.fs=interface
set network.fs.proto=pppossh
set network.fs.sshuser=root
set network.fs.server=ssh.example.cn
set network.fs.port=30244
add_list network.fs.identity=/etc/dropbear/dropbear_rsa_host_key
set network.fs.ipaddr=192.168.177.2
set network.fs.peeraddr=192.168.177.1
commit
EOF

Allow forward and NAT on the remote side (ppp0 is the peer interface on the remote side. eth0 is the interface for Internet access).

sysctl -w net.ipv4.ip_forward=1
iptables -t filter -A FORWARD -i ppp0 -j ACCEPT
iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

It's possible that pppd may output protocol negotiation incompatibilities issues to syslog, such as something like the following which did not hurt the connectivity and was annoying only because we thought it can do better.

Sun Oct 25 09:45:14 2015 daemon.err pppd[22188]: Received bad configure-rej:  12 06 00 00 00 00

To debug such problems, we can try adding option pppd_optinos debug to the interface config. In the above case, it's a LCP CCP configure rej (the CCP options struct is exactly 6 octets in size as indicated in source code pppd/ccp.h) and since the internet fee is not charged on the bytes transferred, I will just use noccp to disable the negotiation altogether.

Also to optimize bulk transfer performance, you can try tweaking the ciphers. OpenSSH client does not support none cipher by default and you have to patch and install it by yourself. Another option is to try ciphers like arcfour and blowfish-cbc. In my case, arcfour has the best throughput.

option ssh_options '-o "Ciphers arcfour"'

Overview (`net/safe-search/Readme.md`) Copy Section

Package: net/safe-search

This package prevents adult content from appearing in search results by
configuring dnsmasq to force all devices on your network to use Google and
Bing's Safe Search IP addresses. This is designed to be appropriate for most
businesses and families. The default filtering rules do not interfere with
normal web browsing.

Enabled and disable Safe Search by editing /etc/config/safe-search . To make
your changes active, run safe-search-update.

Currently Supported:

• Enabled By Default
  • www.bing.com Safe Search
    • https://help.bing.microsoft.com/#apex/18/en-US/10003/0
  • DuckDuckGo.com Safe Search
    • https://duck.co/help/features/safe-search
  • www.Google.com Safe Search
    • https://support.google.com/websearch/answer/186669
• Not Enabled By Default:
  • youtube Safe Search
    • https://support.google.com/a/answer/6214622
    • https://support.google.com/a/answer/6212415
    • https://www.youtube.com/check_content_restrictions
    • Not enabled because it is designed for children, and may annoy adults...

Overview (`net/shunt/README.md`) Copy Section

shunt - policy based routing by mac, source, destination and domain

Table of Contents Copy Chapter

• Description
• Quick Start
• Main Features
• Prerequisites
  • Which tunnels work
• Installation and Usage
• shunt CLI interface
• shunt config options
• How addresses are learned
  • What polling costs
• Examples
• What it shells out to
• What shunt creates on the system
• Coexistence with pbr and mwan3
• Troubleshooting & debug options
• Known limitations
• Support
• Removal
• Donations

Description Copy Chapter

shunt routes selected traffic into a policy interface - a VPN tunnel, a second uplink, a mobile connection - chosen by client address, client MAC, destination or domain. It keeps its own nftables table and one routing table per policy, so it coexists with fw4 and with other routing tools instead of competing with them.

The one thing that defines the project: shunt is not bound to any DNS backend. It works unchanged with dnsmasq, unbound, smartdns, AdGuard Home or anything else, because it never asks the resolver for anything and never sits in the DNS path. Domain to address mapping comes from two sources shunt owns itself, described under How addresses are learned.

Quick Start Copy Chapter

For a typical setup these few steps are enough - see the sections below for details:

1. Install the LuCI companion package: apk update && apk add luci-app-shunt (this pulls in the shunt backend as a dependency).
2. Make reverse path filtering loose and give the policy interface a masquerading firewall zone - both once, both shown under Prerequisites. Without the first, marked traffic is dropped; without the second it is marked and routed and then goes nowhere, which looks exactly like shunt not working.
3. Open LuCI under Services -> shunt, add a policy on the Policies tab: pick the Interface, name the clients under Source addresses or Source MAC addresses, and list the Domains you want routed.
4. Start and verify:

/etc/init.d/shunt enable
/etc/init.d/shunt start
shunt check

Please note: a domain policy only takes effect for a client's next connection to an address that has just been learned - see Known limitations.

Main Features Copy Chapter

• Routes by client address, client MAC, ingress device, destination CIDR, port and domain, in any combination
• Resolver independent: works with any DNS backend, and with an encrypted upstream, because it reads the plaintext leg between client and resolver
• Wildcard domains (*.example.com), learned passively as clients use them
• Domain and address lists from a file - a community-maintained set of thousands of names or networks, without a single UCI entry per line
• Per-policy killswitch: reject the traffic when the interface or proxy is gone, instead of leaking it out of the normal uplink - clients fail at once rather than on a timeout
• Per-policy action: route marks the traffic for the policy interface, bypass exempts it from every policy below, tproxy hands it to a transparent proxy on the router
• Your own networks stay reachable from a policy client, without listing them anywhere
• Puts its own table back when something deletes it, fw4 flush included
• Own nftables table and routing tables, disjoint mark range - runs beside pbr and mwan3
• IPv4 and IPv6 throughout, with a MAC selecting a host in both at once
• Per-element counters on every set, a ubus status object and a LuCI frontend
• No dependency on a specific DNS backend, no resolver configuration, no include files, no hooks into fw4's ruleset

Prerequisites Copy Chapter

• OpenWrt with fw4/nftables
• ucode plus ucode-mod-fs, ucode-mod-socket, ucode-mod-uci, ucode-mod-uloop, ucode-mod-resolv, ucode-mod-ubus, ucode-mod-rtnl, ucode-mod-log and rpcd-mod-ucode - all pulled in by the package; ip is not needed, routes and rules are written over rtnetlink

kmod-nft-tproxy only for a tproxy policy. It is not pulled in: without it a tproxy policy is skipped as an issue and everything else is applied.

ucode-mod-resolv and ucode-mod-ubus are soft at runtime: without resolv, poll is skipped and the observer carries the service alone; without ubus, gateway discovery and interface events are skipped and the config's own values are used. Both cost one warning in the log, not a failed start.

Which tunnels work Copy Section

Any of them, and there is no supported-protocols list to check against, because shunt never asks what protocol an interface speaks. It consumes two things: the device to route into, and a gateway if one is needed. Both come from netifd, and a device netifd does not manage is taken as given.

• Point to point tunnels - wireguard, OpenVPN tun*, L2TP, PPTP, Tailscale, NetBird and the like - need no gateway at all. The route is default dev <device> table <n>.
• Ethernet style interfaces - OpenVPN tap*, a second wired uplink, a mobile connection - use the gateway discovered from netifd, or gw4/gw6 if you set them.
• Interfaces netifd does not manage work by name too. On OpenWrt this is the exception rather than the rule - wireguard, OpenVPN, L2TP and the rest all have netifd protocols and are managed like any other interface. It applies to a tunnel brought up outside netifd, by wg-quick or a script of your own. If such an interface does need a gateway, discovery cannot find one and you have to set gw4/gw6 yourself.

WireGuard: route_allowed_ips belongs off, unless the tunnel is the default uplink. shunt renders default dev <device> into the policy's own table, so it needs no route from the tunnel itself. With the option on and allowed_ips 0.0.0.0/0 netifd installs that prefix as a route in main instead, and the whole box follows the tunnel - the situation policy routing exists to avoid. Turning it off is all that is required; nothing else about the peer changes. Where the tunnel is meant to carry everything and the policies carve out the exceptions, leave it on - see Default uplink and exceptions.

AllowedIPs is not a route, and it still applies. route_allowed_ips decides only whether netifd installs routes for those prefixes - they are written to the wireguard configuration either way, and the kernel uses them as its cryptokey filter. A packet whose destination matches no peer's AllowedIPs is dropped inside wireguard, however correctly it was routed there. A policy meant to carry general traffic therefore needs 0.0.0.0/0 on the peer, and ::/0 if it carries IPv6; what actually enters the tunnel is decided by the policy's selectors, not by the peer. Narrowing AllowedIPs to a few subnets is right only when those subnets really are everything the tunnel should ever carry.

The one thing that does not work is anything that is not a routable interface. Tor is the usual example: it normally offers a SOCKS port, and sending traffic there is a redirect, not a route. shunt marks a packet and looks up a routing table; without a device to put a default route on, there is nothing for it to do.

Two kernel-side prerequisites. shunt never changes either one behind your back - the first can be handed to shunt explicitly (rp_filter_manage, below), the second stays with fw4:

rp_filter must be loose on the policy interface. Marked traffic takes an asymmetric path, so strict reverse path filtering drops it. The kernel decides per incoming packet using max(net.ipv4.conf.all.rp_filter, net.ipv4.conf.<dev>.rp_filter), where 2 is loose - so setting the policy interface alone to 2 suffices even while all stays strict. Prefer this: it leaves reverse path filtering intact on every other interface.

cat > /etc/sysctl.d/99-shunt.conf <<'EOF'
net.ipv4.conf.phy0-sta0.rp_filter=2
EOF
sysctl -p /etc/sysctl.d/99-shunt.conf

Replace phy0-sta0 with your policy interface's device - the Interface column on the overview shows it - one line per policy device.

There is a boot-order catch. A device that does not exist yet - a tunnel, or a wifi client interface brought up late - has no conf/<dev> entry at boot, so sysctl -p cannot set it and skips the line. When the device finally appears it inherits net.ipv4.conf.default.rp_filter, and if that is strict the device comes up strict and stays that way until the next sysctl -p - which for most setups means until the next reboot, i.e. never in practice. Two ways around it: set net.ipv4.conf.default.rp_filter=2 as well, which makes every later-appearing interface inherit loose (a little broader, but far short of all), or let shunt handle it with the option below.

rp_filter_manage (optional, off by default). With it set, shunt itself sets rp_filter=2 on its own policy devices - at start and again whenever one comes up, which is exactly the boot-order moment a static file misses. It only ever touches the devices shunt routes into, never all or default, and only while the service runs. It is off by default because changing a security setting should be a deliberate choice:

uci set shunt.@global[0].rp_filter_manage='1'
uci commit shunt
/etc/init.d/shunt restart

Whichever way you choose, the daemon checks the live per-device values - at start and again whenever a policy interface comes up - and warns, naming the device, only when a policy device exists and is still strict. A device that is not there yet carries no traffic and triggers no warning; it is checked the moment it appears. With rp_filter_manage on the warning therefore simply does not appear - not because the switch is set, but because the values read back are actually loose. With all at 2 (or 0) nothing is ever reported. The package deliberately ships no box-wide sysctl file: rp_filter on all/default is a distribution default OpenWrt sets strict in /etc/sysctl.d/10-default.conf, and loosening it there weakens anti-spoofing on every interface, well beyond shunt's own traffic.

Masquerading stays fw4's job. shunt marks and routes; it does not touch the firewall's NAT. The policy interface needs a zone with masq enabled and forwarding from lan, exactly as any other uplink. If the interface is a netifd one - say a wireguard interface named vpn:

uci add firewall zone
uci set firewall.@zone[-1].name='vpn'
uci set firewall.@zone[-1].input='REJECT'
uci set firewall.@zone[-1].output='ACCEPT'
uci set firewall.@zone[-1].forward='REJECT'
uci set firewall.@zone[-1].masq='1'
uci set firewall.@zone[-1].mtu_fix='1'
uci add_list firewall.@zone[-1].network='vpn'

uci add firewall forwarding
uci set firewall.@forwarding[-1].src='lan'
uci set firewall.@forwarding[-1].dest='vpn'

uci commit firewall
/etc/init.d/firewall reload

network names a logical interface, not a device. For a device netifd does not manage - a tunnel brought up outside netifd - use uci add_list firewall.@zone[-1].device='wg0' instead. And if the policy interface already has a zone, because it is an ordinary second uplink, there is nothing to do here.

Symptoms of getting this wrong are worth knowing, because they do not look like a firewall problem: the prerouting counters rise, nft list set shows the learned address being hit, and the client's connection simply times out.

Installation and Usage Copy Chapter

• Update your router's apk repository (apk update)
• Install the LuCI companion package luci-app-shunt, which also installs the main shunt package as a dependency
• Make rp_filter loose and give the policy interface a masquerading firewall zone - both are one-time steps with copy-paste commands under Prerequisites
• Configure at least one policy, either in LuCI under Services -> shunt or by editing /etc/config/shunt
• Enable and start the service, then run shunt check - it prints the mark, routing table and rule priority of every accepted policy, a bypass policy by name alone, and every rejected value with its reason
• Check the Set Reporting tab to see which addresses were learned, and the Processing Log tab for the service's own messages

shunt CLI interface Copy Chapter

All functions are available from the command line, and the config file can be edited directly if you prefer that to LuCI.

shunt check        # render everything, print marks and issues, change nothing
shunt run          # foreground, the procd service entry point
shunt flush        # tear down table, rules, routes and the mapping file
shunt refresh      # make the running daemon re-read its list files
shunt -v <cmd>     # echo every message to the terminal as well

shunt check is safe at any time, including while the service runs, because it only renders - it never touches the kernel. Run it after every config change. Note that it says nothing about whether the service is running; that is what /etc/init.d/shunt status and the LuCI overview are for.

Exit codes: 0 ok, 1 runtime failure, 2 usage or unusable config.

Logging goes to syslog under the tag shunt, so logread -e shunt shows everything - the daemon's own lines carry its pid, shunt[1234]:. Debug lines stay off unless -v is given or option debug '1' is set - under procd there is no command line, so a bug report needs the config switch. Expect volume: on a router running adblock roughly half of all observed answers are error replies, and debug gives each one a line.

shunt flush is the escape hatch if the daemon ever dies without tearing down. It is idempotent and safe on a box that never ran shunt.

shunt refresh asks the daemon over ubus to re-read every domain_file and dst_file and reports what it found; it is the one change that does not need a restart. Without a running daemon it says so and exits 1 - nothing is lost, the next start reads the files anyway. Everything else in the config still takes /etc/init.d/shunt restart.

shunt config options Copy Chapter

Global section Copy Section

Values below the minimum are clamped, not rejected, and the clamp is logged. entry_ttl should stay well above poll_interval - a polled element is rewritten once its remaining timeout drops below half of entry_ttl, so the default pair refreshes comfortably within two poll cycles. Elements learned by snoop expire with the TTL of the answer instead, see How addresses are learned.

Policy sections Copy Section

Each config policy section is one routing policy. The section must be named, and the name must match [A-Za-z0-9_]{1,24} - it becomes an nftables identifier, so a section without a name, or one with a hyphen or a dot in it, is rejected as an issue and never rendered. LuCI enforces the same pattern when a policy is added.

src, src_mac, src_dev, dst, dst_file, domain and domain_file are lists and may repeat.

Interfaces are resolved through netifd: a logical name resolves to its l3_device, a raw netdev is adopted if netifd knows it, and a device netifd knows nothing about passes through as given - which on OpenWrt means a tunnel started outside netifd, since wireguard and the other tunnel types have netifd protocols of their own. Gateways are discovered from the same dump, merged across sibling entries, because netifd splits families. gw4/gw6 override discovery and always win; on a point to point interface no gateway is needed at all.

There is deliberately no list of supported tunnel protocols. shunt asks netifd for the device and the gateway and renders a default route into the policy table - default via <gw> dev <device> when a gateway is known, default dev <device> when none is needed. Wireguard, OpenVPN in both tun and tap mode, L2TP, PPTP, Tailscale, NetBird, a second physical uplink or a mobile connection all reduce to those two shapes, so none of them needs a case of its own. See Which tunnels work for the one thing that genuinely does not fit.

Selectors are ANDed, client selectors OR each other Copy Section

• src, src_mac or src_dev alone marks everything from those clients
• dst, dst_file, domain, dport or proto alone marks that traffic from everyone - dport '25' by itself routes everybody's smtp
• clients plus destinations marks only those clients' traffic to those destinations

dport and proto AND with everything else, so a policy with a client, a domain and dport 443 covers that client's HTTPS traffic to that domain and nothing more. A port without a protocol matches both tcp and udp - "port 443" almost always means QUIC too, and requiring the protocol would let it slip through unnoticed. If ports or protocols were configured and none of them is usable, the policy is skipped rather than rendered without the narrowing.

This is the single most common source of "it did not work" reports: with a client and a domain both set, a generic curl ifconfig.me from that client correctly takes the normal uplink, because ifconfig.me is not in the domain list. That is the policy working, not failing.

A client MAC, a client address and an ingress device OR each other, so a host may be named either way. If client selectors were configured and none of them is usable - a typo in the only address, say - the policy is skipped with an issue rather than falling back to "every client", which is what an absent client selector otherwise means. The same holds for dst: if every destination address is unusable and no domain is left to narrow the policy, it is skipped rather than widened to every destination.

Selecting clients by MAC Copy Section

src_mac exists mainly for IPv6. Clients prefer rotating privacy addresses for outgoing traffic, so a single IPv6 address is not a usable selector and the LAN prefix covers every host in the segment. A MAC picks exactly one host, in both address families, and keeps doing so when the addresses change. A policy with only src_mac therefore needs no v6 address to route v6.

Three limits, none of them guessable:

• Same layer 2 segment only. Anything behind another router arrives with that router's MAC.
• Never the router itself. The output chain sees traffic the router generated, which has no ethernet sender, so MAC rules are not installed there. An address based policy does cover the router; a MAC-only one does not.
• Phones randomise their MAC, though usually stable per network. Use the address the client shows in your DHCP leases, not the one on the label.

Selecting clients by ingress device Copy Section

src_dev selects everything that arrives on a device - a whole guest network, an IoT VLAN, a second LAN port - in both address families at once. That is what an address selector cannot do for IPv6 on a line with a dynamic prefix: the delegated prefix changes, and the prefix you configured stops matching the day it does. The device does not change.

config policy 'guest'
	option interface 'wg0'
	option fallback  'block'
	list   src_dev   'br-guest'

The entry is a kernel device name - br-guest, lan2, eth0.20 - as ip link shows it, not a netifd interface name. It is matched by name, so a device that does not exist yet is no error: the rule matches nothing until it appears. Like src_mac, it exists in prerouting only, so the router's own traffic is never covered by it.

With keep_local at its default the devices' traffic to your other networks stays local, and traffic to the router itself - DNS, DHCP, LuCI - is delivered locally whatever the mark says. For domain policies the device has to be observed as well: add it to snoop_device, or names its clients ask for are learned by poll alone.

Domain patterns Copy Section

example.com      matches the apex only
*.example.com    matches subdomains only, at any depth, NOT the apex

List both to cover both. This is more typing than dnsmasq's implicit subdomain inclusion, and it is deliberate: dnsmasq's behaviour surprises people regularly, this one does not.

Precedence, in order:

1. an exact match always beats any wildcard
2. among wildcards the longest suffix wins, so *.cdn.example.com beats *.example.com regardless of which policy declared them
3. the same pattern in two policies belongs to both

Rule 3 is what makes one domain usable by two client groups over two different uplinks: the address is written into each policy's set, and each policy's rule matches only its own clients, so they stay apart. Rules 1 and 2 still decide specificity - a shared *.example.com never overrides somebody's exact www.example.com.

Matching is label aligned, never string suffix: evilexample.com does not match *.example.com. A bad pattern is collected as an issue, never fatal.

Domain lists from a file Copy Section

A list domain entry is right for a handful of names. A community-maintained list has thousands, and the place for those is a file, not UCI:

config policy 'vpn'
	option interface   'wg0'
	list  src          '192.168.1.0/24'
	list  domain       'my-own-exception.example'
	list  domain_file  'community.txt'

A bare name lives under /tmp/shunt/, which shunt creates at start; an absolute path is taken as given, for a list kept on a mounted drive. The default is tmpfs on purpose: a list of that size rewritten every day belongs in RAM, not on the flash the overlay sits on. The price is that after a reboot the file is not there until whatever produces it has run again, and that is handled, not worked around - see below.

The file holds one pattern per line in the same two shapes as list domain - example.com or *.example.com - with # starting a comment and blank lines ignored. It is read at start, validated by the same rules, and its patterns join the policy's own; domain and domain_file are additive, and a file may be named by more than one policy. A file that is not there, is unreadable or holds no usable pattern is reported as an issue against the policy and contributes nothing; the policy itself is still rendered, so with domain_file as its only domain selector its learned sets simply stay empty until the file arrives. Bad lines are counted and the first one is named, rather than logging every one of them.

Two things distinguish a file entry from a list domain one, both deliberate:

• File entries are learned by snoop only. poll resolves the names you typed, not the ones from a file - ten thousand names every poll_interval is a DNS storm, not a service. A name from a file reaches its set when a client on the observed LAN segment asks for it, which for a large list is exactly when it matters and never before. The first-connection caveat applies to every one of them.
• shunt reads the file, it does not fetch it. Where the list comes from and how often it changes is a job for cron, a script or a package of its own, and whatever writes the file runs shunt refresh afterwards: the daemon re-reads every domain file and swaps its matcher, and nothing else moves - no restart, the nftables table, the routes and the learned addresses all stay as they are. Write the new list to a temporary name and rename it over the old one, so a half-written file is never read:

uclient-fetch -q -O /tmp/shunt/community.tmp https://example.org/domains.txt && mv /tmp/shunt/community.tmp /tmp/shunt/community.txt && shunt refresh

Run from cron that covers the reboot case as well: the first run after boot creates the file and the refresh loads it. That keeps shunt independent of the network, of any download tool and of the format a list publisher happens to choose - converting hosts or dnsmasq syntax into one pattern per line is one sed away and stays outside the daemon.

What a large list costs: 100k patterns take about two seconds to load and roughly 40 MB of memory on an x86 test box, so expect several seconds and a proportionally smaller footprint on a router, at start and on every refresh. A file above 4 MiB is refused outright as an issue. shunt check prints how many files were read and how many patterns they contributed, shunt refresh does the same for the running daemon, and ubus call shunt status shows the count under files together with the time of the last refresh.

Address lists from a file Copy Section

dst_file is the same mechanism for destinations: a provider's published ranges, a country list, a set of CDN networks - thousands of prefixes that have no business in UCI.

config policy 'streaming'
	option interface 'wg0'
	list   src       '192.168.1.0/24'
	list   dst_file  'provider.txt'

The file holds one IPv4 or IPv6 address or prefix per line, both families mixed as they come, with # starting a comment and blank lines ignored. Name, location, size limit, issues and shunt refresh work exactly as for a domain file, and dst and dst_file are additive. Every entry is checked by the rules a list dst entry is checked by, so a bad line costs that line and never the ruleset.

Overlapping prefixes are fine: the sets are created with auto-merge, so 10.0.0.0/8 next to 10.1.0.0/16 is folded into one instead of failing the whole batch. The policy gets its static sets for both families even while the file is missing, so a later file may bring either family. shunt refresh flushes and refills those sets in one nftables transaction - the set is never seen half-filled - and leaves everything else in place.

A list of 100k prefixes takes about two seconds to read and roughly 40 MB of memory on an x86 test box, and nftables about two seconds to load it, at start and on every refresh; expect several times that on a router.

Actions: route, bypass or tproxy Copy Section

action 'route' (default) is the policy shape everything above describes: matching traffic is marked and looked up in the policy's own table.

action 'bypass' marks nothing. Its rule ends evaluation and the packet leaves shunt untouched, which is the equivalent of pbr's ignore: since a packet takes the first policy it matches, a bypass section carves an exception out of every policy below it. It needs no interface, consumes no mark, and gets no routing table or ip rule of its own - fallback, keep_local and the gateway overrides are not read.

The selectors are the same ones a routing policy uses, domains included, so an exception can be as narrow as one client's traffic to one name:

config policy 'no_vpn'
	option action 'bypass'
	list  src     '192.168.1.50'
	list  domain  'bank.example.com'

config policy 'vpn'
	option interface 'wg0'
	list  src        '192.168.1.50'

Order matters and only order: a bypass section placed after the policy it is meant to except from never sees the packet.

Transparent proxy: tproxy Copy Section

action 'tproxy' hands the selected traffic to a transparent proxy running on the router - hev-socks5-tproxy, sing-box or xray in tproxy mode, or anything else that accepts IP_TRANSPARENT connections. shunt only steers: it does not start, configure or watch the proxy. It needs kmod-nft-tproxy.

config policy 'proxy'
	option action      'tproxy'
	option tproxy_port '1088'
	option fallback    'block'
	list   src         '192.168.1.0/24'
	list   domain      '*.example.com'

The selectors are the usual ones. tproxy carries tcp and udp only, so a tproxy policy without proto covers both, and the proxy must listen for every protocol the policy selects. A policy consumes a mark and gets a routing table holding a single local default dev lo route - that is how the selected packets reach a socket on the router without their destination being rewritten.

shunt delivers to 127.0.0.1 and ::1. A proxy listening on loopback or on the wildcard address is found; one bound to the router's LAN address is not. The address is not left to the kernel on purpose: without one it picks the address of the incoming interface, and a proxy bound to loopback would never be found - the statement fails silently and the traffic is not proxied.

Each family needs a listener that accepts it. A proxy on 0.0.0.0 or 127.0.0.1 serves IPv4 only, so the IPv6 traffic of the policy finds no listener and follows fallback. Listen on :: - which takes both families unless the proxy sets IPV6_V6ONLY - or on both loopback addresses.

Destinations on the router itself are never proxied, nor broadcast and multicast: DNS, DHCP, LuCI and SSH of a selected client reach the router as they would without shunt, and stay reachable with fallback 'block' while the proxy is down. This is tproxy's counterpart to keep_local, built in and not switchable. It covers the router's own addresses only - traffic to your other networks is forwarded unicast and is proxied like any other. A proxy on the router cannot reach those networks on the client's behalf in a useful way, so exempt them with a bypass section above the tproxy policy:

config policy 'no_proxy'
	option action 'bypass'
	list  dst     '192.168.0.0/16'
	list  dst     'fd00::/8'

fallback decides what a new flow does when no listener is found - proxy stopped, crashed, wrong port: main (default) lets it take the normal uplink, block rejects it - tcp with a reset, anything else with ICMP admin-prohibited, so the client gives up at once instead of on a timeout. A flow that was already proxied is rejected the same way once its listener is gone, whatever the fallback. Its state is in the proxy, and its conntrack entry was never NATed, so forwarding the rest of it would put the client's own address on the uplink - measured, which is why this does not follow fallback.

Without proto or dport the policy owns every protocol its clients send, not only what a proxy can take. fallback 'block' therefore also rejects ICMP, ESP, GRE and the rest - while the proxy runs too, so ping from those clients never gets out. Router addresses, broadcast and multicast stay exempt as above, which keeps neighbour discovery and the router's own services working. With proto or dport the policy owns only what it names and block rejects only that; everything else the client sends - QUIC for a policy narrowed to proto 'tcp' - takes the normal uplink.

interface, keep_local and the gateway overrides are not read, and keep_local '1' set explicitly is reported - the exemption of the router's own addresses above takes its place. It would break the policy: main would forward packets the kernel has already handed to the proxy's socket, and the kernel drops those.

Only traffic passing through the router is proxied. tproxy exists in the prerouting hook alone, so the router's own traffic is not touched by a tproxy policy - which also keeps the proxy's upstream connections from looping back into it.

The proxied traffic is delivered to the router itself, so fw4 applies its input rules, not its forward rules. On lan, with input ACCEPT, nothing needs doing. A zone with input REJECT or DROP - a guest network, typically - drops it, and shunt cannot override that from its own table, because a drop in any base chain is final. The packet still carries its original destination port, so a rule on the proxy port does not match; match the policy's mark instead (shunt check prints it):

config rule
	option name   'Allow-guest-tproxy'
	option src    'guest'
	option mark   '0x01000000/0xff000000'
	option target 'ACCEPT'

Example backend: hev-socks5-tproxy. It turns tproxy traffic into connections to a SOCKS5 server and is packaged for OpenWrt. Its sample /etc/hev-socks5-tproxy/main.yml already fits the policy above - tcp and udp on :: port 1088, the SOCKS5 server expected on 127.0.0.1:1080:

socks5:
  port: 1080
  address: 127.0.0.1
  udp: 'udp'

tcp:
  port: 1088
  address: '::'

udp:
  port: 1088
  address: '::'

Point socks5 at your server, then enable the service with uci set hev-socks5-tproxy.config.enabled='1', uci commit hev-socks5-tproxy and /etc/init.d/hev-socks5-tproxy start. Its own connections to the SOCKS5 server start on the router, so the tproxy policy never sees them; a route policy can still send them through a tunnel.

Local traffic: keep_local Copy Section

A policy that names only clients marks everything those clients send, and the mark decides the routing table before the destination is looked at. Without keep_local that includes traffic to your own networks: a marked packet to another VLAN would find only the policy table's default route and leave through the tunnel, and with fallback 'block' it would be rejected.

keep_local '1' (default) renders a second ip rule per family, on the same mark and one priority ahead of the policy rule, that consults main with the default route suppressed:

ip rule add pref 31001 fwmark 0x1000000/0xff000000 lookup main suppress_prefixlength 0
ip rule add pref 31501 fwmark 0x1000000/0xff000000 lookup 8001

Anything main has a specific route for - every attached subnet, every static route - keeps taking it; everything that would have used the default route falls through to the policy rule. The policy itself is unaffected, because its whole purpose is the default route it renders into its own table.

keep_local '0' renders the policy rule alone. That is the hermetic form: with fallback 'block' nothing marked can leave through another interface, at the price of the local traffic above. Set it only where a leak matters more than reaching your own networks, and expect to name the destinations you still want reachable in a bypass section instead.

Policy precedence Copy Section

Section order in /etc/config/shunt, top to bottom. There is no priority option - one less value to set wrong. A packet matching two policies takes the earlier one; rule evaluation ends at the first match.

Note that domain precedence is resolved before this, at the matcher: the most specific pattern wins even if it sits in a later section.

Fallback: main or block Copy Section

fallback 'main' (default) renders no default route into the policy table, so when the policy interface is down the table is empty and marked traffic falls through to main - the normal uplink. Traffic keeps flowing, unpolicied.

fallback 'block' adds a prohibit default at metric 9999 to the policy table. While the interface is up its own default has the lower metric and wins; when the interface drops, the kernel withdraws that route and the prohibit route catches everything, answering it with ICMP admin-prohibited - a connection attempt fails at once instead of on a timeout, measured. That is the killswitch: traffic belonging to the policy stops rather than leaking out of the wrong interface. It stops at the destinations the policy actually owns - see keep_local for what a marked packet to one of your own networks does, and how to make the killswitch hermetic.

Default uplink and exceptions Copy Section

shunt routes only what its policies select. Everything else follows main, and which uplink main uses is decided by the interface metrics, not by shunt. A box with a normal uplink and a tunnel can therefore be set up either way round:

ISP as default, selected clients through the tunnel. The uplink keeps its default route in main, the tunnel installs none (route_allowed_ips '0'). The policy names the tunnel as its interface:

config policy 'vpn'
	option interface 'wg0'
	list  src_mac    'aa:bb:cc:dd:ee:ff'

Tunnel as default, selected clients through the ISP. The tunnel carries the default route in main (route_allowed_ips '1' and a lower metric than the uplink), and the policy names the uplink as its interface:

config policy 'isp'
	option interface 'wan'
	list  src_mac    'aa:bb:cc:dd:ee:ff'

In both forms the policy's own table decides for its clients in both address families, so the metrics matter only for traffic no policy selects. Set them explicitly on both sides anyway, including wan6 where IPv6 comes from an interface of its own: netifd's default metric 0 stays 0 for IPv4, but the kernel stores an IPv6 route with metric 0 as 1024. An interface left at the default therefore wins the IPv4 default route and loses the IPv6 one against any interface with an explicit metric - unselected clients then leave through different uplinks per family.

fallback 'block' covers the policy's clients only. In the tunnel-as-default form, unselected clients move to the uplink when the tunnel goes down, because netifd withdraws the tunnel's route from main and the uplink's is left. Preventing that is a matter of the firewall, not of shunt.

How addresses are learned Copy Chapter

Two sources feed the same nftables sets, union with an element timeout. They are complementary, not alternative modes.

• poll resolves the configured names through whatever system resolver exists, on a fixed interval. It warms the sets before the first client packet, so first contact does not race. Wildcards are not names and cannot be polled, and names from a domain_file are not polled by design - see Domain lists from a file.
• snoop passively observes DNS responses on the LAN side via AF_PACKET with a BPF filter matching UDP source port 53 - answers, not questions - including one level of VLAN tagging. It covers CDN variance and wildcards, which poll cannot. It reads; it never writes anything back onto the wire and never sits between a client and its resolver. If it dies, DNS keeps working and only the policy stops applying.

The two sources differ in how long an element lives. A snooped element carries the TTL of the answer it came from - the shortest one, when a message mixes several - clamped to the range 60 to entry_ttl seconds. So an address a CDN hands out for 30 seconds is gone from the set about a minute after the last answer that named it, while a name with a day-long TTL is capped at entry_ttl and re-learned on its next answer. A polled element carries entry_ttl: the resolver interface hands back addresses without their TTL, so poll has nothing better than the ceiling. Where both sources see the same address the shorter bound wins - the next snooped answer cuts a polled element down to its TTL, and the write cache only rewrites an element when the new expiry moves by at least half of the lifetime the answer carries, so a burst of identical answers costs one write.

The kernel timeout runs a few seconds past that lifetime: the current write interval plus two seconds, so four on an ordinary box. A client asks again when the TTL runs out, and the write for the new answer reaches the set up to one write interval later; an element timed out to the second would be missing for exactly that gap, and a connection opened in it would start on the normal uplink and stay there. The slack follows the interval because the gap does - on a box where writes are expensive and the interval has grown, see What shunt creates on the system, elements outlive their TTL by correspondingly more.

This is also the honest answer to the question every IP-based policy router gets: what about a CDN address that the domain stops using while some other site starts to? Nothing on layer 3 can tell two names apart once they share an address, shunt included. What shunt can do is not keep the address longer than the resolver would have, which is exactly what the TTL says.

What polling costs Copy Section

"Polling" invites the assumption of waste, so here is the arithmetic. One cycle is a single call asking for A and AAAA of every listed name: two lookups per name per interval, against the local resolver. Ten names at the default 300 seconds is 240 lookups an hour - about what a dozen web page loads cost, on a network whose own DNS traffic runs to hundreds of answers in a few minutes. There is no polling of anything else: no interface scanning, no ruleset re-rendering, no periodic writes. A polled element is only rewritten when its remaining lifetime has dropped below half.

Two costs worth knowing:

• The query is synchronous. A name that does not resolve blocks the cycle until it times out (2s, one retry), which delays the service start noticeably if several are wrong. This is why an unresolvable name is reported by name.
• For names with a TTL shorter than the interval the local cache has expired, so poll does refetch upstream rather than answering from cache.

What that means in practice:

• Pick the device the answers cross on their way to the clients, normally br-lan. It must be an Ethernet type device - a bridge, a VLAN device, a physical port, a wireless interface. A tunnel or PPP interface has no ethernet header, so neither the packet filter nor the decoder can read it, and the failure is silent: nothing matches, nothing is logged.
• Only the client-to-resolver leg matters, and only whether it is encrypted. What the resolver does upstream is irrelevant: the usual OpenWrt setup - unbound or dnsmasq on the router, forwarding upstream over DoT or DoH
  • is fully covered, because the client asked in plain text over the LAN and the answer comes back the same way.
• A client that speaks DoH or DoT itself is invisible, because it bypasses the local resolver. That is the one encryption case that costs coverage.
• One entry per layer 2 segment. A guest or IoT VLAN on its own device never carries the answers of the main LAN, so it needs its own snoop_device entry. A device that cannot be opened costs one warning; the others keep running.
• The router's own lookups are not seen. poll's queries leave through the uplink, not the LAN device.
• Not seen either: DNS over TCP, DNS on a port other than 53, and a second stacked VLAN tag.

A name in a domain list that never resolves is reported once, by name and policy:

poll: www.example.com (policy vpn) has no address - the policy entry has no effect until it resolves

Once on the way in and once on recovery, never in between. The first cycle runs immediately at start, so a typo shows up within seconds. Wildcards cannot produce this message - nothing can tell whether *.example.com was ever meant to match anything.

Examples Copy Chapter

One client, one domain family, over a wireguard tunnel

config policy 'vpn'
	option enabled   '1'
	option interface 'wg0'
	option fallback  'main'
	list  src        '192.168.1.50'
	list  domain     'example.com'
	list  domain     '*.example.com'

A whole IoT VLAN over a mobile uplink, killswitch on

The client is named by MAC, so it is covered in both address families without listing a rotating IPv6 address:

config global
	list  snoop_device 'br-lan'
	list  snoop_device 'br-iot'

config policy 'iot'
	option enabled   '1'
	option interface 'trm_wwan'
	option fallback  'block'
	list  src_mac    'aa:bb:cc:dd:ee:ff'
	list  domain     '*.vendor-cloud.com'

The same domain for two client groups over two uplinks

Both policies claim www.example.com; each routes only its own clients:

config policy 'wwan'
	option interface 'trm_wwan'
	list  src        '10.168.30.70'
	list  domain     'www.example.com'

config policy 'vpn'
	option interface 'wg0'
	list  src        '10.168.1.20'
	list  domain     'www.example.com'

An exception for one client, over a policy that covers the whole subnet

The bypass section comes first, so the packets it matches never reach the policy below it. Everything else from the subnet goes into the tunnel:

config policy 'no_vpn'
	option action 'bypass'
	list  src     '192.168.1.50'
	list  domain  'bank.example.com'
	list  domain  '*.bank.example.com'

config policy 'subnet'
	option interface 'wg0'
	list  src        '192.168.1.0/24'

A whole guest network into the tunnel

br-guest is the device, not the netifd interface. It covers the guest network's IPv4 and IPv6 alike, whatever prefix the provider hands out:

config policy 'guest'
	option interface 'wg0'
	option fallback  'block'
	list   src_dev   'br-guest'

One port for everybody

No client, no destination - every smtp connection leaves through the second uplink:

config policy 'smtp'
	option interface 'wan2'
	list   dport     '25'

A destination range without any domain

config policy 'office'
	option interface 'wg0'
	list  src        '192.168.1.0/24'
	list  dst        '10.0.0.0/8'

What it shells out to Copy Section

Almost nothing. The daemon and the rpcd backend work through ucode's native bindings - fs, socket for the AF_PACKET observer, uci, uloop, ubus, resolv, rtnl and log - and rpcd carries the LuCI side, so there is no shell glue, no awk, no temporary state files. Logging goes to syslog through the binding, not through a logger process per line.

One external command remains:

Routes and rules go over rtnetlink through ucode-mod-rtnl, the same binding the rpcd backend reads them with, so there is no ip process per command and no ip dependency. A route on a device that does not exist yet is reported by the kernel's own reason rather than an exit code, and rp_filter_manage writes the /proc/sys value directly instead of calling sysctl.

Nothing is ever handed to a shell for parsing: system() takes an argument array and only ever runs nft, and popen() only ever runs fixed command lines - nft -f - in the daemon and nft -j list table in the rpcd backend - so no configuration value or captured data reaches a command line.

What shunt creates on the system Copy Chapter

table inet shunt                     own table, see below
  chain prerouting                   filter hook prerouting, priority mangle
  chain output                       route hook output, priority mangle
  set d4_<policy> / d6_<policy>      learned, flags timeout, per-element counter
  set s4_<policy> / s6_<policy>      static dst and dst_file, flags interval, auto-merge, counter
  set c4_<policy> / c6_<policy>      client src selectors, interval, auto-merge, counter
  set m_<policy>                     client MACs, no family digit, counter
  set i_<policy>                     client ingress devices, no family digit, counter

fwmark                               <index> << 24, mask 0xff000000
ct mark                              same bits, set on a flow's first packet
ip rule pref                         31000 + <index> keep_local's main lookup
                                     31500 + <index> the policy table
routing table                        8000 + <index>, for tproxy: local default dev lo
                                     with fallback 'block': prohibit default metric 9999
/etc/iproute2/rt_tables.d/shunt.conf the table name mapping, for `ip route show` only

A bypass policy is only a rule in the prerouting and output chains: no mark, no table, no ip rule, and it does not count against the 255. A tproxy policy has rules in prerouting only, and no keep_local rule. The mark mask is fixed at 0xff000000, which allows 255 policies. The output chain is type route so the router's own marked traffic is re-routed after the mark is set.

Every set carries per-element counters, so "is this element ever hit" is one look at nft list set inet shunt <set> rather than a tcpdump session. The two kinds count different things: nftables tests a rule left to right, so a client set counts every packet that matched the selector, whether or not the destination matched afterwards; a learned set is the last lookup in the rule, so a hit there means the packet really was marked. A busy client beside learned addresses at zero is a client that has not visited any of the routed domains, not a fault.

The table can be deleted from outside, and comes back. fw4 reload and fw4 restart touch only table inet fw4, so shunt's table survives both. fw4 flush does not: it walks nft list tables and deletes every table it finds, shunt's included - and that is exactly what /etc/init.d/firewall stop runs. Nothing in the kernel reports the loss, so the daemon checks that its table is still there once per poll cycle, and immediately whenever a write into a learned set fails. If it is gone, the ruleset is re-applied and the write cache is dropped, so poll and snoop refill the learned sets rather than suppressing addresses the kernel no longer has:

shunt: ruleset gone from the kernel - re-applying; `fw4 flush`, as run by `/etc/init.d/firewall stop`, deletes every nftables table
shunt: ruleset re-applied - learned addresses refill from the next poll cycle and from snoop

The routes and ip rules are not affected by any of this - they are re-asserted every poll cycle anyway. Until the check runs, marked traffic simply is not marked, so it takes the normal uplink; with fallback 'block' that means the killswitch is not in force either. ubus call shunt status counts the recoveries as reapplied.

Writes are batched, and the interval adapts. nft -f reads the entire ruleset from the kernel before it resolves a single name, so on a box that also runs a tool with very large sets - banIP with 238k elements, measured - one add element costs seconds of CPU, and nft --check alone costs the same. That is a known bug in nftables (netfilter bugzilla #1735, open since 2024), not something shunt can fix, so observed addresses are collected and applied together by a timer.

The interval follows what the last write actually cost, between 2 and 60 seconds: on an ordinary box a write takes milliseconds and the interval stays at its floor, where the batching is invisible. Where it is expensive the interval grows until nftables takes a bounded share of the machine instead of all of it, at the price of a learned address reaching its set later. Both numbers show up under debug.

A reload wipes learned state. Applying the configuration destroys and re-creates the table atomically, so the learned sets start empty. poll rewarms them within one interval and snoop refills from live traffic; expect a short window after a restart where domain policies do not apply yet.

A flow is routed once, on its first packet. The mark a route policy sets is also written to the flow's conntrack entry, and every later packet of the flow in the original direction takes its mark from there and never reaches the set lookups; flows that got no mark, or a bypass, stay settled the same way. That is what makes a set change safe for connections already running: the kernel kills a masqueraded conntrack entry whose output interface changes, so re-marking a live flow would reset it - measured, not assumed. The same rule holds across a reload. Conntrack survives it, so a connection keeps the decision it started with, including the policy index encoded in its mark; if a reload reorders the policies, that index may now belong to a different policy. Existing connections are not re-evaluated against the new configuration, new connections follow it. Reboot, or restart the client's connections, if that matters after a reorder.

Coexistence with pbr and mwan3 Copy Chapter

shunt is an independent implementation, not a fork of pbr and not a drop-in for it - there is no config migration and no attempt at feature parity. Within its scope it is a full alternative.

Running both at once during a migration is safe by construction:

The mark bits are disjoint and all three mask their writes. Where pbr and shunt both match, pbr's lower rule priority wins, deterministically. So move policies over one at a time and retire pbr once its config is empty.

Anything shunt cannot see is worth knowing about: marks set via SO_MARK on a daemon socket (OpenVPN's --mark) or by an eBPF program are invisible to any inspection. If a box uses those, check the mark ranges by hand.

Troubleshooting & debug options Copy Chapter

Did the policy actually match? Copy Section

The authoritative check needs no route lookups at all:

nft reset counters table inet shunt
# generate traffic from the client
nft list chain inet shunt prerouting        # rule counters moved?
tcpdump -ni <policy-interface> host <addr>  # the flow leaves where it should

The wire capture is ground truth - but capture a learned address, not everything: on a router whose policy interface is also a normal uplink, an unfiltered capture shows traffic that has nothing to do with shunt. An IP echo service is a convenient confirmation, but it only discriminates uplinks that actually have different exits.

The route lookup variant asks the kernel directly:

ip route get <addr> mark 0x1000000
ip route get <addr>

The first answer must name the policy table, the second the normal uplink. With keep_local on - the default - pick a destination outside your own networks for this: an address in an attached subnet or behind a static route deliberately answers with main in both lines, and that is the feature working, not the policy failing.

The first line needs iproute2's ip, because BusyBox's route get does not understand mark - one build rejects it outright, the OpenWrt one sends an incomplete netlink request that the kernel answers with EINVAL. shunt itself no longer depends on ip, so install ip-tiny for this check: route and rule are complete there, the tiny build only strips exotic objects. The second line, without a mark, works with BusyBox too.

Adding from <client> iif br-lan makes the lookup more precise, with one further catch worth a confused test session: iif is not optional there. Without it, from a non-local address makes the kernel validate a locally originated lookup and answer ENETUNREACH regardless of any table's content, which reads like broken routing and is not.

What the observer discards, and why Copy Section

Most DNS answers on a network are of no use to a routing policy, so snoop counts what it discarded and why. ubus call shunt status reports those counters, and the LuCI overview shows them with readable labels.

qtype is usually the largest category and that is expected: current browsers and operating systems ask for HTTPS records (type 65) alongside every A and AAAA. noaddr is the other half of that distinction: the question was A or AAAA, the reply is well formed, and the answer section still holds no address - NODATA.

The checks run in order and the first one wins, so these are "first reason to discard" rather than independent counters: a PTR query for a name you route counts as qtype, never as nomatch.

A high discard count is therefore not a fault. The one number that says whether the observer is doing its job is the matched count next to them.

When the whole ruleset is gone Copy Section

/etc/init.d/firewall stop runs fw4 flush, which deletes every nftables table on the box, shunt's among them - fw4 restart and fw4 reload do not. Nothing is marked from that moment, so all policy traffic takes the normal uplink and a fallback 'block' killswitch is not in force either.

The daemon notices this within one poll_interval, or immediately if a learned address is written in the meantime, and re-applies its ruleset; the log says so twice, once for the loss and once for the recovery. nft list table inet shunt and the LuCI overview both show whether the table is there now, and ubus call shunt status counts how often it had to come back:

ubus call shunt status | grep reapplied

A number that keeps climbing means something on the box flushes nftables repeatedly. Look for a service that calls fw4 flush or nft flush ruleset in an init or hotplug script - shunt only puts its own table back, it cannot stop whatever removes it.

When a policy stops applying after a reconnect Copy Section

The kernel removes routes from a policy table when the interface goes down, after which the fwmark rule falls through to main while every counter keeps counting. shunt handles this on two levels: a ubus listener on network.interface rebuilds the route half on ifup/ifdown, and every poll tick replays the route commands as a keeper. Learned sets survive both. If ubus is unavailable, only the keeper remains, so recovery takes up to one poll_interval.

Debug logging Copy Section

uci set shunt.@global[0].debug='1'
uci commit shunt
/etc/init.d/shunt restart
logread -e shunt

Set it back to 0 afterwards. Every observed answer and every set write gets a line, which on a busy network is a lot.

Known limitations Copy Chapter

These are consequences of the design, stated rather than worked around:

• Clients that speak DoH or DoT themselves are invisible to snoop. poll still covers the names you list explicitly; wildcards do not work for those clients. A resolver forwarding upstream over DoT or DoH changes nothing.
• Wildcards require snoop. poll can only resolve names it was given, and *.example.com is not a name.
• One CDN address serves many domains. If a policy routes example.com and the address behind it also serves a thousand other sites, those sites follow the same policy. This is unsolvable at layer 3 by anything that routes on addresses.
• The first connection to a newly seen address takes the old path. snoop learns from the response the client is reading at that moment, so the client's SYN is usually out before the element reaches the set. That connection stays where it started, by design: a flow's route is decided on its first packet and kept on the conntrack entry, so the switch happens at a connection boundary and never mid-stream - see What shunt creates on the system. The next connection to the same host starts on the policy interface. Listing the entry point explicitly closes the gap, because poll warms it before any client asks.
• DNS over TCP is not observed. Port 53 over TCP needs reassembly, which is out of scope; answers large enough to force TCP are rare in the traffic shunt cares about.
• Route and rule application is best effort. At boot a tunnel interface may not exist yet. A rule over an empty table falls through to main, so the failure mode is "policy not applied yet", never "traffic broken". Each distinct reason is one warning line.
• No interface hotplug. A device that appears later is picked up on the next ifup event or within one poll interval, not immediately.
• tproxy is detected by its module file. shunt applies a tproxy policy when nft_tproxy is loaded or installed under /lib/modules. A custom kernel with tproxy built in has neither, and its tproxy policies are skipped as an issue.
• An outside flush of nftables is repaired, not prevented. Any tool may delete shunt's table - fw4 flush does. shunt re-applies it within one poll interval, or sooner, and until then nothing is marked.

Out of scope permanently: resolver-integrated set population (dnsmasq nftset, AdGuard Home etc.). Being independent of the DNS backend is the entire point of the project, so adopting a backend-specific mechanism would give up the one property that distinguishes it. Also out: DSCP tagging and user include files.

Support Copy Chapter

Please report issues with as much detail as possible - the output of shunt check, the relevant part of logread -e shunt with debug enabled, your /etc/config/shunt, and the OpenWrt version of the device. Please join the shunt discussion in this forum thread or contact me by mail [email protected].

Removal Copy Chapter

Stop the service with /etc/init.d/shunt stop, which also tears down the nftables table, the routing tables and the ip rules, then remove the shunt and luci-app-shunt packages if necessary. shunt flush does the teardown alone, should anything be left behind.

Donations Copy Chapter

You like this project - is there a way to donate? Generally speaking "No" - I have a well-paying full-time job and my OpenWrt projects are just a hobby of mine in my spare time.

If you still insist to donate some bucks ...

• I would be happy if you put your money in kind into other, social projects in your area, e.g. a children's hospice
• Let's meet and invite me for a coffee if you are in my area, the “Markgräfler Land” in southern Germany or in Switzerland (Basel)
• Send your money to my PayPal account and I will collect your donations over the year to support various social projects in my area

No matter what you decide - thank you very much for your support!

Have fun!
Dirk

Overview (`net/simple-captive-portal/README.md`) Copy Section

Simple captive portal

This package intercepts/blocks traffic from 'interface' and
redirects http requests to a splash page that you can personalize,
stored in '/etc/simple-captive-portal/'.
After clicking on 'connect' the MAC of the client is allowed,
for 'timeout' seconds (24h), allowing both IPv4 and IPv6.

If your guest interface defaults to input drop or reject (recommended),
make sure to allow tcp 8888-8889 on input (and also dns and dhcp).

Here an example (ipv4) firewall configuration.

config zone
	option name 'guest'
	option forward 'REJECT'
	option output 'ACCEPT'
	option input 'REJECT'
	option network 'guest'

config forwarding
	option dest 'wans'
	option src 'guest'

config rule
	option name 'guest-dhcp'
	option src 'guest'
	option family 'ipv4'
	option proto 'udp'
	option dest_port '67'
	option target 'ACCEPT'

config rule
	option name 'guest-dns'
	option src 'guest'
	option family 'ipv4'
	list proto 'tcp'
	list proto 'udp'
	option dest_port '53'
	option target 'ACCEPT'

config rule
	option name 'guest-portal'
	option src 'guest'
	option family 'ipv4'
	list proto 'tcp'
	option dest_port '8888-8889'
	option target 'ACCEPT'

To disable simple-captive-portal, just unset/comment 'interface' in the uci config.

Overview (`net/static-neighbor-reports/README.md`) Copy Section

static-neighbor-reports

The static-neighbor-reports package allows a user to configure static neighbor reports which
are available for clients to be polled in case they support IEEE802.11k. This greatly improves
the wireless experiences in terms of mobility.

Make sure to enable ieee80211k for each Virtual Access Point (VAP) neighbor reports should be
installed to.

Configuring Copy Chapter

The uci config name is static-neighbor-report. There's currently only the section
type neighbor.

neighbor Copy Section

The following options are supported for neighbor sections:

neighbor_report

This is the binary neighbor report element from a foreign AP. It is required for each neighbor.

disabled

Values other than 0 disable the neighbor. It won't be installed into hostapd in this case.
If this option is missing, the neighbor is implicitly active.

bssid

The BSSID of the foreign AP. This option can usually be omitted, as it's implicitly present in
the first 6 bytes of the binary neighbor report element.

ssid

The SSID of the foreign AP. This option can be omitted, in case it matches the SSID used on the local AP.

iface

Space separated list of hostapd interfaces the neighbor should be installed to.

Retrieving neighbor information Copy Chapter

To retrieve the neighbor informations of an AP to be isntalled on a foreign AP, make sure the UCI option
ieee80211k is set to 1 on the VAP.

Execute ubus call hostapd. rrm_nr_get_own on the AP. To get a list of all available interfaces,
execute ubus list.

The returned information follows this format:

{
    "value": [
        "<BSSID>",
        "<SSID>",
        "<Neighbor report element>"
    ]
}

Overview (`net/swgp-go/README.md`) Copy Section

swgp-go

This readme should help you configure swgp-go.

Configuration Copy Chapter

Edit /etc/swgp-go.json with your desired configuration (Client, Server or both).

If you're configuring a server, also properly allow that port in your firewall.

Note the pprof feature is disabled in this package. If you try to enable it
regardless, swgp-go will show an error on startup.

Start daemon Copy Chapter

Once you have created your config, enable and run swgp-go using its init script:

/etc/init.d/swgp-go enable
/etc/init.d/swgp-go start

Please refer to the Project README for more configuration info and examples.

Overview (`net/tailscale/README.md`) Copy Section

Tailscale

This readme should help you with tailscale client setup.

[!NOTE]
By default this package will use nftables. If you wish to use iptables, the config file /etc/config/tailscale can be modfied, changing the line fw_mode 'nftables' to fw_mode 'iptables'. You can then run /etc/init.d/tailscale restart to restart tailscale using your chosen method

First setup Copy Chapter

First, enable and run daemon

/etc/init.d/tailscale enable
/etc/init.d/tailscale start

Then you should use tailscale utility to get a login link for your device.

Run command and finish device registration with the given URL.

tailscale up

See the OpenWrt wiki for more detailed setup instructions

Overview (`net/tcfilter/README.md`) Copy Section

tcfilter

A thin UCI front-end for persistent tc filter ... ingress rules.

It does not model the flower match/action fields. You write that part as
raw tc syntax in option spec; the package only manages the device, the
pref number, enable/disable, persistence across boot, and re-applying the
rules when the network is reconfigured.

Meant for driving hardware tc-flower offload (e.g. the Realtek DSA PIE
offload) where no higher-level config layer exists.

Config Copy Chapter

/etc/config/tcfilter:

config tcfilter 'global'
	option enabled '1'

config rule
	option label   'Drop-HomePlug-AV (FRITZ!Box)'
	option device  'lan1'
	option enabled '1'
	option pref    '49152'
	option spec    'protocol 0x88e1 flower skip_sw action drop'

The shipped default config carries a few such rules with enabled '0'
as ready-to-use examples (FRITZ!Box powerline discovery, mDNS) — set
device and flip enabled to 1.

label is optional and cosmetic — it only tags the log messages and the
LuCI rows.

spec is everything that would follow

tc filter add dev <device> ingress pref <pref>

• pref is required — it is how the rule is deleted again.
• Use skip_sw so a match the hardware cannot offload fails loudly instead
  of silently installing in software.
• One rule per pref per device.

Commands Copy Chapter

/etc/init.d/tcfilter start        # apply all enabled rules
/etc/init.d/tcfilter stop         # remove them
/etc/init.d/tcfilter reload       # stop + start
/etc/init.d/tcfilter show         # tc -s filter show for every configured device
/etc/init.d/tcfilter reapply_dev lan1

Notes / limitations Copy Chapter

• ingress / clsact only.
• The clsact qdisc is added if missing but never removed on stop (other
  users may share it); only the individual filters are deleted.
• Installed (device, pref) pairs are tracked in /var/run/tcfilter.state
  so a rule removed from the config is still torn down on the next reload.
• Re-apply hooks: hotplug.d/iface runs start on ifup, hotplug.d/net
  runs reapply_dev on netdev add. start is idempotent.
• A procd_add_reload_trigger reloads the service when the tcfilter
  config changes, so LuCI Save & Apply and
  uci commit tcfilter && reload_config take effect on their own; a bare
  uci commit still needs an explicit /etc/init.d/tcfilter reload.
• No dry-run validation — an invalid spec is reported via logread only.
• Free-form spec is passed to tc by word-split (no shell). Anyone who can
  edit the config can install redirect/mirror rules, i.e. tap traffic.

Hardware packet counters (Realtek rtl930x PIE offload) Copy Section

Older rtl930x kernels mis-read the per-rule LOG packet counter: with more
than one offloaded flower rule, only the rule whose PIE rule id was
even-aligned reported a working tc -s hardware packet count and the
others stayed at 0 (rtl930x_packet_cntr_read() assumed the L3-route
counter layout). Dropping / trapping / redirecting was never affected.

Fixed in the kernel driver upstream (openwrt/openwrt#24994); every
offloaded rule now reports its own count. Firmware built before that
patch still shows the old behaviour.

Overview (`net/travelmate/README.md`) Copy Section

Travelmate, a wlan connection manager for travel routers

Table of Contents Copy Chapter

• Description
• Quick Start
• Main Features
• Prerequisites
• Installation and Usage
• Travelmate CLI interface
• Travelmate config options
• Examples
• Best practice and tweaks
• Troubleshooting & debug options
• Support
• Removal
• Donations

Description Copy Chapter

If you're taking your laptop, tablet, or phone on an upcoming vacation or business trip, you'll want to connect with friends or complete work on the go. But many hotels don't have a secure wireless network setup or limit you to using a single device at a time.

Travelmate lets you use a small "travel router" to connect all of your devices at once while having total control over your own personal wireless network.

Travelmate runs on OpenWrt and provides an "uplink" to the hotel's wireless access point/hotspot. Travelmate then becomes the Access Point (AP) for you and your companions, providing secure access to the internet. It manages all the network settings, firewall settings, connections to a hotel network, etc. and automatically (re)connects to configured APs/hotspots as they become available.

Quick Start Copy Chapter

For a typical setup these few steps are enough to get travelmate up and running — see the sections below for details:

1. Install the LuCI companion package: apk update && apk add luci-app-travelmate (this pulls in the travelmate backend as a dependency).
2. Open LuCI under Services → Travelmate and run the Interface Wizard once. It creates the uplink interface, the firewall assignment and the required network settings.
3. Switch to the Wireless Stations tab, scan the radio you want to use as uplink, click Add Uplink... for the desired SSID and enter its credentials.
4. Start and verify the service:

/etc/init.d/travelmate start
/etc/init.d/travelmate status

Please note: configure your AP on a different radio than the uplink whenever your router has more than one. Sharing a single radio between AP and uplink works, but costs a noticeable amount of throughput.

Main Features Copy Chapter

• Easy setup from the LuCI web interface with Interface Wizard and Wireless Station manager
• Display a QR code to transfer the wireless credentials to your mobile devices
• Fast uplink connections
• Supports routers with multiple radios in any order
• Supports all kinds of uplinks, including hidden and enterprise uplinks (WEP-based uplinks are no longer supported)
• Continuously checks the existing uplink quality, e.g. for conditional uplink (dis)connections
• Automatically add open uplinks to your wireless config, e.g. hotel captive portals
• Captive portal detection with a 'heartbeat' function to keep the uplink connection up and running
• Captive portal hook for auto-login configured via uci/LuCI, using an external script (see the examples below)
• VPN hook supports 'wireguard' or 'openvpn' client setups to handle VPN (re)connections automatically
• E-mail hook via 'msmtp' sends notification e-mails after every successful uplink connect
• Proactively scan and switch to a higher priority uplink, replacing an existing connection
• Check router subnet vs. uplink subnet, to show conflicts with the router LAN network
• (Optional) Generate a random unicast MAC address for each uplink connection
• (Optional) Evil twin protection by skipping access points with locally-administered (LAA) BSSIDs
• Configurable retry limit per uplink, with optional unlimited retry mode
• NTP time sync before sending e-mails
• procd init and ntp-hotplug support
• Runtime information available via LuCI and via the 'status' init command
• Log status and debug information to syslog
• STA interfaces operate in an "always off" mode, to make sure that the AP is always accessible

Prerequisites Copy Chapter

• OpenWrt, tested/compatible with current stable and latest OpenWrt snapshot
• The luci-app-travelmate package ensures these dependencies are present:
  • 'dnsmasq' as dns backend
  • 'ubus iwinfo' for wlan scanning
  • 'curl' for connection checking and all kinds of captive portal magic, e.g. cp detection and auto-logins
  • a 'wpad' variant to support various WPA encrypted networks (WEP-based uplinks are no longer supported!)
• optional: 'wireguard' or 'openvpn' for vpn client connections
• optional: 'msmtp' to send out travelmate related status messages via e-mail

Installation and Usage Copy Chapter

• Install OpenWrt on your router and set it up to allow wireless connections. Be sure to set a strong password on the wireless channel(s) so that only you and your companions can use it
• Decide which radio you'll use for the travelmate uplink (radio0, radio1, etc.). 2.4GHz allows a longer (more distant) link, 5GHz provides a faster link. Travelmate works on all radios, but for better performance configure the AP on a separate radio from the one you're planning to use as the uplink
• Install both travelmate and luci-app-travelmate, the application is located in LuCI under the Services menu
• You must use the travelmate Interface Wizard one time to configure the uplink, firewall and other network settings
• Use the Wireless Stations tab to add an uplink station:
  • Scan the radio you chose for the uplink
  • Click Add Uplink... for the desired SSID. If there are multiples, choose the one with the largest Strength
  • Enter the credentials (password, etc.)
  • You should be "on the air" - test by browsing the internet
• You may add additional uplinks for different locations by repeating the previous step
• Happy traveling ...

The buttons at the bottom of the LuCI overview page behave as follows:

While a run cycle is in progress (status processing), all buttons except Stop are temporarily locked to avoid overlapping actions. Stop always stays available, so an unwanted or long running cycle can be interrupted at any time - e.g. right after the Interface Wizard on a fresh setup, when no uplink station has been configured yet.

Travelmate CLI interface Copy Chapter

• All important travelmate functions are accessible via CLI, too. If you're going to configure travelmate via CLI, edit the config file /etc/config/travelmate and enable the service, see the options reference tables below.

~# /etc/init.d/travelmate
Syntax: /etc/init.d/travelmate [command]

Available commands:
	start           Start the service
	stop            Stop the service
	restart         Restart the service
	reload          Reload configuration files (or restart if service does not implement reload)
	enable          Enable service autostart
	disable         Disable service autostart
	enabled         Check if service is started on boot
	scan            [<radio>|<ifname>] Scan for available nearby uplinks
	setup           [<iface>] [<zone>] [<metric>] Setup the travelmate uplink interface, by default 'trm_wwan' with firewall zone 'wan' and metric '100'
	running         Check if service is running
	status          Service status
	trace           Start with syscall trace
	info            Dump procd service info

The setup sub-command is the CLI equivalent of the LuCI Interface Wizard and only needs to be run once. The scan sub-command writes its result to /var/run/travelmate/travelmate.scan, sorted by signal quality, and is used by the Wireless Stations tab in LuCI as well.

The status sub-command prints the current runtime information:

~# /etc/init.d/travelmate status
::: travelmate runtime information
  + travelmate_status  : connected, net ok/100
  + frontend_ver       : 2.4.7-1
  + backend_ver        : 2.4.7-1
  + station_id         : radio0/GlutenfreiVerbunden/-
  + station_mac        : 42:40:45:EC:B3:D1
  + station_interfaces : wwan, -
  + station_subnet     : 10.168.20.0 (lan: 10.200.1.0)
  + run_flags          : autoadd: ✘, captive: ✔, eviltwin: ✘, mail: ✔, netcheck: ✘, ntp: ✔, proactive: ✔, randomize: ✔, vpn: ✘
  + last_run           : mode: start, date / time: 2026-08-06 09:08:24, memory: 412.35 MB available
  + system_info        : cores: 2, fetch: curl, Cudy TR3000 v1, mediatek/filogic, OpenWrt SNAPSHOT (r32287-1c7ec8ab19)

The travelmate_status field reports one of the following states:

A stopped service does not report a state at all, it truncates the runtime file instead - LuCI shows this as stopped.

Travelmate config options Copy Chapter

• Usually the pre-configured travelmate setup works quite well and no manual config overrides are needed. All options listed below apply to the 'global' section:

Please note: 'trm_netcheck' is evaluated independently of 'trm_captive'. A detected captive portal does not count as an error as long as 'trm_captive' is enabled - such an uplink stays connected so that a manual or script based portal login is still possible. With 'trm_captive' disabled travelmate can neither allowlist the portal domain nor run a login script, so a detected portal is treated like a failed connectivity check. Only a failed connectivity check counts, and it is confirmed by a second probe before it is acted on. Such a failure is then handled like a failed connection attempt: after 'trm_maxretry' tries the affected uplink gets disabled in the travelmate config. A longer lasting outage of your upstream provider may therefore disable all configured uplinks, which have to be re-enabled manually.

• Per uplink there is an additional 'uplink' section in the travelmate config, with the following options:

Examples Copy Chapter

VPN client setup
Please read one of the following guides to get a working vpn client setup on your travel router:

• Wireguard client setup guide
• OpenVPN client setup guide

Make sure to uncheck the "Bring up on boot" option during vpn interface setup, so that netifd doesn't interfere with travelmate. Also prevent potential vpn protocol autostarts, e.g. add an additional 'globals' section in newer openvpn uci configs:

config globals 'globals'
        option autostart '0'

Once your vpn client connection setup is correct, you can reference that config in travelmate to handle VPN (re-) connections automatically.

E-Mail setup
To use e-mail notifications you have to set up the package 'msmtp'. Modify the file /etc/msmtprc, e.g. for gmail:

[...]
defaults
auth            on
tls             on
tls_certcheck   off
timeout         5
syslog          LOG_MAIL
[...]
account         trm_notify
host            smtp.gmail.com
port            587
from            [email protected]
user            yyy
password        zzz

Finally enable e-mail support in travelmate and add a valid e-mail receiver address.

Captive portal auto-logins
For automated captive portal logins you can reference an external shell script per uplink. All login scripts have to be executable and located in /etc/travelmate with the extension .login. A login script signals its result via the exit code: 0 means the login succeeded, any other value means it failed. Only 0 makes travelmate re-check the connectivity right away, every other value is just logged. The package ships multiple ready to run auto-login scripts:

• 'wifibahn.login' for german DB railway hotspots
• 'telekom.login' for telekom hotspots (DE)
• 'vodafone.login' for vodafone hotspots (DE)
• 'generic-user-pass.login' a template to demonstrate the optional parameter handling in login scripts

A typical and successful captive portal login looks like this:

[...]
user.info trm-2.4.7-1[26222]: captive portal domain 'www.wifibahn.de' added to dhcp rebind allowlist
user.info trm-2.4.7-1[26222]: captive portal login script for 'www.wifibahn.de' has been finished with rc '0'
user.info trm-2.4.7-1[26222]: connected to uplink 'radio1/WIFI@DB/-' with mac 'B2:9D:F5:96:86:A4' (1/3)
[...]

Building your own login script
The fastest way to a working script is to record the login once by hand and then replay it with curl. Any browser's developer tools can do the recording:

1. Connect a client to the hotspot - either directly, or through travelmate's own AP while the uplink is up - and open the portal page.
2. Open the developer tools (usually F12) and switch to the Network tab. Enable Preserve log (Chromium, Edge, Safari) resp. Persist Logs (Firefox, behind the gear icon) and Disable cache. A portal login almost always ends in a redirect, and without these options the recorded entries are dropped at that point.
3. Perform the login manually and watch which requests are sent.
4. Right-click the request that carries your credentials and choose Copy -> Copy as cURL. You now have the exact URL, method, headers, cookies and form fields as the browser sent them. Save All As HAR resp. Export HAR records the whole session if you want to study it later - note that recent Chromium versions strip cookies and authorization headers from the export unless you allow sensitive data in the devtools settings.
5. Strip the copied command down: the browser adds a lot of Accept*, Sec-* and Priority headers that no portal cares about. Keep the request body, the Content-Type and whatever the portal actually validates, then replace curl's flags with travelmate's ${trm_fetchcmd} ${trm_fetchparm} and --user-agent "${trm_useragent}".
6. Look for values that are only valid for one session - CSRF tokens, session ids, sid parameters. Those must not be copied into the script but fetched at runtime, see wifibahn.login (cookie jar plus awk) or vodafone.login (json response plus jsonfilter) for the two usual patterns.
7. Never hardcode credentials. Pass them via the uplink's script_args option and read them as ${1} and ${2}, like generic-user-pass.login does.
8. Test the script on the router while the portal is actually in the way: sh -x /etc/travelmate/my.login user pass; echo "rc: ${?}". Make sure it only exits 0 when the login really succeeded - a script that reports success too eagerly is worse than one that fails, because travelmate will happily keep the uplink.

The portal domain travelmate detected is in the system log: logread -e "trm-" shows it as captive portal domain '<domain>' added to dhcp rebind allowlist.

Hopefully more scripts for different captive portals will be provided by the community!

Best practice and tweaks Copy Chapter

Radio assignment
If your router has more than one radio, keep the AP and the uplink on separate radios - sharing one radio between both costs a noticeable amount of throughput. Use trm_radio to restrict travelmate to the uplink radio(s) and trm_revradio to change the processing order, e.g. to prefer 5GHz over 2.4GHz.

Signal quality thresholds
trm_minquality (default 35%) decides twice: a scan result below the threshold is not considered as a connection candidate at all, and an existing connection that drops below it is torn down so that travelmate can look for something better. Raising the value makes travelmate switch away earlier, lowering it keeps weak uplinks alive longer. Values well above 50% tend to make travelmate restless in hotels.

Retry behaviour
trm_maxretry (default 3) limits the connection attempts per uplink. When the limit is reached, the affected uplink is disabled in the travelmate config and has to be re-enabled manually - which is intentional for permanently broken credentials, but worth keeping in mind in combination with trm_netcheck. Set trm_maxretry to '0' for unlimited retries if you never want an uplink to be disabled automatically.

Per uplink, revive softens that. With a value of n, an uplink disabled by the retry limit is set back to 'enabled' after n run cycles, so a network that was only temporarily unavailable comes back on its own. Values below 10 are raised to 10, since a run cycle is roughly trm_timeout seconds long and shorter intervals only produce needless reconnect attempts. The number of revivals is capped by the global trm_maxretry, which also means that revive has no effect with trm_maxretry set to '0'. The cycle and round counters are kept in the runtime file '/var/run/travelmate/travelmate.revive', they are never written to the config and are cleared when the service is stopped. The enable and disable itself is still recorded in the travelmate config, so the LuCI station list always shows the real state.

Open uplinks
trm_autoadd adds open networks to your wireless config on the fly, which is handy in hotels and on trains. Keep trm_maxautoadd at a sane value so that a busy location doesn't flood your config, and use trm_ssidfilter to skip the usual noise, e.g. Chromecast* or printer and camera SSIDs.

Privacy and evil twin protection
trm_randomize generates a new random unicast MAC address for each uplink connection, so a hotspot operator can't trivially recognize your router across visits. trm_eviltwin skips access points with a locally administered (LAA) BSSID, which is a cheap indicator for a spoofed access point - note that some legit setups (mesh, repeaters) use LAA BSSIDs as well.

Timing
trm_maxwait (default 30s) is the budget for a single connection attempt and also scales the internal curl timeouts. On slow uplinks or with captive portals that take their time, raising it to 45-60s helps, lowering it makes travelmate give up on weak candidates faster. trm_triggerdelay adds a delay before processing starts after an ifup event, which is useful if your uplink needs a moment to settle.

Subnet conflicts
Travelmate compares the uplink subnet against your router LAN network and logs a warning if both overlap. If you run into this frequently, change your LAN network to something uncommon, e.g. 10.200.1.0/24, because most hotel networks use 192.168.0.0/24 or 192.168.1.0/24.

Troubleshooting & debug options Copy Chapter

Travelmate provides an optional debug mode that writes detailed diagnostic information about every processing step to the system log. Under normal conditions only the relevant status messages are logged, to keep regular runs clean and silent. To enable debug mode, set the option trm_debug to 1.

Whenever you encounter travelmate related processing problems, please enable trm_debug, restart travelmate and check the Log View tab in LuCI (or the syslog via logread -e "trm-").

Typical symptoms:

• No uplink is found although it is in range: compare the reported signal quality in the debug log against trm_minquality, and make sure the uplink is still enabled in the travelmate config - the retry limit may have disabled it
• An uplink connects but has no internet: the debug output of f_net shows the probe host, the effective url and the resulting state (net ok, net cp '<domain>' or net nok). A net cp state means a captive portal was detected and is waiting for a login
• A captive portal login script doesn't run: it has to be executable and located in /etc/travelmate with the extension .login, everything else is rejected for security reasons
• The connection drops right after connecting: check for a subnet conflict warning between the uplink network and your router LAN network

Support Copy Chapter

Please join the travelmate discussion in this forum thread or contact me by mail [email protected]
If you want to report an error, please describe it in as much detail as possible - with (debug) logs, the current travelmate status and your travelmate configuration.

Removal Copy Chapter

Stop the travelmate daemon with /etc/init.d/travelmate stop and remove the travelmate packages if necessary.

Donations Copy Chapter

You like this project - is there a way to donate? Generally speaking "No" - I have a well-paying full-time job and my OpenWrt projects are just a hobby of mine in my spare time.

If you still insist to donate some bucks ...

• I would be happy if you put your money in kind into other, social projects in your area, e.g. a children's hospice
• Let's meet and invite me for a coffee if you are in my area, the “Markgräfler Land” in southern Germany or in Switzerland (Basel)
• Send your money to my PayPal account and I will collect your donations over the year to support various social projects in my area

No matter what you decide - thank you very much for your support!

Have fun!
Dirk

Overview (`net/uneighbord/README.md`) Copy Section

uneighbord

uneighbord synchronizes hostapd 802.11k Neighbor Reports between local
hostapd.* BSSes and other OpenWrt access points on the same LAN, over
IPv6 link-local UDP multicast. Reports are only shared between BSSes with
the same SSID, and installed through hostapd's ubus API.

Requirements Copy Chapter

ucode, ucode-mod-ubus, ucode-mod-uloop, ucode-mod-socket, ucode-mod-uci, ucode-mod-log.

Build and install Copy Chapter

make menuconfig                  # select Network -> uneighbord
make package/uneighbord/compile V=s

Install the resulting package, then:

/etc/init.d/uneighbord enable
/etc/init.d/uneighbord start

Configuration Copy Chapter

config uneighbord 'main'
        option enabled '1'
        option network 'lan'

network is an OpenWrt logical network name (not a device name); its
l3_device is used for multicast membership and scope.

How it works Copy Chapter

Every 30 seconds each AP announces its local Neighbor Reports (from
rrm_nr_get_own) as a small JSON packet to a fixed IPv6 multicast group on
port 32027. For each local BSS, same-SSID reports from other local BSSes
and remote peers are merged, excluding the BSS's own entry, and installed
via rrm_nr_set. Remote peers are dropped after 90 seconds without a
fresh announcement.

uneighbord assumes a trusted L2/backhaul network: announcements are
unauthenticated, so any host able to reach the multicast group can
influence the installed Neighbor Report list.

Debugging Copy Chapter

ubus list 'hostapd.*'
ubus call hostapd.<interface> rrm_nr_list
logread -e uneighbord
ss -6 -u -a -n | grep 32027
ip -6 maddr show dev br-lan

Overview (`net/wg-installer/README.md`) Copy Section

Wireguard Installer Copy Chapter

This tool can be used to automatically create wireguard tunnels. Using rpcd a new wireguard interface is created on the server where the client can connect to.

Installation Copy Chapter

For Server

opkg install wireguard-installer-server

For Client

opkg install wireguard-installer-client

Wiregurad server automatically installs a user and associated ACL to use the wireguard-installer-server features.
The user is called wginstaller and so is the password.

Usage Copy Chapter

Get Usage Statistics

wg-client-installer get_usage --ip 127.0.0.1 --user wginstaller --password wginstaller

Register Tunnel Interface

wg-client-installer register --ip 127.0.0.1 --user wginstaller --password wginstaller --bandwidth 10

Hotplugs Copy Chapter

• wg-installer-server-hotplug-babeld: mesh automatically via wireguard with babeld

Overview (`net/wgsd/README.md`) Copy Section

Wireguard Service Discovery (Mesh) Copy Chapter

This tool allows you to build a mesh from wireguard tunnels and also traversal NAT.

See this article: https://www.jordanwhited.com/posts/wireguard-endpoint-discovery-nat-traversal/
Also see project on github: https://github.com/jwhited/wgsd

Usage Copy Chapter

On server edit /etc/Corefile to select on which port DNS-SD should be serving and also which interface to use.

Here is the example, where port 5353 will be used by coredns, coredns.lan. zone be used for discovery and vpn_wg interface be used to gather peers information.

.:5353 {
  log
  #whoami
  wgsd coredns.lan. vpn_wg
}

On a client you should put to the cron line like that:

1,6,11,16,21,26,31,36,41,46,51,56 * * * * /usr/bin/wgsd-client -device vpn_wg -dns your.central.node:5353 -zone coredns.lan

Note Copy Section

All peers that should connect to each other should know other peers.
So you should setup your central node as a first peer followed with peers.
E.g. let's say we have a Cloud-Router (CR), Alice and the Bob. Then you should configure peers for CR (with the address) and Bob on Alice's side and CR and Alice on Bob's.

Overview (`net/wifischedule/README.md`) Copy Section

wifischedule

Turns WiFi on and off according to a schedule on an openwrt router

Components Copy Chapter

• wifischedule: Shell script that creates cron jobs based on configuration provided in UCI and does all the other logic of enabling and disabling wifi with the use of /sbin/wifi and /usr/bin/iwinfo. Can be used standalone.
• luci-app-wifischedule: LUCI frontend for creating the UCI configuration and triggering the actions. Depends on wifischedule.

Use cases Copy Chapter

You can create user-defined events when to enable or disable WiFi.
There are various use cases why you would like to do so:

1. Reduce power consumption and therefore reduce CO2 emissions.
2. Reduce emitted electromagnatic radiation.
3. Force busincess hours when WiFi is available.

Regarding 1: Please note, that you need to unload the wireless driver modules in order to get the most effect of saving power.
In my test scenario only disabling WiFi saves about ~0.4 Watt, unloading the modules removes another ~0.4 Watt.

Regarding 2: Think of a wireless accesspoint e.g. in your bedrom, kids room where you want to remove the ammount of radiation emitted.

Regarding 3: E.g. in a company, why would wireless need to be enabled weekends if no one is there working?
Or think of an accesspoint in your kids room when you want the youngsters to sleep after 10 pm instead of facebooking...

Configuration Copy Chapter

You can create an arbitrary number of schedule events. Please note that there is on sanity check done wheather the start / stop times overlap or make sense.
If start and stop time are equal, this leads to disabling the WiFi at the given time.

Logging if enabled is done to the file /var/log/wifi_schedule.log and can be reviewed through the "View Logfile" tab.
The cron jobs created can be reviewed through the "View Cron Jobs" tab.

Please note that the "Unload Modules" function is currently considered as experimental. You can manually add / remove modules in the text field.
The button "Determine Modules Automatically" tries to make a best guess determining regarding the driver module and its dependencies.
When un-/loading the modules, there is a certain number of retries (module_load) performed.

The option "Force disabling wifi even if stations associated" does what it says - when activated it simply shuts down WiFi.
When unchecked, its checked every recheck_interval minutes if there are still stations associated. Once the stations disconnect, WiFi is disabled. To ignore associated stations add their MAC to ignore_stations.

Please note, that the parameters module_load, recheck_interval and ignore_stations are only accessible through uci.

UCI Configuration `wifi_schedule` Copy Chapter

UCI configuration file: /etc/config/wifi_schedule:

config global
        option logging '0'
        option enabled '0'
        option recheck_interval '10'
        option modules_retries '10'
#       option ignore_stations 'AA:AA:AA:AA:AA:AA BB:BB:BB:BB:BB:BB'

config entry 'Businesshours'
        option enabled '0'
        option daysofweek 'Monday Tuesday Wednesday Thursday Friday'
        option starttime '06:00'
        option stoptime '22:00'
        option forcewifidown '0'

config entry 'Weekend'
        option enabled '0'
        option daysofweek 'Saturday Sunday'
        option starttime '00:00'
        option stoptime '00:00'
        option forcewifidown '1'

Script: `wifi_schedule.sh` Copy Chapter

This is the script that does the work. Make your changes to the UCI config file: /etc/config/wifi_schedule

Then call the script as follows in order to get the necessary cron jobs created:

wifi_schedule.sh cron

All commands:

wifi_schedule.sh cron|start|startup|stop|forcestop|recheck|getmodules|savemodules|help

    cron: Create cronjob entries.
    start: Start wifi.
    startup: Checks current timewindow and enables/disables WIFI accordingly.
    stop: Stop wifi gracefully, i.e. check if there are stations associated and if so keep retrying.
    forcestop: Stop wifi immediately.
    recheck: Recheck if wifi can be disabled now.
    getmodules: Returns a list of modules used by the wireless driver(s)
    savemodules: Saves a list of automatic determined modules to UCI
    help: This description.

Startup Script: `/etc/init.d/wifi_schedule` Copy Chapter

Makes sure time window is checked and WIFI is enabled or disabled accordingly when powering on the router.

Overview (`net/xl2tpd/README.md`) Copy Section

OpenWrt Package for xl2tpd

xl2tpd is a development from the original l2tpd package originally written by
Mark Spencer, subsequently forked by Scott Balmos and David Stipp, inherited
by Jeff McAdams, modified substantially by Jacco de Leeuw and then forked
again by Xelerance (after it was abandoned by l2tpd.org).

Rationale for inclusion in OpenWrt Copy Chapter

l2tpd has some serious alignment problems on RISC platforms. It also runs
purely in userspace.

Some of the features added in this fork include:

1. IPSec SA reference tracking inconjunction with openswan's IPSec transport
   mode, which adds support for multiple clients behind the same NAT router
   and multiple clients on the same internal IP behind different NAT routers.

2. Support for the pppol2tp kernel mode L2TP.

3. Alignment and endian problems resolved.

hcg

UCI options Copy Chapter

server takes the form host[:port] with port defaults to 1701. It
specifies the l2tp server's address.

checkup_interval tells netifd to check after that many seconds since last
setup attempt to see if the interface is up. If not it should issue another
teardown/setup round to retry the negotiation. This option defaults to 0 and
netifd will not do the check and retry.