CONNECT-TUNNEL(1p)

📦
version 0.13 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ connect-tunnel — like, the manual page, but make it make sense ✨

okay bestie, so this is the manual page for connect-tunnel, a little Perl script from the User Contributed Perl Documentation section. it's a Perl thing, it's a tunnel thing, and honestly? it's giving main character energy. let's go 💖

🌸 NAME 🌸

connect-tunnel — create CONNECT tunnels through HTTP proxies. that's the whole vibe. tunnels. through proxies. slay.

🎀 SYNOPSIS 🎀

connect-tunnel [ -Lv ] [ -A user:pass ] [ -P proxy:port ]
               [ -C controlport ] [ -T port:host:hostport ]

💅 DESCRIPTION 💅

so basically, connect-tunnel sets up tunneled connections to outside hosts, and the way it does that is by redirecting connections to local ports towards those hosts/ports through an HTTP proxy. it's a middleman. a cute little middleman. 🧚

the trick it uses is the HTTP CONNECT method, which is how it asks the proxy to build a tunnel out to an outside server. but — and this is the important part, no cap — some proxies are set up to deny outside tunnels. that can be a denial for ports other than 443, or a denial for anything outside a specified set of outside hosts. so if it doesn't work, it might not be you, it might be the proxy being a hater. 💀

✨ OPTIONS ✨

the program follows the usual GNU command line syntax, with long options starting with two dashes. periodt.

  • -A, --proxy-authentication user:password — the proxy authentication info, aka your little login moment. 🫶 please note that every authentication scheme supported by LWP::UserAgent is supported here, because we use an LWP::UserAgent internally to talk to the proxy. iykyk.
  • -C, --control-port controlport — the port you can connect to in order to issue control commands to connect-tunnel. see "CONTROL CONNECTIONS" for more deets about which commands are available. yes, it's a remote control. iconic. 👑
  • -L, --local-only — creates the tunnels so they only listen on localhost. so only connections coming from the machine that's running connect-tunnel get accepted. lowkey the safest vibe. also, fun fact: this was the default behaviour back in connect-tunnel version 0.02. the way that changed… 😭
  • -P, --proxy proxy[:port] — the proxy is required to connect the tunnels, bestie, it's not optional. if you don't give a port, 8080 is used by default. see also "ENVIRONMENT VARIABLES" below. 🌈
  • -T, --tunnel port:host:hostport — this says: the given port on the local host gets forwarded to the given host and hostport on the remote side. how it works: it allocates a socket listening on port on the local side, and every time a connection shows up on that port, connect-tunnel forwards it to the proxy (with the credentials, if they're required), and the proxy forwards it onward to the final destination. teamwork, fr fr. 🤝
⚠️ heads up: this does not imply the use of any cryptographic system — no SSL, no nothing. this is a simple TCP redirection. whatever security exists, if any, is the security provided by the protocol you're using to connect to the destination through connect-tunnel. so like, don't assume it's encrypted just because it's a tunnel. 💀

on Unix systems, only root can forward privileged ports. 🫠

also — you can set up tunnels to multiple destinations by just using the --tunnel option several times. no need to run five of them.

  • -U, --user-agent string — specifies the User-Agent value to send in HTTP requests. the default is to send connect-tunnel/version. dress it up however you like. 🎀
  • -v, --verbose — verbose output. and yes, you can use this option several times for even more verbose output. stacking the vibes. 🔥

🌈 EXAMPLES 🌈

okay so say you wanna connect to a SSH server running on ssh.example.com, on port 443, through the proxy proxy.company.com running on port 8080. boom:

connect-tunnel -P proxy.company.com:8080 -T 22:ssh.example.com:443

and now point your favorite ssh client to the machine running connect-tunnel. that's it. that's the whole thing. ✨

you can also emulate a "standard" user-agent:

connect-tunnel -U "Mozilla/4.03 [en] (X11; I; Linux 2.1.89 i586)"
               -P proxy.company.com:8080 -T 22:ssh.example.com:443

and connect-tunnel can easily use your proxy credentials to connect outside, no drama:

connect-tunnel -U "Mozilla/4.03 [en] (X11; I; Linux 2.1.89 i586)"
               -P proxy.company.com:8080 -T 22:ssh.example.com:443
               -A book:s3kr3t

but if you do not want anybody else connecting to your tunnels and going through the proxy with your credentials, use the --local-only option. protect your login bestie!! 🔒

connect-tunnel -U "Mozilla/4.03 [en] (X11; I; Linux 2.1.89 i586)"
               -P proxy.company.com:8080 -T 22:ssh.example.com:443
               -A book:s3kr3t -L

and if you've got several destinations, there's genuinely no need to run several instances of connect-tunnel:

connect-tunnel -U "Mozilla/4.03 [en] (X11; I; Linux 2.1.89 i586)"
               -P proxy.company.com:8080 -A book:s3kr3t -L
               -T 22:ssh.example.com:443
               -T 222:ssh2.example.com:443

but naturally, you will need to correctly set up the ports in your clients. no skipping that part. 🙈

mmm, such a long command line would perfectly fit in an alias or a .BAT file. ;-) 💅

🦋 ENVIRONMENT VARIABLES 🦋

the environment variable HTTP_PROXY can be used to provide a proxy definition.

and that environment variable gets overriden by the --proxy option, if it's passed to connect-tunnel. so the flag wins. always. 👑

💜 AUTHOR 💜

Philippe "BooK" Bruhat, <book@cpan.org>.

and he says: he seems to have re-invented a well-known wheel with that script, but at least he hopes he added a few interesting options to it. honestly? he did. 🫶

📜 SCRIPT HISTORY 📜

the first version of the script was a quick hack that let him go through a corporate proxy. relatable.

version 0.02 and version 0.03 were released on CPAN in 2003.

version 0.04 sits half-finished in a CVS repository at home — he couldn't decypher the spaghetti of his data structures any more. :-( 💀 literally the most developer thing ever.

version 0.05 (and higher) are based on Net::Proxy, and included with the Net::Proxy distribution.

and even though it's not rocket science, connect-tunnel has been cited in at least one academic work:

  • HTTP Tunnels Through Proxies, Daniel Alman

available at SANS InfoSec Reading Room: Covert Channels <http://www.sans.org/rr/whitepapers/covert/>

direct link: <http://www.sans.org/rr/whitepapers/covert/1202.php>

Copyright 2003-2007, Philippe Bruhat. All rights reserved.

🌸 LICENSE 🌸

this module is free software; you can redistribute it or modify it under the same terms as Perl itself.

okay bestie that's the whole page, you're officially a tunnel girlie now 🎀 the manual page itself is from the perl v5.38.2 docs, dated 2024-05-15, and it lives in the CONNECT-TUNNEL(1p) section. go forth and tunnel. no cap. 💖✨🦋

📦 where this page comes from