PROXYTUNNEL(1)

📦
version 1.13.0 · 5 versions
, in arch rolling, nixpkgs unstable

💅 PROXYTUNNEL — the proxytunnel(1) glow-up 🎀

okay bestie, so picture this: you're stuck behind a corporate HTTPS proxy and it's giving hostile, and you just want to get a connection out. that's literally what proxytunnel is for. it's a program that tunnels any connection through a standard HTTPS proxy, circumventing standard HTTP filtering mechanisms. it's mostly used as a backend for OpenSSH's ProxyCommand, and as a proxy backend for Putty. it can also be used for other proxy-traversing purposes like proxy bouncing. no cap, it's iconic. 👑

✨ SYNOPSIS ✨

proxytunnel [OPTION...]

that's it. that's the whole vibe. options go in, tunnel comes out. 🦋

📖 DESCRIPTION 📖

so like — proxytunnel is a program that tunnels any connection through a standard HTTPS proxy, circumventing standard HTTP filtering mechanisms. it's mostly used as a backend for OpenSSH's ProxyCommand, and as a proxy backend for Putty. it can also be used for other proxy-traversing purposes like proxy bouncing. yes, it said proxy bouncing twice-ish, because that's a whole thing you can do. periodt. 💅

🌸 OPTIONS 🌸

  • -i, --inetd — run from inetd (default: off). classic old-school energy, we respect it.
  • -a, --standalone=[address:]port — run as standalone daemon on specified address and port. the address may be a IPv4 address, a bracket-enclosed IPv6 address or a bracket-enclosed combination of IPv6 address, '%' and interface name. that last format is only required with link-local IPv6 addresses. the daemon listens on any address if address is not given.

Examples, so you don't have to guess 🫶:

22, 123.45.67.89:22, [2001:db8::123:4567:89ab:cdef]:22,
[2001:db8::123:4567:89ab:cdef%eth0]:22
  • -p, --proxy=host:port — use host and port as the local (primary) proxy to connect to. if not specified the HTTP_PROXY environment variable, if set, will be used instead. bestie this option or the environment variable are mandatory — you literally can't skip both. 😭
  • -r, --remproxy=host:port — use host and port as the remote (secondary) proxy to connect to. the double-proxy era has arrived. 🔥
  • -d, --dest=host:port — use host and port as the destination for the tunnel. this is a mandatory option. like, no destination, no tunnel, no nothing. 🙈
  • -e, --encrypt — SSL encrypt data between local proxy and destination. 🔒
  • -E, --encrypt-proxy — SSL encrypt data between client and local proxy. 🔒
  • -X, --encrypt-remproxy — SSL encrypt data between local and remote (secondary) proxy. 🔒

🎀 ADDITIONAL OPTIONS 🎀

the extra-sparkle section, honestly:

  • -z, --no-check-certificate — do not verify server SSL certificate when establishing an SSL connection. by default, the server SSL certificate is verified and the target host name is checked against the server certificate's subject alternative names if any are present, or common name if there are no subject alternative names. so like, flipping this off is a choice. 💀
  • -C, --cacert=filename/directory — specify a CA certificate file (or directory containing CA certificate(s)) to trust when verifying a server SSL certificate. if a directory is provided, it must be prepared with OpenSSL's c_rehash tool (default, unless changed at compile time using DEFAULT_CA_FILE or DEFAULT_CA_DIR options: /etc/ssl/certs). trust issues? not on our watch. 🫶
  • -4, --ipv4 — enforce the use of IPv4 when connecting to the local proxy. old reliable. ⭐
  • -6, --ipv6 — enforce the use of IPv6 when connecting to the local proxy. futuristic slay. 🌈
  • -F, --passfile=filename — use filename for reading username and password for HTTPS proxy authentication. the file uses the same format as .wgetrc and can be shared with wget. use this option, or environment variables, to hide the password from other users. lowkey the responsible thing to do. 🔐
  • -P, --proxyauth=username:password — use username and password as credentials to authenticate against a local HTTPS proxy. the username and password can also be specified in the PROXYUSER and PROXYPASS environment variables to hide them from other users. if the password is omitted and no PROXYPASS environment variable is set, proxytunnel will prompt for a password. so you don't have to type it into your shell history, bestie, please don't. 😭
  • -R, --remproxyauth=username:password — use username and password as credentials to authenticate against a remote (secondary) HTTPS proxy. the username and password can also be specified in the REMPROXYUSER and REMPROXYPASS environment variables to hide them from other users. if the password is omitted and no REMPROXYPASS environment variable is set, proxytunnel will prompt for a password.
  • -c, --cert=filename — provide the name of the file containing the SSL client certificate to authenticate by client certificate against local proxy, remote proxy or destination. the file must be in PEM format. on top of this it may contain one or more intermediary certificates missing at the servers's end, effectively forming a certificate chain. requires specification of -k, --key in addition. ignored if neither -e, --encrypt nor -E, --encrypt-proxy nor -X, --encrypt-remproxy is given. so like, don't bring a cert to a no-encryption party. 💅
  • -k, --key=filename — provide the name of the file containing the SSL client key to authenticate by client certificate against local proxy, remote proxy or destination. the file must be in PEM format. requires specification of -c, --cert in addition. ignored if neither -e, --encrypt nor -E, --encrypt-proxy nor -X, --encrypt-remproxy is given. they're a matched set, your honor. 👑
  • -N, --ntlm — use NTLM based authentication. corporate-core. 🏢
  • -t, --domain=STRING — specify NTLM domain (default: autodetect). let it figure itself out, or tell it. your call.
  • -H, --header=STRING — add additional HTTP headers to send to proxy. custom flair for your packets. ✨
  • -o, --host=host[:port] — send a custom Host header. with SSL connections host is also sent as SNI. multitasking icon.
  • -x, --proctitle=STRING — use a different process title. incognito mode but make it system administration. 🕵️
  • -I, --no-sni — disable SNI. simply off. 🙅

