bashforward

External Port Forwarding - WireGuard Server - NGINX Reverse Proxy

bashforward provides interactive menus for port forwarding (iptables DNAT), WireGuard VPN user administration, and NGINX reverse proxy with Let's Encrypt automation. All rules and configurations are stored in a SQLite database (bashforward.db)

Port Forwarding

DNAT rules for IPv4/IPv6 using iptables/ip6tables. Custom chains ensure clean management, with systemd service for boot persistence.

WireGuard Menu

Interactive setup & client management. Based on Nyr/wireguard-install, extended with SQLite storage. QR codes, DNS selection, IPv6 support.

NGINX Reverse Proxy

Automatic generation of reverse‑proxy configs. HTTP → HTTPS with Certbot webroot integration. Database‑driven domain/backend mapping.

Project Structure

The suite consists of five main scripts (plus a shared SQLite database):

File	Purpose
`bashforward.sh`	Main launcher – menu to enter sub‑tools.
`bashforward-portforwarding.sh`	Port forwarding (DNAT) manager.
`bashforward-nyr-wireguard.sh`	WireGuard installation & client manager.
`bashforward-nginx.sh`	NGINX reverse proxy + Let's Encrypt automation.
`bashforward-installer.sh`	Installer script for dependencies, database, and tables.
`bashforward.db`	SQLite database (auto‑created).

Installation

Quick Install (Recommended)

The easiest way to get started is to run the automated installer:


git clone https://github.com/babywhale321/bashforward.git
cd bashforward
chmod +x *.sh
sudo ./bashforward-installer.sh

The installer will:

Install all required packages.
Create the SQLite database file (bashforward.db) and initialise three tables:
- wireguard_entries
- nginx_entries
- portforward_entries
Remove any default NGINX sites that may conflict with the generated configuration.

Note: All scripts assume they are executed from the same directory as the database file (bashforward.db). The database is created automatically with the installer script.

Main Menu (bashforward.sh)

======================= bashforward =======================

1. Port Forwarding Menu  2. Wireguard Menu  3. NGINX menu

q. Quit

Each option calls the appropriate sub‑script in a new Bash session.

Port Forwarding Module

bashforward-portforwarding.sh manages DNAT port forwards using iptables (IPv4) and ip6tables (IPv6). All entries are stored in the portforward_entries table.

Key Features

Custom iptables chains (PORT_FORWARDING_PREROUTING, PORT_FORWARDING_POSTROUTING) keep rules isolated.
Systemd service (port-forwarding.service) applies rules at boot and survives reboots.
Regeneration script (port-forwarding.sh) is generated from the database and contains the exact iptables commands.
IPv4 and IPv6 fully supported with validation.

Menu Options

s – Show current rules (iptables list + database entries).
1 – Add a new forwarding rule (interactive prompts).
2 – Delete a rule by ID.
3 – Reset all port forwarding rules (clears database and flushes chains).

Database Schema: `portforward_entries`

Column	Type	Description
id	INTEGER PRIMARY KEY	Auto‑increment ID
ip_version	TEXT	'v4' or 'v6'
external_port	INTEGER	Public listening port
dest_ip	TEXT	Target internal IP
dest_port	INTEGER	Target port on dest_ip

Example Rule Creation


Enter the IP version (v4/v6): v4
Enter the external port (1-65535): 8080
Enter the destination IP (v4): 10.7.0.2
Enter the destination port (1-65535): 22

The script adds two DNAT rules (TCP+UDP) and a MASQUERADE rule for return traffic. After each change, the systemd service is updated and the rules are applied instantly.

Under the Hood

ensure_iptables_chains() creates the custom chains and adds jump rules if missing. regenerate_script() builds a fresh port-forwarding.sh that flushes the custom chains and re‑adds all DNAT rules. The systemd service runs this script on start.

IPv6 rules use the same logic with ip6tables.

WireGuard Module

bashforward-nyr-wireguard.sh is a fork/adaptation of Nyr/wireguard-install extended with SQLite storage and integration into the bashforward ecosystem.

First‑time Installation

If /etc/wireguard/wg0.conf does not exist, the script guides through a full WireGuard setup:

Detects public IP and asks for endpoint (NAT handling).
Configures interface wg0 with subnet 10.7.0.0/24 (IPv6 ULA fddd:2c4:2c4:2c4::/64).
Creates iptables/ip6tables rules via a systemd service (wg-iptables.service).
Enables IP forwarding.
Adds the first client and displays QR code.

Client Management Menu

After installation, the script presents a menu for ongoing administration:

s – List all clients from the wireguard_entries table.
1 – Add a new client (asks name, DNS, generates keys).
2 – Remove a client (removes peer from wg0.conf and database).

Database Schema: `wireguard_entries`

Column	Type	Description
id	INTEGER PRIMARY KEY	Auto‑increment
name	TEXT UNIQUE	Client identifier (sanitized)
public_key	TEXT	WireGuard public key
preshared_key	TEXT	Preshared key for post‑quantum resistance
ipv4_octet	INTEGER	Last octet of the client IP (10.7.0.2‑10.7.0.254)
dns	TEXT	DNS servers for the client config
created_at	DATETIME	Timestamp (auto)

Client DNS Selection

The script offers several preset DNS options (Google, Cloudflare, Quad9, etc.) or custom resolvers. The chosen DNS is embedded in the generated .conf file.

