Install and deploy

Debian and Ubuntu packages

Download the amd64 package for your distribution from the GitHub release:

Download SoftGRE 2.0.4

Download SHA256SUMS too, verify the hash and install with sudo apt install ./softgred_2.0.4-1+debian12_amd64.deb (adjust the filename for your system). The package installs the daemon, the dashboard, the DHCP lease hook, the configuration, these guides, logrotate rules and both systemd units. The units are enabled and startup is requested on systemd hosts. Set the capture interface in /etc/softgred/softgred.conf (see Configuration) and inspect /var/log/softgred.log if startup fails.

Container image

GitHub Packages hosts the amd64 production image as ghcr.io/jpereira/softgre:2.0.4 and latest. It runs the daemon and the dashboard together. Configure the capture interface and VLAN mappings in a local softgred.conf, then run it with host networking:

docker pull ghcr.io/jpereira/softgre:2.0.4
docker run --rm --network host --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /absolute/path/softgred.conf:/etc/softgred/softgred.conf:ro ghcr.io/jpereira/softgre:2.0.4

Host networking lets the daemon create interfaces and bridges on the Linux host. The host kernel must support GRE, VLANs, bridges and ebtables; the container cannot supply missing kernel modules. The dashboard listens on port 8080. Authenticate with docker login ghcr.io when package visibility requires it; public images support anonymous pulls. Build the same image locally with docker build -f docker/Dockerfile -t softgre ..

Build from source

Build dependencies are a C11 compiler, Make, Autoconf and Automake, with no third-party libraries. GLib headers (glib.h) and libraries are not required: the hash maps, string buffers, INI parser and process helpers are included in the source tree. Runtime dependencies are ebtables and Python 3 for the dashboard and lease hook.

sudo apt-get install build-essential autoconf automake ebtables iptables iproute2 python3
git clone https://github.com/jpereira/softgre.git
cd softgre
./autogen.sh --prefix=/usr --sysconfdir=/etc --localstatedir=/var --with-piddir=/run
make -j2
make check
sudo make install
sudoedit /etc/softgred/softgred.conf

A default /usr/local installation reads /usr/local/etc/softgred/softgred.conf instead. Use --disable-web to omit the dashboard and --disable-service to omit the TCP API; the dashboard requires the API.

To build a Debian package of the checked-out source, install debhelper as well and run ./autogen.sh && make deb. The target runs the Debian build and regression tests and writes softgred_VERSION_ARCH.deb to the parent directory; it does not install it.

OpenWrt

Configure with --enable-openwrt to build for OpenWrt (musl, procd). The option installs /etc/init.d/softgred (a procd script with respawn) instead of the systemd units, and it turns the dashboard and the Python DHCP lease hook off, since routers rarely carry Python or PHP. The TCP status API stays enabled; pass --disable-service to drop it.

openwrt/softgred/Makefile is a ready package definition. Copy it to package/softgred in a buildroot or SDK (or add the directory to a feed), then select Network -> softgred in make menuconfig, or build it directly:

make package/softgred/compile V=s

The Makefile passes --enable-openwrt to configure. It downloads the release tarball (PKG_SOURCE_URL); PKG_HASH is skip and must be filled in for a feed. The package depends on kmod-gre, ebtables-nft and kmod-nft-bridge. Bridge and 802.1Q support are built into the stock kernel; custom kernels need CONFIG_BRIDGE, CONFIG_VLAN_8021Q and GRE/gretap. Install the .ipk and start it:

opkg install softgred_*.ipk
vi /etc/softgred/softgred.conf
/etc/init.d/softgred enable
/etc/init.d/softgred start

/etc/init.d/softgred reload sends SIGHUP (log reopen). The log is /var/log/softgred.log, which lives in RAM on OpenWrt; point log-file to persistent storage if you need it across reboots. docker/test.openwrt.sh validates this build (see Development).

Run with systemd

Packages install and enable both units. After a source build, install them yourself:

sudo install -m 644 share/softgred.service /etc/systemd/system/softgred.service
sudo install -m 644 share/softgred-web.service /etc/systemd/system/softgred-web.service
sudo systemctl daemon-reload
sudo systemctl enable --now softgred.service softgred-web.service
sudo systemctl status softgred.service softgred-web.service
sudo journalctl -u softgred -u softgred-web -f

softgred.service runs the daemon in the foreground with CAP_NET_ADMIN and CAP_NET_RAW and starts after the network is online. Add a dependency on your network manager's address-ready target if network-online.target alone does not guarantee the capture interface is ready. The daemon wants the web unit, which follows its starts, stops and restarts and runs as an unprivileged dynamic user on 0.0.0.0:8080. Mask softgred-web.service to disable the dashboard. Stop a manually started instance before enabling the unit, because the daemon's PID lock prevents duplicates.

Change the dashboard's address or API endpoint in /etc/default/softgred-web:

sudo tee /etc/default/softgred-web <<'CONF'
SOFTGRE_WEB_BIND=192.168.1.253
SOFTGRE_WEB_PORT=8080
SOFTGRE_API_HOST=127.0.0.1
SOFTGRE_API_PORT=8888
CONF
sudo systemctl restart softgred-web.service

Run without systemd

The installed supervisor starts the daemon and the unprivileged dashboard together, stops both when one exits and propagates shutdown. The production container uses it:

sudo python3 /usr/share/softgred/run-services.py

Open http://SERVER_IP:8080/index.html. Neither the dashboard nor the TCP API provides authentication; use a trusted management network or an access-controlled reverse proxy.