tcp-bridge

A simple TCP forwarding utility and bridge, written in Go.

tcp-bridge supports local TCP port forwarding, as well as bridged TCP port forwarding (using a multiplexed control connection) to forward traffic through environments where one side cannot accept direct inbound connections.

Features

• Forward Mode: Standard local TCP forwarding.
• Server/Client Modes: Bridged TCP forwarding. A client initiates a control connection to the server, and the server multiplexes incoming TCP connections to the client over this single control channel.
• Port Mapping: Supports both identical port forwarding (e.g., 8080 to 8080) and custom port mapping (e.g., 8080->80).

---

Usage

Usage:
  tcp-bridge <mode> [arguments]

Modes:
  forward   Forward all TCP connections to TARGET_HOST from a list of PORTS.
            Usage: tcp-bridge forward LISTEN_HOST TARGET_HOST PORTS...
            Arguments:
              LISTEN_HOST  Host onto which to listen for TCP connections (e.g. "0.0.0.0")
              TARGET_HOST  Destination host to forward connections to (e.g. "example.com")
              PORTS        Space-delimited list of ports to be forwarded (e.g. "8080")
                           or pairs of port mappings (e.g. "80->8080" or "8081->8082")

  client    Connect to a tcp-bridge server.
            Usage: tcp-bridge client ADDR
            Arguments:
              ADDR         Address of the tcp-bridge server to connect to (e.g. "127.0.0.1:9000")

  server    Listen for a tcp-bridge client and forward connections to it.
            Usage: tcp-bridge server CONTROL_ADDR LISTEN_HOST TARGET_HOST PORTS...
            Arguments:
              CONTROL_ADDR Address on which to listen for the tcp-bridge client (e.g. ":9000")
              LISTEN_HOST  Host on which to listen for local TCP connections (e.g. "0.0.0.0")
              TARGET_HOST  Host to forward connections from the client to (e.g. "127.0.0.1")
              PORTS        Space-delimited list of ports to be forwarded (e.g. "8080")
                           or pairs of port mappings (e.g. "80->8080")

---

Examples

1. Local Forwarding (forward mode)

To forward local ports on all interfaces (0.0.0.0) to a remote target host:

• Forward local port 8080 to example.org:8080 and map local port 8081 to example.org:8082:

  tcp-bridge forward 0.0.0.0 example.org 8080 8081->8082

• Forward local ports 8080, 8081, and 8082 to host 192.168.1.150 on the same ports:

  tcp-bridge forward 0.0.0.0 192.168.1.150 8080 8081 8082

2. Bridged Forwarding (server and client modes)

Bridged forwarding is useful when the machine behind a firewall (client) needs to expose services to the outside world, or vice-versa, without opening direct firewall ports for the services.

1. Start the Server (e.g., on a public server): Listen on :9000 for the client. Listen on 0.0.0.0 for incoming public traffic on ports 8080 and 8081, which will be bridged to the client:

   tcp-bridge server :9000 0.0.0.0 127.0.0.1 8080 8081->8082

2. Start the Client (on the private machine): Establish the multiplexed bridge connection to the server. Incoming connections on the server's ports will be forwarded to the client, which will dial them to 127.0.0.1 (on ports 8080 and 8082 respectively):

   tcp-bridge client 127.0.0.1:9000

---

Installation

Prerequisites:

• Go compiler (version 1.26.4 or later recommended)

Run without installing

You can run tcp-bridge directly using go run:

go run github.com/paskozdilar/tcp-bridge@latest forward 0.0.0.0 192.168.1.150 8080 8081->8082

Install globally

To install the binary globally (this installs to $GOBIN or $GOPATH/bin, which should be in your PATH):

go install github.com/paskozdilar/tcp-bridge@latest

Compile from source

To clone and compile tcp-bridge from source:

git clone https://github.com/paskozdilar/tcp-bridge.git
cd tcp-bridge
go build