frp-ezpz

KO | EN

gitlite — search

#javascript #react #typescript #llm #go #golang #android #linux #nodejs #macos #java #windows #security #open-source

(★ 10)

frp-ezpz

frp-ezpz Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# frp-ezpz

Docker image and YAML-driven config generator for [frp](https://github.com/fatedier/frp). Run frp **over an existing TCP tunnel** (SSH port-forward, dnstt, iodine, etc.) with one shared config file on both sides.

## What it does

frp-ezpz wraps frpc and frps in a single container. At startup it reads `conf.yml`, generates the frp TOML, and runs the right processes based on `ROLE`:

| `ROLE=client` | `ROLE=server` |
|---------------|---------------|
| Main frpc dials frps (directly or via a local tunnel port) | frps accepts the control connection |
| Exposes **client** services to the server | Runs a local frpc for **server** services |
| Reaches **server** services via STCP/SUDP visitors | Exposes **client** services via STCP/SUDP visitors |

Proxies use **STCP** (TCP) and **SUDP** (UDP) with a shared `auth.secret`, so frps does not publish ordinary remote TCP/UDP ports — only the control listener and visitor binds on localhost (or addresses you choose).

Typical use cases:

- Reach a home LAN from a VPS (and vice versa) through a slow or censored outer hop
- Bidirectional SOCKS: browse from the server’s IP on the client, or from the client’s LAN on the server
- Expose selected TCP/UDP services without opening frp’s default public proxy ports

Image: `ghcr.io/aleskxyz/frp-ezpz:latest`

## Quick start

```bash
cp conf.example.yml conf.yml
# Edit auth.token, auth.secret, and endpoints.
```

Use the **same** `conf.yml` on both machines. Only `ROLE` differs:

**Client**

```bash
docker run -d \
  --name frp-ezpz \
  --network host \
  -e ROLE=client \
  -v /absolute/path/to/conf.yml:/etc/frp/conf.yml:ro \
  ghcr.io/aleskxyz/frp-ezpz:latest
```

**Server**

```bash
docker run -d \
  --name frp-ezpz \
  --network host \
  -e ROLE=server \
  -v /absolute/path/to/conf.yml:/etc/frp/conf.yml:ro \
  ghcr.io/aleskxyz/frp-ezpz:latest
```

With **`--network host`**, frp binds on the host network stack (no `-p` publishing). On Linux this matches listening on the host’s addresses and ports; Docker Desktop’s host networking differs.

## Example: outer TCP tunnel

The bundled example assumes a **TCP tunnel on the client**: something listens on `127.0.0.1:6000` and forwards to `127.0.0.1:7000` on the server. frpc dials `127.0.0.1:6000`; frps listens on `127.0.0.1:7000`.

**SSH**

```bash
ssh -N -L 6000:127.0.0.1:7000 user@server.example
```

**dnstt**

```bash
# Server
./dnstt-server -udp :53 -privkey-file server.key t.example.com 127.0.0.1:7000
# Client
./dnstt-client -udp 8.8.8.8:53 -pubkey-file server.pub t.example.com 127.0.0.1:6000
```

If you connect to frps directly (no outer tunnel), set `client.connect.server_port` to the server’s bind port (e.g. `7000`) and point `server_addr` at the server IP.

`conf.example.yml` matches the full example below without inline comments.

### What the example exposes

**On the client host**

- **SOCKS5** `127.0.0.1:2080` — reach the **server’s** network (internet as the server sees it)
- **`ssh`** — `127.0.0.1:2222` → SSH on the **server** (`127.0.0.1:22`)
- **`dns`** — UDP `127.0.0.1:5353` → `8.8.8.8:53` on the server side

**On the server host**

- **SOCKS5** `127.0.0.1:1080` — reach the **client’s** network
- **`ssh`** — `127.0.0.1:2222` → SSH on the **client** (`127.0.0.1:22`)
- **`web`** — HTTP `0.0.0.0:8080` → client’s `127.0.0.1:80`
- **`lan-web`** — HTTP `0.0.0.0:8081` → `192.168.10.10:80` on the client LAN

## Transport tuning

The `transport` block tunes the long-lived frp control session. Use identical values in the shared `conf.yml`. These settings apply to frp on top of your outer TCP hop — they do not change SSH, dnstt, or other tunnel protocols.

The full example uses the **normal network** preset. For slow or lossy paths (DNS tunnel, iodine, satellite), swap in the **harsh network** preset.

### Normal network

Stable link: low latency, enough bandwidth, little loss.

```yaml
transport:
  tcp_mux: true
  pool_count: 1
  max_pool_count: 5
  use_encryption: false
  use_compression: false
  heartbeat_interval: -1
  heartbeat_timeout: -1
  dial_server_timeout: 10
  dial_server_keepalive: 7200
  tcp_mux_keepalive_interval: 30
  tcp_keepalive: 30
```

### Harsh network

High latency, low bandwidth, jitter, or packet loss.

```yaml
transport:
  tcp_mux: true
  pool_count: 1
  max_pool_count: 2
  use_encryption: false
  use_compression: true
  heartbeat_interval: 60
  heartbeat_timeout: 360
  dial_server_timeout: 120
  dial_server_keepalive: 1800
  tcp_mux_keepalive_interval: 60
  tcp_keepalive: 180
```

On harsh paths, use explicit heartbeats with a long `heartbeat_timeout` (e.g. 360 s) so multi-minute stalls do not drop the session. Keep `heartbeat_timeout` ≥ `heartbeat_interval`.

When `tcp_mux` is true and heartbeat keys are omitted, the generator defaults them to `-1` (matching frp). Set them explicitly for the harsh preset.

### Field reference

| Key | Maps to (frpc / frps) | Purpose |
|-----|------------------------|---------|
| `tcp_mux` | both | Multiplex streams on one TCP (yamux). Must match on client and server. |
| `pool_count` | client frpc | Pre-opened work connections to frps. |
| `max_pool_count` | frps | Upper bound per proxy; must be ≥ `pool_count`. |
| `use_encryption` | per proxy/visitor | Optional frp payload encryption (separate from TLS). |
| `use_compression` | per proxy/visitor | Compress tunneled payload; helps low-bandwidth paths. |
| `heartbeat_interval` | client + server frpc | App-layer ping interval (s). `-1` disables. |
| `heartbeat_timeout` | client + server frpc, frps | Max silence before disconnect (s). `-1` disables when ≤ 0. |
| `dial_server_timeout` | client frpc | Max wait for the first TCP dial to frps (s). |
| `dial_server_keepalive` | client frpc | OS TCP keepalive on the control connection (s). |
| `tcp_mux_keepalive_interval` | client frpc, frps | Yamux keepalive interval (s). |
| `tcp_keepalive` | frps | OS TCP keepalive on frps control connections (s). |

## Full configuration example

This file is shared by **both** containers. The generator turns it into frpc/frps TOML at startup; only `ROLE` decides which processes run on each host.

**Traffic flow in this example**

```text
[Client host]                         [Server host]
     |                                       |
     |  SSH/dnstt tunnel (outer hop)         |
     |  127.0.0.1:6000 --------------------> 127.0.0.1:7000 (frps)
     |                                       |
Main frpc ----STCP/SUDP----> frps + server frpc (visitors bind on server)
Server frpc visitors <----STCP/SUDP---- frps (bind on client)
```

- **`client.*`** — things on the **client machine**: main frpc dials out, publishes client services, and runs visitors for server services.
- **`server.*`** — things on the **server machine**: frps listens, server frpc handles server-side proxies and visitors for client services.

```yaml
auth:
  token: your-strong-secret-token-change-me   # frpc ↔ frps login; must match on both hosts
  secret: your-stcp-secret-change-me            # STCP/SUDP secret; must match on both hosts

log:
  level: info                                   # trace | debug | info | warn | error

# Normal network preset (see Transport tuning for harsh-network values)
transport:
  tcp_mux: true
  pool_count: 1
  max_pool_count: 5
  use_encryption: false
  use_compression: false
  heartbeat_interval: -1
  heartbeat_timeout: -1
  dial_server_timeout: 10
  dial_server_keepalive: 7200
  tcp_mux_keepalive_interval: 30
  tcp_keepalive: 30

# --- Client side (ROLE=client runs main frpc here) ---
client:
  connect:
    # First TCP hop from this machine. With an SSH -L / dnstt tunnel listening on 6000,
    # frpc dials localhost:6000; traffic emerges at server listen (7000 below).
    # For a direct VPS dial, use the server IP and frps bind_port instead.
    server_addr: 127.0.0.1
    server_port: 6000

socks:
    enabled: true
    # SOCKS listener on the *server* so server-side apps can use the client's network
    remote_bind_addr: 127.0.0.1
    remote_bind_port: 1080                      # e.g. curl --socks5 127.0.0.1:1080 on server

services:
    # Client SSH → reachable on the server at 127.0.0.1:2222
    - name: ssh
      protocol: tcp
      local_target_addr: 127.0.0.1              # SSH daemon on this (client) machine
      local_target_port: 22
      remote_bind_addr: 127.0.0.1                 # Bind on the server host
      remote_bind_port: 2222

# Client web → public HTTP on the server at 0.0.0.0:8080
    - name: web
      protocol: tcp
      local_target_addr: 127.0.0.1
      local_target_port: 80
      remote_bind_addr: 0.0.0.0                   # All interfaces on server
      remote_bind_port: 8080

# Another host on the client LAN → public HTTP on the server at 0.0.0.0:8081
    - name: lan-web
      protocol: tcp
      local_target_addr: 192.168.10.10            # Must be routable from this client
      local_target_port: 80
      remote_bind_addr: 0.0.0.0
      remote_bind_port: 8081

# --- Server side (ROLE=server runs frps + server frpc here) ---
server:
  listen:
    # Where frps accepts the control connection (tunnel exit or direct bind)
    bind_addr: 127.0.0.1                          # 0.0.0.0 to listen on all interfaces
    bind_port: 7000

socks:
    enabled: true
    # SOCKS listener on the *client* so client-side apps can use the server's network
    remote_bind_addr: 127.0.0.1
    remote_bind_port: 2080                      # e.g. curl --socks5 127.0.0.1:2080 on client

services:
    # Server SSH → reachable on the client at 127.0.0.1:2222
    - name: ssh
      protocol: tcp
      local_target_addr: 127.0.0.1              # SSH daemon on this (server) machine
      local_target_port: 22
      remote_bind_addr: 127.0.0.1                 # Bind on the client host
      remote_bind_port: 2222

# DNS via the server → UDP listener on the client at 127.0.0.1:5353
    - name: dns
      protocol: udp
      local_target_addr: 8.8.8.8                  # Upstream resolver on server egress
      local_target_port: 53
      remote_bind_addr: 127.0.0.1
      remote_bind_port: 5353
```

### What each entry does

| Entry | Runs on | You connect to | Traffic goes to |
|-------|---------|----------------|-----------------|
| `client.connect` | Client | (frpc dials out) | Outer tunnel → frps `listen` |
| `client.socks` | Client proxy → server visitor | Server `127.0.0.1:1080` | Out via **client** default route/LAN |
| `client.services.ssh` | Client | Server `127.0.0.1:2222` | Client `127.0.0.1:22` |
| `client.services.web` | Client | Server `:8080` (any interface) | Client `127.0.0.1:80` |
| `client.services.lan-web` | Client | Server `:8081` | Client LAN `192.168.10.10:80` |
| `server.listen` | Server | (frps accepts inbound) | frps control port |
| `server.socks` | Server proxy → client visitor | Client `127.0.0.1:2080` | Out via **server** default route |
| `server.services.ssh` | Server | Client `127.0.0.1:2222` | Server `127.0.0.1:22` |
| `server.services.dns` | Server | Client `127.0.0.1:5353` (UDP) | Server forwards to `8.8.8.8:53` |

**Naming:** `client.services[].name` and `server.services[].name` are independent labels for each proxy/visitor pair (e.g. both can be `ssh` — they refer to different directions). Each `name` must be unique within its own `services` list.

**`local_target_*`** — address/port as seen from the machine that **hosts the service** (where the daemon listens).

**`remote_bind_*`** — address/port where the **other** host opens a listener to reach that service through frp.

## License

Licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE).

frp-ezpz

frp-ezpz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

frp-ezpz

frp-ezpz Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README