Skip to content

Commit f876b88

Browse files
ayanrajpoot10ayanrajpoot10
committed
docs: add config examples
1 parent c9a56f1 commit f876b88

5 files changed

Lines changed: 211 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Tunn
22

3-
A minimal, cross-platform SSH WebSocket tunneling tool for free internet.
3+
A minimal, cross-platform SSH WebSocket tunneling tool for free internet setups.
44

55
## Installation
66

@@ -22,7 +22,7 @@ go install github.com/FreeNetLabs/tunn@latest
2222
},
2323
"local": {
2424
"type": "http",
25-
"port": 1080
25+
"port": 8080
2626
},
2727
"payload": "GET / HTTP/1.1\r\nHost: example.com\r\nUpgrade: websocket\r\n\r\n",
2828
"timeout": 30,
@@ -35,12 +35,20 @@ go install github.com/FreeNetLabs/tunn@latest
3535
2. Run the tunnel:
3636

3737
```bash
38-
tunn -config config.json
38+
tunn -c config.json
3939
```
4040

41-
3. Connect your applications through the local proxy at `127.0.0.1:1080`.
41+
3. Connect your applications through the local proxy at `127.0.0.1:8080`.
42+
43+
## Examples
44+
45+
Check the `examples/` folder for configs setups and explanations:
46+
47+
- `examples/direct/` — direct HTTP WebSocket tunnel
48+
- `examples/direct-with-sni/` — direct tunnel using TLS SNI
49+
- `examples/proxy/` — proxy-style HTTP WebSocket tunnel
50+
- `examples/proxy-with-sni/` — proxy tunnel using TLS SNI
4251

4352
## License
4453

4554
MIT License
46-

‎examples/direct-with-sni/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Example: direct-with-sni
2+
3+
This example shows a direct SSH WebSocket tunneling setup with TLS Server Name Indication (SNI).
4+
5+
## Config file
6+
7+
The sample file is `config.json`.
8+
9+
```json
10+
{
11+
"host": "ssh-server.com",
12+
"port": 443,
13+
"auth": {
14+
"user": "ssh-username",
15+
"pass": "ssh-password"
16+
},
17+
"local": {
18+
"type": "http",
19+
"port": 8080
20+
},
21+
"payload": "GET / HTTP/1.1\r\nHost: bug-host.com\r\nUpgrade: websocket\r\n\r\n",
22+
"timeout": 30,
23+
"tls": {
24+
"sni": "bug-host.com"
25+
}
26+
}
27+
```
28+
29+
## What this config does
30+
31+
- `host`: connects to the remote server at `ssh-server.com`.
32+
- `port`: connects over port `443`, which is typically used for HTTPS/TLS.
33+
- `auth.user`: SSH username used by the tunnel.
34+
- `auth.pass`: SSH password used by the tunnel.
35+
- `local.type`: local listener type; `http` means `tunn` exposes an HTTP proxy locally.
36+
- `local.port`: local proxy listens on port `8080`.
37+
- `payload`: raw HTTP request sent to the remote host to initiate a WebSocket connection.
38+
- `Host: bug-host.com` is the host name used in the WebSocket upgrade request.
39+
- `Upgrade: websocket` requests a WebSocket tunnel.
40+
- `timeout`: connection timeout in seconds.
41+
- `tls.sni`: sets the TLS Server Name Indication header to `bug-host.com`.
42+
- This is useful when the remote TLS server expects a specific hostname during the TLS handshake.
43+
44+
## Usage
45+
46+
Run `tunn` with this config:
47+
48+
```bash
49+
tunn -config examples/direct-with-sni/config.json
50+
```
51+
52+
Then point your local HTTP proxy client to `127.0.0.1:8080`.

‎examples/direct/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Example: direct
2+
3+
This example shows a direct SSH WebSocket tunneling setup using `tunn`.
4+
5+
## Config file
6+
7+
The sample file is `config.json`.
8+
9+
```json
10+
{
11+
"host": "vps-server.com",
12+
"port": 80,
13+
"auth": {
14+
"user": "ssh-user",
15+
"pass": "ssh-passwrod"
16+
},
17+
"local": {
18+
"type": "http",
19+
"port": 8080
20+
},
21+
"payload": "GET / HTTP/1.1\r\nHost: bug-host.com\r\nUpgrade: websocket\r\n\r\n",
22+
"timeout": 30
23+
}
24+
```
25+
26+
## What this config does
27+
28+
- `host`: connects to the remote server at `vps-server.com`.
29+
- `port`: connects on port `80`, using plain HTTP for the WebSocket handshake.
30+
- `auth.user`: SSH username used by the tunnel.
31+
- `auth.pass`: SSH password used by the tunnel.
32+
- `local.type`: local listener type; `http` means `tunn` exposes an HTTP proxy locally.
33+
- `local.port`: local proxy listens on port `8080`.
34+
- `payload`: raw HTTP request sent to the remote host to initiate a WebSocket connection.
35+
- `Host: bug-host.com` is the host name used in the WebSocket upgrade request.
36+
- `Upgrade: websocket` requests a WebSocket tunnel.
37+
- `timeout`: connection timeout in seconds.
38+
39+
## Usage
40+
41+
Run `tunn` with this config:
42+
43+
```bash
44+
tunn -config examples/direct/config.json
45+
```
46+
47+
Then point your local HTTP proxy client to `127.0.0.1:8080`.