🧚 MISCELLANEOUS OPTIONS 🧚

the little odds and ends:

  • -v, --verbose — turn on verbosity. she's chatty now. 💬
  • -q, --quiet — suppress messages. she's mysterious now. 🤫
  • -h, --help — print help and exit. 🫶
  • -V, --version — print version and exit. 📜

💖 USAGE 💖

depending on your situation you might want to do any of the following things (and honestly, iconic choices all around):

  • connect through a local proxy to your home system on port 22:
$ proxytunnel -v -p proxy.company.com:8080 -d system.home.nl:22
  • connect through a local proxy (with authentication) to your home system:
$ proxytunnel -v -p proxy.company.com:8080 -P username:password -d system.home.nl:22
  • connect through a local proxy (with authentication) hiding your password — yes bestie, this one, do this one:
$ export PROXYPASS=password
$ proxytunnel -v -p proxy.company.com:8080 -P username -d system.home.nl:22
  • connect through a local proxy to a remote proxy and bounce to any system:
$ proxytunnel -v -p proxy.company.com:8080 -r proxy.athome.nl:443 -d system.friend.nl:22
  • connect using SSL through a local proxy to your home system:
$ proxytunnel -v -E -p proxy.company.com:8080 -d system.home.nl:22

🔑 OPENSSH CONFIGURATION 🔑

to use this program with OpenSSH to connect to a host somewhere, create a ~/.ssh/config file with the following content:

Host system.athome.nl
    ProxyCommand proxytunnel -p proxy.company.com:8080 -d %h:%p
    ServerAliveInterval 30
Note 🫶 the ServerAliveInterval directive makes sure that idle connections are not being dropped by intermediate firewalls that remove active sessions aggressively. if you see your connection dropping out, try to lower the value even more. yes, even more. she said what she said. 😤

to use the dynamic (SOCKS) portforwarding capability of the SSH client, you can specify the DynamicForward directive in your ssh_config file like:

Host system.athome.nl
    DynamicForward 1080
    ProxyCommand proxytunnel -p proxy.company.com:8080 -d %h:%p
    ServerAliveInterval 30

⚠️ NOTES ⚠️

Important 🚨 most HTTPS proxies do not allow access to ports other than HTTPS (tcp/443) and SNEWS (tcp/563). in this case you need to make sure the SSH daemon or remote proxy on the destination system is listening on either tcp/443 or tcp/563 to get through. like, the proxy said "443 or 563 or nothing," and she meant it. 💀

🌿 ENVIRONMENT 🌿

proxytunnel can be influenced by setting one of the following environment variables:

  • HTTP_PROXY — if this environment variable is set, proxytunnel will use it as the local proxy if -p or --proxy is not provided.
  • PROXYUSER — if this environment variable is set, proxytunnel will use it as the username for proxy authentication, unless specified using the -P or --proxyauth option.
  • PROXYPASS — if this environment variable is set, proxytunnel will use it as the password for proxy authentication, unless specified using the -P or --proxyauth option.
  • REMPROXYUSER — if this environment variable is set, proxytunnel will use it as the username for remote (secondary) proxy authentication, unless specified using the -R or --remproxyauth option.
  • REMPROXYPASS — if this environment variable is set, proxytunnel will use it as the password for remote (secondary) proxy authentication, unless specified using the -R or --remproxyauth option.

👀 SEE ALSO 👀

ssh(1), ssh_config(8) — go read those too, iykyk. 📚

🐛 BUGS 🐛

this software is bug-free, at least we'd like to think so. 💅 if you do not agree with us, please provide the proof with your friendly report at https://github.com/proxytunnel/proxytunnel/issues :) — friendly being the operative word, be nice to the maintainers, they're doing their best. 🫶

👑 AUTHOR 👑

this manpage was initially written by Loïc Le Guyader <loic.leguyader@laposte.net[1]> for the Debian GNU/Linux system, revamped in asciidoc by Dag Wieërs <dag@wieers.com[2]> and is now maintained by the Proxytunnel developers. legends, all of them. 🌟

homepages at https://proxytunnel.sourceforge.io and https://github.com/proxytunnel/proxytunnel 🦋

📎 NOTES 📎

  1. loic.leguyader@laposte.net mailto:loic.leguyader@laposte.net
  2. dag@wieers.com mailto:dag@wieers.com

and that's the whole page, bestie!! 🎀 this was version 1.13.0, dated 2026-05-31 — go forth and tunnel responsibly, mwah 💜✨

📦 where this page comes from