Reticulum-Interfaces/RNS-over-HTTP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
ivan
2025-09-26 18:00:29 -05:00
parent 3df0ee2fba
commit c57f9a84af
1 changed files with 88 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
README.md
View File

@@ -1,108 +1,136 @@
# RNS-over-HTTP # RNS-over-HTTP
This Reticulum Interface allows using HTTP POST requests as a bidirectional transport layer. It consists of two parts: a client and a server. The server must have a public IP address and be accessible via HTTP. The client only needs internet access. One server can serve any number of clients. A Reticulum interface that tunnels traffic over standard HTTP/S POST requests. This allows Reticulum to operate on networks where only web traffic is permitted, effectively bypassing firewalls, DPI, and other restrictions.
This could be used to bypass firewalls, DPI, and other restrictions. Make sure to adapt the user-agent accordingly or disable it. ## Overview
RNS-over-HTTP creates a bidirectional transport layer using a simple client-server model:
- **Server**: Runs on a machine with a public IP, listening for HTTP requests.
- **Client**: Can be behind a firewall or NAT, only needing outbound internet access.
The client polls the server with HTTP POST requests, sending any outbound data in the request body and receiving inbound data in the response body. This makes the traffic appear as normal web activity.
## How It Works
The interface mimics a persistent connection using a long-polling-like mechanism:
1. The client sends an HTTP POST request to the server, with any pending data in the request body.
2. The server receives the request. It processes the data from the client and immediately sends back any data it has queued for the client in the HTTP response body.
3. The client receives the response and processes the data.
4. After a short, configurable polling interval, the client repeats the process.
This continuous cycle creates a reliable, albeit higher-latency, communication channel.
## Features ## Features
- Bidirectional communication - **Firewall & DPI Evasion**: Tunnels any traffic through standard HTTP/S ports (80/443).
- User-Agent check for security (optional) - **Bidirectional Communication**: Full-duplex data transfer.
- Automatic retry on connection failures - **Simple Setup**: No complex dependencies, just Python and `requests`.
- Configurable polling interval - **Reliable**: Automatic connection retry with exponential backoff.
- MTU support for large data transfers - **Flexible**: Supports custom MTU sizes and configurable polling intervals.
- Runs over standard HTTP ports (typically 80/443) - **Proxy-Friendly**: Works seamlessly behind reverse proxies like Caddy or Nginx.
## Setup ## Getting Started
Dependencies: ### Requirements
Python 3.9+ and Requests - Python 3.9 or later
- `pip` for installing packages
### Installation
1. **Install the `requests` library if not already installed:**
```bash
pip install requests
```
2. **Download the interface script:**
Place `http_interface.py` in a known location on both your client and server machines, for example, `~/.reticulum/interfaces/`.
## Configuration ## Configuration
1. Download http_interface.py to `~/.reticulum/interfaces/` or wherever you want to store it. Set up a `PipeInterface` in your `~/.reticulum/config` file on both the server and client machines.
2. Add a PipeInterface to your `~/.reticulum/config` file on both the server and the client and update the path to the http_interface.py file, as well as the server and client URLs.
### Client Configuration
```ini
[[HTTP Interface]]
type = PipeInterface
enabled = True
command = python3 /path/to/your/http_interface.py client --url http://<server-host>:<port>
# Optional: delay before respawn in seconds
respawn_delay = 2
# Optional: adjust polling interval (default 0.1s)
# command = python3 /path/to/your/http_interface.py client --url http://<server-host>:<port> --poll-interval 0.5
name = HTTP Interface
```
### Server Configuration ### Server Configuration
The server listens for incoming connections from clients.
```ini ```ini
[[HTTP Interface]] [[HTTP Interface]]
type = PipeInterface type = PipeInterface
enabled = True enabled = True
# The command to run the server script. Listens on all interfaces by default.
command = python3 /path/to/your/http_interface.py server --host 0.0.0.0 --port 8080 command = python3 /path/to/your/http_interface.py server --host 0.0.0.0 --port 8080
# Optional: delay before respawn in seconds # Optional: delay before respawning the interface if it crashes.
respawn_delay = 2 respawn_delay = 5
name = HTTP Interface name = HTTP Interface Server
``` ```
### Example using Caddy ### Client Configuration
#### Using a main domain The client connects to the server's public URL.
```ini
[[HTTP Interface]]
type = PipeInterface
enabled = True
# The command to run the client script. Point --url to your server.
command = python3 /path/to/your/http_interface.py client --url http://<your-server-ip-or-domain>
# Optional: delay before respawning the interface if it crashes.
respawn_delay = 5
name = HTTP Interface Client
``` ```
example.com {
## Command-Line Options
You can customize the behavior of the script with these arguments:
- `--mtu`: Maximum Transmission Unit in bytes (default: `4096`).
- `--poll-interval`: Client polling interval in seconds (default: `0.1`).
- `--verbose` or `-v`: Enable verbose debug logging.
- `--host`: Server listen host (default: `0.0.0.0`).
- `--port`: Server listen port (default: `8080`).
- `--disable-user-agent-check`: Disable User-Agent validation on the server.
## Reverse Proxy Setup (Caddy Example)
### Subdomain
```caddy
# Caddyfile for example.yourdomain.com
example.yourdomain.com {
reverse_proxy 127.0.0.1:8080 reverse_proxy 127.0.0.1:8080
header { header {
# Remove server identification # Hide the server software version
-Server -Server
# Add security headers # Prevent MIME-type sniffing
X-Content-Type-Options nosniff X-Content-Type-Options nosniff
} }
} }
``` ```
#### Using a subdomain ### Main Domain
``` ```caddy
api1.example.com { yourdomain.com {
reverse_proxy 127.0.0.1:8080 reverse_proxy 127.0.0.1:8080
header { header {
# Remove server identification # Hide the server software version
-Server -Server
# Add security headers # Prevent MIME-type sniffing
X-Content-Type-Options nosniff X-Content-Type-Options nosniff
} }
} }
``` ```
more examples will be available soon. ## Security Considerations
### Options - **Use HTTPS**: Helps bypass some firewalls and DPI that could potentially see reticulum data.
- **User-Agent Check**: By default, the server validates the `User-Agent` header (`RNS-HTTP-Tunnel/1.0`). This provides basic protection against web crawlers and casual scanning. If you need to bypass sophisticated DPI, you might consider changing this header in the script to mimic a common browser and disabling the check on the server (`--disable-user-agent-check`).
- `--mtu`: Maximum transmission unit (default: 4096 bytes)
- `--poll-interval`: Client polling interval in seconds (default: 0.1)
- `--verbose`: Enable verbose logging
- `--host`: Server listen host (default: 0.0.0.0)
- `--port`: Server listen port (default: 8080)
- `--disable-user-agent-check`: Disable User-Agent validation (server mode only)
## Security
By default, the server validates that incoming requests include the correct User-Agent header (`RNS-HTTP-Tunnel/1.0`) which can be changed but make sure the users that use your server have the correct User-Agent header in the interface. This helps prevent:
- Web crawlers and bots from accessing the tunnel
- Casual browsing attempts
- Unauthorized data collection
You can disable this check with `--disable-user-agent-check`
## License ## License
[MIT License](LICENSE) This project is licensed under the [MIT License](LICENSE).