• 🎯 Easy Installation: Interactive installer with comprehensive guide
• 🔄 Dual Tunnel Modes: Direct (-L) and reverse (-R) tunneling
• ⚡ Resilient Connection: Uses autossh with SSH multiplexing
• 🛠️ Simple Management: CLI management for logs, restart, and settings
• 📝 YAML Configuration: Settings stored in /etc/backflip/config.yaml
• 🔧 Systemd Service: Auto-start and service management
• 📊 Structured Logging: Logs in /var/log/backflip/ and systemd journal
• 🔐 SSH Key Support: Secure authentication without passwords
• 🌐 Multi-Platform: Works on Ubuntu, Debian, and other Linux distributions

curl -sSfL https://raw.githubusercontent.com/zZedix/BackFlip/main/install.sh | sudo bash

What this does:

• ✅ Installs system dependencies (python3, pip, autossh, openssh-client)
• ✅ Creates Python virtual environment in /opt/backflip
• ✅ Downloads latest Backflip from GitHub
• ✅ Launches interactive configuration wizard
• ✅ Sets up systemd service for auto-start

💡 Local Installation: If you have a local clone, run sudo bash install.sh from the repository root.

For Ubuntu/Debian:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv autossh openssh-client

For CentOS/RHEL/Fedora:

# CentOS/RHEL
sudo yum install -y python3 python3-pip autossh openssh-clients

# Fedora
sudo dnf install -y python3 python3-pip autossh openssh-clients

For Arch Linux:

sudo pacman -S python python-pip autossh openssh

Option A: From GitHub (Recommended)

sudo pip3 install git+https://github.com/zZedix/BackFlip.git

Option B: From Local Source

git clone https://github.com/zZedix/BackFlip.git
cd BackFlip
sudo pip3 install .

sudo backflip-install

The wizard will:

• ✅ Check for required dependencies
• ✅ Prompt for tunnel mode (direct/reverse)
• ✅ Ask for server addresses
• ✅ Configure proxy mappings
• ✅ Set up SSH multiplexing
• ✅ Create systemd service
• ✅ Enable and start the service

backflip

Use the interactive menu to:

• 📊 View logs and status
• 🔄 Restart the tunnel
• ⚙️ Edit configuration
• 🔄 Update the service
• 🗑️ Uninstall Backflip

The installer creates /etc/backflip/config.yaml. Example:

mode: "direct"
server_iran: "iran.example.com"
server_foreign: "us.example.com"
tunnel_port: 443
proxies:
  - local_port: 8080
    remote_host: us.example.com
    remote_port: 8080
  - local_port: 8443
    remote_host: us.example.com
    remote_port: 8443
mux: true

💡 Note: Update the file manually or through backflip → Edit Settings. After changes, restart the service to apply them.

If you provide a password during installation, Backflip automatically sets mux: false to avoid ControlMaster prompts. To re-enable multiplexing with key-based authentication:

1. Generate a key for the Backflip service user (root) on the Iran server

   sudo ssh-keygen -t ed25519 -f /root/.ssh/backflip -N ''

2. Install the public key on the foreign server

   sudo ssh-copy-id -i /root/.ssh/backflip root@your-foreign-host

3. Reference the key via /root/.ssh/config

   Host backflip-foreign
       HostName your-foreign-host
       User root
       IdentityFile /root/.ssh/backflip

4. Update /etc/backflip/config.yaml

   • Set server_foreign: backflip-foreign
   • Remove the password field (or set password: null)
   • Set mux: true

5. Restart Backflip

   sudo systemctl restart backflip

The tunnel now reuses a single SSH control socket and reconnects instantly without storing any password.

• Python 3.10+
• Git

# Clone the repository
git clone https://github.com/zZedix/BackFlip.git
cd BackFlip

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Run the tunnel directly
python -m backflip.tunnel path/to/config.yaml

• Linting: ruff or flake8
• Testing: pytest (if you add tests)
• Type Checking: mypy

backflip
# Then select "Uninstall" option

# Stop and disable service
sudo systemctl disable --now backflip

# Remove service file
sudo rm /etc/systemd/system/backflip.service

# Remove configuration and logs
sudo rm -rf /etc/backflip /var/log/backflip

# Remove Python package
sudo pip3 uninstall backflip

# Reload systemd
sudo systemctl daemon-reload

backflip/
├── __init__.py           # Package initialization
├── cli.py                # Command-line interface
├── config.py             # Configuration management
└── tunnel.py             # SSH tunnel implementation
scripts/
├── __init__.py
└── install.py            # Installation wizard
install.sh                # One-line installation script
pyproject.toml            # Project configuration
README.md / README-fa.md  # Documentation
LICENSE                   # MIT License

We welcome contributions to Backflip Tunnel! Here's how you can help:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Follow the existing code style
   • Add comments for complex logic
   • Update documentation if needed
4. Add tests for new functionality

   pytest tests/

5. Ensure all tests pass
6. Submit a pull request

# Clone the repository
git clone https://github.com/zZedix/BackFlip.git
cd BackFlip

# Install in development mode
pip install -e .

# Run tests
pytest tests/

If you find Backflip Tunnel useful and want to support its development, consider making a donation:

• Bitcoin (BTC): bc1q637gahjssmv9g3903j88tn6uyy0w2pwuvsp5k0
• Ethereum (ETH): 0x5B2eE8970E3B233F79D8c765E75f0705278098a0
• Tron (TRX): TSAsosG9oHMAjAr3JxPQStj32uAgAUmMp3
• USDT (BEP20): 0x5B2eE8970E3B233F79D8c765E75f0705278098a0
• TON: UQA-95WAUn_8pig7rsA9mqnuM5juEswKONSlu-jkbUBUhku6

• ⭐ Star the repository if you find it useful
• 🐛 Report bugs and suggest improvements
• 📖 Improve documentation and translations
• 🔗 Share with others who might benefit

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 Backflip Tunnel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Important Legal Notice:

• Educational Purpose: This software is provided for educational and research purposes only.
• Legal Compliance: Users are responsible for ensuring compliance with all applicable laws and regulations in their jurisdiction.
• No Warranty: The software is provided "as is" without any warranty or guarantee of functionality.
• Security Notice: While we strive to maintain security, users should implement additional security measures as appropriate for their use case.
• Network Usage: Users are responsible for ensuring their network usage complies with their ISP's terms of service and local regulations.
• No Liability: The developers and contributors are not liable for any misuse, damage, or legal issues arising from the use of this software.

By using this software, you acknowledge that you have read and understood this disclaimer and agree to use the software at your own risk.