Peer Management

When adding a client, the script automatically:

Finds the next free IPv4 octet via find_free_octet().
Generates private/public key pair and preshared key.
Inserts record into wireguard_entries.
Appends a [Peer] block to /etc/wireguard/wg0.conf (marked with # BEGIN_PEER name).
Creates client config file (name.conf) and displays QR code.
Reloads the WireGuard interface with wg addconf.

IPv6 support: If an IPv6 address was detected during setup, the ULA prefix fddd:2c4:2c4:2c4::/64 is used, and each client gets a matching IPv6 address (e.g., fddd:2c4:2c4:2c4::octet/128).

Persistence & Firewall

The systemd service wg-iptables.service manages NAT and firewall rules. It is created during installation and remains active. The service uses ExecStart and ExecStop to add/remove rules cleanly.

NGINX Reverse Proxy Module

bashforward-nginx.sh provides a database‑driven NGINX reverse proxy with automatic Let's Encrypt certificate issuance using Certbot webroot method.

How It Works

Uses a dedicated configuration file: /etc/nginx/conf.d/reverse-proxy-generated.conf.
All proxy entries are stored in the nginx_entries SQLite table.
When changes occur, the entire NGINX config is regenerated and tested (nginx -t) before reload.
SSL certificates are obtained via Certbot (certbot certonly --webroot) and automatically included in the HTTPS server block.
Recent improvement: The installer removes any default NGINX sites (like default) to avoid configuration conflicts.

Database Schema: `nginx_entries`

Column	Type	Description
id	INTEGER PRIMARY KEY	Auto‑increment
domain	TEXT UNIQUE	Domain name (e.g., app.example.com)
backend_host	TEXT	Upstream server IP/hostname
backend_port	INTEGER	Upstream port
ssl	INTEGER	1 = SSL enabled, 0 = HTTP only

Menu Options

s – List all configured domains.
1 – Add a new reverse proxy entry (prompts for domain, backend, SSL).
2 – Delete an entry by ID.

Adding a Domain with SSL


Domain (e.g., example.com): myapp.example.org
Backend host (IP or hostname): 10.7.0.2
Backend port: 80
Enable SSL (via Certbot)? (y/n): y

The process:

Inserts the record into the database.
Regenerates reverse-proxy-generated.conf with an HTTP server block (including the .well-known/acme-challenge location).
Reloads NGINX.
Runs Certbot in webroot mode to obtain the certificate.
Regenerates the config again, this time including the HTTPS server block with SSL directives.
Final NGINX reload.

The webroot (/var/www/html) is used for ACME challenges. Ensure port 80 is reachable.

Configuration Details

Generated server blocks include standard proxy headers:


proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

If SSL is enabled and certificates exist, the HTTPS block listens on port 443 and references /etc/letsencrypt/live/domain/fullchain.pem and privkey.pem.

Backup & Safety

Before overwriting the generated config, a backup is saved as reverse-proxy-generated.conf.bak. If the NGINX configuration test fails, the backup is restored automatically.

Shared SQLite Database

All three modules share the same bashforward.db file.

-- portforward_entries
CREATE TABLE IF NOT EXISTS portforward_entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    ip_version TEXT NOT NULL,
    external_port INTEGER NOT NULL,
    dest_ip TEXT NOT NULL,
    dest_port INTEGER NOT NULL
);

-- wireguard_entries
CREATE TABLE IF NOT EXISTS wireguard_entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    public_key TEXT NOT NULL,
    preshared_key TEXT NOT NULL,
    ipv4_octet INTEGER UNIQUE NOT NULL,
    dns TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- nginx_entries
CREATE TABLE IF NOT EXISTS nginx_entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    domain TEXT UNIQUE NOT NULL,
    backend_host TEXT NOT NULL,
    backend_port INTEGER NOT NULL,
    ssl INTEGER DEFAULT 0
);

Advanced Usage & Customization

Change webroot for NGINX – Edit WEBROOT variable in bashforward-nginx.sh.
WireGuard subnet – Modify the Address line in /etc/wireguard/wg0.conf (requires manual adjustment).
Port forwarding custom chains – Names are defined in the script; changing them requires updating the systemd service accordingly.
Logging – All actions are echoed to stdout. You can redirect output for logging.

License & Credits

bashforward is created by Kyle Schroeder (BabyWhale).
The WireGuard module is based on Nyr/wireguard-install (MIT License).
This documentation is part of the bashforward project.

The entire project is released under the MIT License. See the LICENSE file for details.

For issues, contributions, or feature requests, please visit the GitHub repository.

bashforward

Port Forwarding

WireGuard Menu

NGINX Reverse Proxy

Project Structure

Installation

Quick Install (Recommended)

Main Menu (bashforward.sh)

Port Forwarding Module

Key Features

Menu Options

Database Schema: portforward_entries

Example Rule Creation

Under the Hood

WireGuard Module

First‑time Installation

Client Management Menu

Database Schema: wireguard_entries

Client DNS Selection

Peer Management

Persistence & Firewall

NGINX Reverse Proxy Module

How It Works

Database Schema: nginx_entries

Menu Options

Adding a Domain with SSL

Configuration Details

Backup & Safety

Shared SQLite Database

Advanced Usage & Customization

License & Credits

Database Schema: `portforward_entries`

Database Schema: `wireguard_entries`

Database Schema: `nginx_entries`