# **VPN-Chainer 🛡️**
## *A powerful WireGuard VPN chaining tool with dynamic routing, automated service control, and API support.*
## **🔹 Overview**
VPN-Chainer allows you to **chain multiple WireGuard VPNs together**, dynamically reordering routes for improved anonymity and security. It includes **auto-installation as a system service**, API-based VPN rotation, and a customizable **pre/post spin-up/down hook system**.
Now, you can **optionally test VPN speeds** and **select the fastest VPNs** using `--fastest`.
**📦 Available on PyPI** - Install easily with `pip install vpn-chainer`
---
## **⚡ Features**
✅ **Multi-Hop VPN Chaining** – Connect through multiple WireGuard VPNs in random order.
✅ **Speed-Tested VPN Selection** – Use `--fastest` to pick the top VPNs based on download speed.
✅ **Automatic Routing & Firewall Rules** – Seamless packet forwarding between VPN interfaces.
✅ **Pre/Post Execution Hooks** – Run custom scripts **before and after** VPN chain events.
✅ **Remote API Support** – Securely rotate VPNs via a web API.
✅ **Auto-Installation as a Systemd Service** – Persistently run VPN-Chainer in the background.
---
## **🚀 Installation**
### **1️⃣ Prerequisites**
Ensure you have **Python 3** and **WireGuard** installed:
```bash
sudo apt update
sudo apt install -y python3 python3-pip wireguard
```
### **2️⃣ Install VPN-Chainer from PyPI**
**Easy installation via pip:**
```bash
sudo pip install vpn-chainer
```
### **🔄 Alternative: Install from Source**
If you prefer to install from source:
```bash
git clone https://github.com/a904guy/VPN-Chainer.git
cd VPN-Chainer
sudo python3 setup.py install
```
### **⚡ Quick Start**
After installation, you can immediately start using VPN-Chainer:
```bash
# Install the package
sudo pip install vpn-chainer
# Set up your WireGuard configs in /etc/wireguard/
# Then run with 2 VPNs
sudo vpn-chainer 2
# Or use the fastest VPNs
sudo vpn-chainer 3 --fastest
```
---
## **🛠️ Usage**
### **🔹 Basic Usage**
```bash
sudo vpn-chainer <number_of_vpns>
```
For example, to create a **3-hop VPN chain**:
```bash
sudo vpn-chainer 3
```
### **🔹 Use Speed Testing to Select Fastest VPNs**
To **test all VPNs first** and **pick the top N fastest VPNs**, use `--fastest`:
```bash
sudo vpn-chainer 3 --fastest
```
🚀 **This will:**
- Test **all available VPNs** in `/etc/wireguard/`
- Select **the top 3 fastest VPNs**
- Use them in the **VPN chain**
### **🔹 Install as a Systemd Service**
Automatically install and enable the VPN-Chainer service:
```bash
sudo vpn-chainer 3 --auto-install
```
Once installed, it will **start automatically on boot**.
To **stop or restart** the service:
```bash
sudo systemctl stop vpn-chainer
sudo systemctl restart vpn-chainer
```
To **view logs**:
```bash
sudo journalctl -u vpn-chainer -f
```
---
## **🔗 API Usage**
### **Rotate VPN Remotely**
VPN-Chainer provides an **API to trigger VPN rotations**. The API key is displayed on startup:
```bash
[INFO] VPN-Chainer API running at:
🔗 http://127.0.0.1:5000/rotate_vpn?key=6a1f-45e9...
```
To rotate VPNs:
```bash
curl -X GET "http://127.0.0.1:5000/rotate_vpn?key=YOUR_API_KEY"
```
This will:
- **Tear down** the current VPN chain.
- **Randomly select new VPN configs** *(or use fastest if started with `--fastest`)*.
- **Reestablish routing and firewall rules**.
---
## **⚙️ Hook System (Pre/Post Execution Scripts)**
VPN-Chainer allows you to **run scripts before and after VPN activation/deactivation**.
### **🔹 Hook Script Locations**
Scripts should be placed in:
```bash
/etc/vpn-chainer/hooks/
```
| Hook Script Name | Triggered When |
|------------------------|------------------------------------|
| pre-spin-up.sh | Before the VPN chain starts |
| post-spin-up.sh | After the VPN chain is established |
| pre-spin-down.sh | Before VPNs are torn down |
| post-spin-down.sh | After all VPNs have shut down |
### **🔹 Example Hook: Restart Tor After VPN Starts**
Edit `/etc/vpn-chainer/hooks/post-spin-up.sh`:
```bash
# !/bin/bash
echo "[HOOK] Restarting Tor for anonymity..."
systemctl restart tor
```
Then **enable the hook**:
```bash
chmod +x /etc/vpn-chainer/hooks/post-spin-up.sh
```
---
## **📂 Configuration Files**
VPN-Chainer automatically selects **random WireGuard config files** from:
/etc/wireguard/*.conf
Ensure that **at least the number of VPN configs requested exists**.
Additionally the **Address** line is required.
Example VPN config:
```yaml
[Interface]
PrivateKey = <YOUR_PRIVATE_KEY>
Address = 10.13.36.109/24
DNS = 10.8.0.1
[Peer]
PublicKey = <PEER_PUBLIC_KEY>
Endpoint = 10.10.10.24:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25
```
---
## **❓ Troubleshooting**
### **🔸 VPN Doesn't Start**
- Check that you have **WireGuard installed**:
```bash
which wg
```
If missing, install it:
```bash
sudo apt install wireguard
```
- Ensure you have **enough VPN config files** in `/etc/wireguard/`.
### **🔸 Systemd Service Not Running**
- Check status:
```bash
sudo systemctl status vpn-chainer
```
- Restart it:
```bash
sudo systemctl restart vpn-chainer
```
### **🔸 API Not Responding**
- Ensure VPN-Chainer is running:
```bash
sudo systemctl status vpn-chainer
```
- Check firewall rules (port `5000` must be open):
```bash
sudo ufw allow 5000/tcp
```
---
## **📜 Roadmap**
✔️ **Multi-Hop Randomization**
✔️ **Pre/Post Execution Hooks**
✔️ **Auto-Install as a Systemd Service**
✔️ **Speed-Tested VPN Selection (`--fastest`) (Added in v1.1)**
🔜 **Web Dashboard for Control & Logs**
🔜 **VPN Failover Detection ❓❓**
🔜 **Split-Tunneling (Selective Routing) ❓❓**
🔜 **Submit Your Ideas Via Issues**
---
## **🤝 Contributing**
Want to improve VPN-Chainer? Contributions are welcome! Fork the repository and submit a PR.
1. **Fork & Clone**
git clone https://github.com/a904guy/VPN-Chainer.git
cd vpn-chainer
2. **Make Changes & Test**
sudo python3 vpn-chainer.py 3
3. **Submit a Pull Request**
---
## **📜 License**
This project is licensed under the **MIT License**.
---
## **👨💻 Author**
💡 Created by **Andy Hawkins**
🌐 GitHub: [a904guy GitHub Profile](https://github.com/a904guy)
---
🚀 **VPN-Chainer is your ultimate tool for anonymous, multi-hop VPN tunneling!** 🔥
💬 Have questions or feature requests? Open an **Issue** on GitHub! 😎
Raw data
{
"_id": null,
"home_page": "https://github.com/a904guy/VPN-Chainer",
"name": "vpn-chainer",
"maintainer": "Hawkins.Tech Inc",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "\"Hawkins.Tech Inc\" <projects+vpnchainer@hawkins.tech>",
"keywords": "vpn, wireguard, proxy, networking, security, privacy",
"author": "Andy Hawkins",
"author_email": "Andy Hawkins <andy+vpnchainer@hawkins.app>",
"download_url": "https://files.pythonhosted.org/packages/e0/02/a215ccab123cedcbcf811a5982957e2c3f47a7695498198f4dc3d159f2f3/vpn_chainer-1.3.2.tar.gz",
"platform": null,
"description": "# **VPN-Chainer \ud83d\udee1\ufe0f**\n\n## *A powerful WireGuard VPN chaining tool with dynamic routing, automated service control, and API support.*\n\n\n\n\n\n\n## **\ud83d\udd39 Overview**\n\nVPN-Chainer allows you to **chain multiple WireGuard VPNs together**, dynamically reordering routes for improved anonymity and security. It includes **auto-installation as a system service**, API-based VPN rotation, and a customizable **pre/post spin-up/down hook system**.\n\nNow, you can **optionally test VPN speeds** and **select the fastest VPNs** using `--fastest`. \n\n**\ud83d\udce6 Available on PyPI** - Install easily with `pip install vpn-chainer` \n\n---\n\n## **\u26a1 Features**\n\n\u2705 **Multi-Hop VPN Chaining** \u2013 Connect through multiple WireGuard VPNs in random order. \n\u2705 **Speed-Tested VPN Selection** \u2013 Use `--fastest` to pick the top VPNs based on download speed. \n\u2705 **Automatic Routing & Firewall Rules** \u2013 Seamless packet forwarding between VPN interfaces. \n\u2705 **Pre/Post Execution Hooks** \u2013 Run custom scripts **before and after** VPN chain events. \n\u2705 **Remote API Support** \u2013 Securely rotate VPNs via a web API. \n\u2705 **Auto-Installation as a Systemd Service** \u2013 Persistently run VPN-Chainer in the background. \n\n---\n\n## **\ud83d\ude80 Installation**\n\n### **1\ufe0f\u20e3 Prerequisites**\n\nEnsure you have **Python 3** and **WireGuard** installed:\n\n```bash\nsudo apt update \nsudo apt install -y python3 python3-pip wireguard \n```\n\n### **2\ufe0f\u20e3 Install VPN-Chainer from PyPI**\n\n**Easy installation via pip:**\n\n```bash\nsudo pip install vpn-chainer\n```\n\n### **\ud83d\udd04 Alternative: Install from Source**\n\nIf you prefer to install from source:\n\n```bash\ngit clone https://github.com/a904guy/VPN-Chainer.git \ncd VPN-Chainer \nsudo python3 setup.py install\n```\n\n### **\u26a1 Quick Start**\n\nAfter installation, you can immediately start using VPN-Chainer:\n\n```bash\n# Install the package\nsudo pip install vpn-chainer\n\n# Set up your WireGuard configs in /etc/wireguard/\n# Then run with 2 VPNs\nsudo vpn-chainer 2\n\n# Or use the fastest VPNs\nsudo vpn-chainer 3 --fastest\n```\n\n---\n\n## **\ud83d\udee0\ufe0f Usage**\n\n### **\ud83d\udd39 Basic Usage**\n\n```bash\nsudo vpn-chainer <number_of_vpns> \n```\n\nFor example, to create a **3-hop VPN chain**: \n\n```bash\nsudo vpn-chainer 3 \n```\n\n### **\ud83d\udd39 Use Speed Testing to Select Fastest VPNs**\n\nTo **test all VPNs first** and **pick the top N fastest VPNs**, use `--fastest`: \n\n```bash\nsudo vpn-chainer 3 --fastest \n```\n\n\ud83d\ude80 **This will:**\n- Test **all available VPNs** in `/etc/wireguard/`\n- Select **the top 3 fastest VPNs**\n- Use them in the **VPN chain**\n\n### **\ud83d\udd39 Install as a Systemd Service**\n\nAutomatically install and enable the VPN-Chainer service: \n\n```bash\nsudo vpn-chainer 3 --auto-install \n```\n\nOnce installed, it will **start automatically on boot**.\n\nTo **stop or restart** the service: \n\n```bash\nsudo systemctl stop vpn-chainer \nsudo systemctl restart vpn-chainer \n```\n\nTo **view logs**: \n\n```bash\nsudo journalctl -u vpn-chainer -f \n```\n\n---\n\n## **\ud83d\udd17 API Usage**\n\n### **Rotate VPN Remotely**\n\nVPN-Chainer provides an **API to trigger VPN rotations**. The API key is displayed on startup:\n\n```bash\n[INFO] VPN-Chainer API running at: \n\ud83d\udd17 http://127.0.0.1:5000/rotate_vpn?key=6a1f-45e9... \n```\n\nTo rotate VPNs: \n\n```bash\ncurl -X GET \"http://127.0.0.1:5000/rotate_vpn?key=YOUR_API_KEY\" \n```\n\nThis will:\n- **Tear down** the current VPN chain. \n- **Randomly select new VPN configs** *(or use fastest if started with `--fastest`)*. \n- **Reestablish routing and firewall rules**. \n\n---\n\n## **\u2699\ufe0f Hook System (Pre/Post Execution Scripts)**\n\nVPN-Chainer allows you to **run scripts before and after VPN activation/deactivation**.\n\n### **\ud83d\udd39 Hook Script Locations**\n\nScripts should be placed in:\n\n```bash\n/etc/vpn-chainer/hooks/ \n```\n\n| Hook Script Name | Triggered When |\n|------------------------|------------------------------------|\n| pre-spin-up.sh | Before the VPN chain starts |\n| post-spin-up.sh | After the VPN chain is established |\n| pre-spin-down.sh | Before VPNs are torn down |\n| post-spin-down.sh | After all VPNs have shut down |\n\n### **\ud83d\udd39 Example Hook: Restart Tor After VPN Starts**\n\nEdit `/etc/vpn-chainer/hooks/post-spin-up.sh`: \n\n```bash\n# !/bin/bash \n\necho \"[HOOK] Restarting Tor for anonymity...\" \nsystemctl restart tor \n```\n\nThen **enable the hook**: \n\n```bash\nchmod +x /etc/vpn-chainer/hooks/post-spin-up.sh \n```\n\n---\n\n## **\ud83d\udcc2 Configuration Files**\n\nVPN-Chainer automatically selects **random WireGuard config files** from: \n/etc/wireguard/*.conf \n\nEnsure that **at least the number of VPN configs requested exists**.\nAdditionally the **Address** line is required.\n\nExample VPN config:\n\n```yaml\n[Interface] \nPrivateKey = <YOUR_PRIVATE_KEY> \nAddress = 10.13.36.109/24 \nDNS = 10.8.0.1 \n\n[Peer] \nPublicKey = <PEER_PUBLIC_KEY> \nEndpoint = 10.10.10.24:51820 \nAllowedIPs = 0.0.0.0/0 \nPersistentKeepalive = 25 \n```\n\n---\n\n## **\u2753 Troubleshooting**\n\n### **\ud83d\udd38 VPN Doesn't Start**\n\n- Check that you have **WireGuard installed**: \n\n```bash\nwhich wg \n```\n\nIf missing, install it: \n\n```bash\nsudo apt install wireguard \n```\n\n- Ensure you have **enough VPN config files** in `/etc/wireguard/`.\n\n### **\ud83d\udd38 Systemd Service Not Running**\n\n- Check status: \n\n```bash\nsudo systemctl status vpn-chainer \n```\n\n- Restart it: \n\n```bash\nsudo systemctl restart vpn-chainer \n```\n\n### **\ud83d\udd38 API Not Responding**\n\n- Ensure VPN-Chainer is running: \n\n```bash\nsudo systemctl status vpn-chainer \n```\n\n- Check firewall rules (port `5000` must be open): \n\n```bash\nsudo ufw allow 5000/tcp \n```\n\n---\n\n## **\ud83d\udcdc Roadmap**\n\n\u2714\ufe0f **Multi-Hop Randomization** \n\u2714\ufe0f **Pre/Post Execution Hooks** \n\u2714\ufe0f **Auto-Install as a Systemd Service** \n\u2714\ufe0f **Speed-Tested VPN Selection (`--fastest`) (Added in v1.1)** \n\ud83d\udd1c **Web Dashboard for Control & Logs** \n\ud83d\udd1c **VPN Failover Detection \u2753\u2753** \n\ud83d\udd1c **Split-Tunneling (Selective Routing) \u2753\u2753** \n\ud83d\udd1c **Submit Your Ideas Via Issues** \n\n---\n\n## **\ud83e\udd1d Contributing**\n\nWant to improve VPN-Chainer? Contributions are welcome! Fork the repository and submit a PR.\n\n1. **Fork & Clone** \ngit clone https://github.com/a904guy/VPN-Chainer.git \ncd vpn-chainer \n\n2. **Make Changes & Test** \nsudo python3 vpn-chainer.py 3 \n\n3. **Submit a Pull Request** \n\n---\n\n## **\ud83d\udcdc License**\n\nThis project is licensed under the **MIT License**.\n\n---\n\n## **\ud83d\udc68\u200d\ud83d\udcbb Author**\n\n\ud83d\udca1 Created by **Andy Hawkins** \n\ud83c\udf10 GitHub: [a904guy GitHub Profile](https://github.com/a904guy) \n\n---\n\n\ud83d\ude80 **VPN-Chainer is your ultimate tool for anonymous, multi-hop VPN tunneling!** \ud83d\udd25\n\ud83d\udcac Have questions or feature requests? Open an **Issue** on GitHub! \ud83d\ude0e\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to chain multiple WireGuard VPNs and rotate them dynamically via API",
"version": "1.3.2",
"project_urls": {
"Documentation": "https://github.com/a904guy/VPN-Chainer/blob/main/README.md",
"Homepage": "https://github.com/a904guy/VPN-Chainer",
"Issues": "https://github.com/a904guy/VPN-Chainer/issues",
"Repository": "https://github.com/a904guy/VPN-Chainer"
},
"split_keywords": [
"vpn",
" wireguard",
" proxy",
" networking",
" security",
" privacy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "775cbad7e8c8288dfe7336b6f928338d077c8bf765f88b5ef40fb057ad143090",
"md5": "e48681e668eba6c429ec4b76cb5c4da9",
"sha256": "c15af94b3a5459159fa0ab35a3125d836d2f430c3519b102adc41c8bf9b2a9af"
},
"downloads": -1,
"filename": "vpn_chainer-1.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e48681e668eba6c429ec4b76cb5c4da9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 11884,
"upload_time": "2025-07-26T00:58:11",
"upload_time_iso_8601": "2025-07-26T00:58:11.846382Z",
"url": "https://files.pythonhosted.org/packages/77/5c/bad7e8c8288dfe7336b6f928338d077c8bf765f88b5ef40fb057ad143090/vpn_chainer-1.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e002a215ccab123cedcbcf811a5982957e2c3f47a7695498198f4dc3d159f2f3",
"md5": "af56b0ae0e93f6450394c6919d68fc4d",
"sha256": "cc62badaa20b76f4fb2384714743252de6701ed638c1f1a3a959f28cb9efdc17"
},
"downloads": -1,
"filename": "vpn_chainer-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "af56b0ae0e93f6450394c6919d68fc4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 16176,
"upload_time": "2025-07-26T00:58:13",
"upload_time_iso_8601": "2025-07-26T00:58:13.090344Z",
"url": "https://files.pythonhosted.org/packages/e0/02/a215ccab123cedcbcf811a5982957e2c3f47a7695498198f4dc3d159f2f3/vpn_chainer-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 00:58:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "a904guy",
"github_project": "VPN-Chainer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
"==",
"3.1.1"
]
]
},
{
"name": "setproctitle",
"specs": [
[
"==",
"1.3.5"
]
]
},
{
"name": "speedtest-cli",
"specs": [
[
"==",
"2.1.3"
]
]
}
],
"lcname": "vpn-chainer"
}
JSON
