tcp_tunnel 1.0.0
tcp_tunnel: ^1.0.0 copied to clipboard
A minimalistic TCP tunnel library, entirely written in Dart, and equipped with a user-friendly Command Line Interface (CLI) for seamless usage across diverse platforms.
tcp_tunnel #
A minimalistic TCP tunnel library, entirely written in Dart, and equipped with a user-friendly Command Line Interface (CLI) for seamless usage across diverse platforms.
Motivation #
The primary motivation behind this library is to assist in the development of servers, clients, and services within intricate network topologies.
During the development process, accessing remote devices or servers can often be challenging, especially in the initial stages and validation phase. This difficulty arises when nothing is exposed to a public network, and there is a need to integrate multiple networks, including cloud resources, local LAN, and debugging environments.
Usage #
There are three types of tunnels that can be utilized in combination:
-
Local Port Redirect:
Links
listenPort
tolocalTargetPort
for bidirectional data flow. -
Bridge Tunneling:
Connects
listenPort1
andlistenPort2
for data traffic exchange. -
Client Tunnel:
Links
remoteHost:remotePort
tolocalTargetPort
for bidirectional data transfer.
Local Port Redirect: #
To redirect a local port, like 3366 (listenPort
) to 3306 (targetPort
):
Future<void> redirectLocalPort(int listenPort, int targetPort, {String targetHost = 'localhost'}) async {
await TunnelLocalServer(listenPort, targetPort, targetHost: targetHost).start();
}
The TunnelLocalServer
will listen on listenPort
, and for each accepted Socket,
it will initiate a connection to the localTargetPort
and
enable bidirectional data traffic redirection between them.
Bridge Tunneling: #
To create a bridhe between 2 ports:
Future<void> bridgePorts(int listenPort1, int listenPort2) async {
await TunnelBridge(listenPort1, listenPort2).start();
}
The TunnelBridge
will concurrently listen on listenPort1
and listenPort2
.
For each accepted Socket
on listenPort1
, it will await for a corresponding
accepted Socket
on listenPort2
(and vice versa). Once both Socket
s are established,
it will enable bidirectional data traffic redirection between them.
Client Tunnel: #
To create a client tunnel:
Future<void> clientTunnel(String remoteHost, int remotePort, int localTargetPort) async {
var tunnel = Tunnel.connect(remoteHost, remotePort, localTargetPort);
tunnel.onClose = (t) {
// closed, try to reconnect...
};
}
The Tunnel
establishes a connection to remoteHost:remotePort
,
after which it connects to localTargetPort
and enables bidirectional
data traffic redirection between the two connections.
CLI Tool #
You can utilize the CLI tool tcp_tunnel
with ease on any platform supported by Dart.
To activate the CLI tool just run:
dart pub global activate tcp_tunnel
Then you can create a tunnel for each necessary scenario:
-
Local Port Redirect:
tcp_tunnel local %listenPort %targetPort %targetHost
%targetHost
is optional. Default:localhost
-
Bridge Tunneling:
tcp_tunnel bridge %listenPort1 %listenPort2
-
Client Tunnel:
tcp_tunnel client %remoteHost %remotePort %localTargetPort
Combined Usage #
To access the port 3306
(MySQL) inside a remote and private Server X (no public address):
-
- Establish a Server Bridge in a public Server Y (server-y.domain):
tcp_tunnel bridge 8035 8036
-
- Run the client tunnel at private Server X (the server with the private MySQL DB):
tcp_tunnel client server-y.domain 8036 3306
-
- Run mysql client pointing to the tunnel port:
mysql -u myuser -p -h server-y.domain -P 8035
With this setup you can use the remote port server-y.domain:8035
as the
private MySQL port 3306
.
-
- If you wish to expand the configuration, you can establish a local port for the redirection above.
Now, simply access the local porttcp_tunnel local 3306 8035 server-y.domain
3306
as you would with a standard MySQL database. This local port, in reality, connects to a remote private server.
Or just with default settings (same as above):mysql -u myuser -p -h localhost -P 3306
mysql -u myuser -p
Security #
Please be aware that the tunnel communication is NOT encrypted, and any connection made over a public network may expose its data to potential security risks.
Features and bugs #
Please file feature requests and bugs at the issue tracker.
Author #
Graciliano M. Passos: gmpassos@GitHub.
Sponsor #
Don't be shy, show some love, and become our GitHub Sponsor. Your support means the world to us, and it keeps the code caffeinated! ☕✨
Thanks a million! 🚀😄
License #
Dart free & open-source license.