‎examples/proxy-with-sni/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Example: proxy-with-sni
2+
3+
This example shows a SSH WebSocket tunneling setup over CDN proxy using `tunn` with TLS Server Name Indication (SNI).
4+
5+
## Config file
6+
7+
The sample file is `config.json`.
8+
9+
```json
10+
{
11+
"host": "bug-host.com",
12+
"port": 443,
13+
"auth": {
14+
"user": "ssh-username",
15+
"pass": "ssh-password"
16+
},
17+
"local": {
18+
"type": "http",
19+
"port": 8080
20+
},
21+
"payload": "GET / HTTP/1.1\r\nHost: vps-server.com\r\nUpgrade: websocket\r\n\r\n",
22+
"timeout": 30,
23+
"tls": {
24+
"sni": "vps-server.com"
25+
}
26+
}
27+
```
28+
29+
## What this config does
30+
31+
- `host`: connects to the remote server at `bug-host.com`.
32+
- `port`: connects over port `443`, so the remote connection uses TLS.
33+
- `auth.user`: SSH username used by the tunnel.
34+
- `auth.pass`: SSH password used by the tunnel.
35+
- `local.type`: local listener type; `http` means `tunn` exposes an HTTP proxy locally.
36+
- `local.port`: local proxy listens on port `8080`.
37+
- `payload`: raw HTTP request sent to the remote host to initiate a WebSocket connection.
38+
- `Host: vps-server.com` is the host name used in the WebSocket upgrade request.
39+
- `Upgrade: websocket` requests a WebSocket tunnel.
40+
- `timeout`: connection timeout in seconds.
41+
- `tls.sni`: sets the TLS Server Name Indication header to `vps-server.com`.
42+
- This is used when the remote TLS server expects a specific hostname during the handshake.
43+
44+
## Usage
45+
46+
Run `tunn` with this config:
47+
48+
```bash
49+
tunn -config examples/proxy-with-sni/config.json
50+
```
51+
52+
Then point your local HTTP proxy client to `127.0.0.1:8080`.

‎examples/proxy/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Example: proxy
2+
3+
This example shows a SSH WebSocket tunneling setup over CDN proxy using `tunn`.
4+
5+
## Config file
6+
7+
The sample file is `config.json`.
8+
9+
```json
10+
{
11+
"host": "bug-host.com",
12+
"port": 80,
13+
"auth": {
14+
"user": "ssh-username",
15+
"pass": "ssh-possword"
16+
},
17+
"local": {
18+
"type": "http",
19+
"port": 2080
20+
},
21+
"payload": "GET / HTTP/1.1\r\nHost: vps-server.com\r\nUpgrade: websocket\r\n\r\n",
22+
"timeout": 30
23+
}
24+
```
25+
26+
## What this config does
27+
28+
- `host`: connects to the remote server at `bug-host.com`.
29+
- `port`: connects over port `80`, using plain HTTP for the WebSocket handshake.
30+
- `auth.user`: SSH username used by the tunnel.
31+
- `auth.pass`: SSH password used by the tunnel.
32+
- `local.type`: local listener type; `http` means `tunn` exposes an HTTP proxy locally.
33+
- `local.port`: local proxy listens on port `2080`.
34+
- `payload`: raw HTTP request sent to the remote host to initiate a WebSocket connection.
35+
- `Host: vps-server.com` is the host name used in the WebSocket upgrade request.
36+
- `Upgrade: websocket` requests a WebSocket tunnel.
37+
- `timeout`: connection timeout in seconds.
38+
39+
## Usage
40+
41+
Run `tunn` with this config:
42+
43+
```bash
44+
tunn -config examples/proxy/config.json
45+
```
46+
47+
Then point your local HTTP proxy client to `127.0.0.1:2080`.

0 commit comments

Comments
 (0)