'\" t
.\"     Title: proxytunnel
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-02-06
.\"    Manual: \ \&
.\"    Source: \ \& 1.12.1
.\"  Language: English
.\"
.TH "PROXYTUNNEL" "1" "2024\-02\-06" "\ \& 1\&.12\&.1" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
proxytunnel \- program to tunnel a connection through a standard HTTPS proxy
.SH "SYNOPSIS"
.sp
\fBproxytunnel\fR [\fIOPTION\&...\fR] [\fIhost\fR:\fIport\fR]
.SH "DESCRIPTION"
.sp
\fBproxytunnel\fR is a program to tunnel any connection through a standard HTTPS proxy, circumventing standard HTTP filtering mechanisms\&. It\(cqs mostly used as a backend for OpenSSH\(cqs ProxyCommand, and as a proxy backend for Putty\&. It can also be used for other proxy\-traversing purposes like proxy bouncing\&.
.SH "OPTIONS"
.PP
\fB\-i\fR, \fB\-\-inetd\fR
.RS 4
Run from inetd (default: off)\&.
.RE
.PP
\fB\-a\fR, \fB\-\-standalone\fR=[\fIaddress\fR:]\fIport\fR
.RS 4
Run as standalone daemon on specified
\fIaddress\fR
and
\fIport\fR\&.
\fIaddress\fR
may be a IPv4 address, a bracket\-enclosed IPv6 address or a bracket\-enclosed combination of IPv6 address, \*(Aq%\*(Aq and interface name\&. The latter format is only required with link\-local IPv6 addresses\&. The daemon listens on any address if
\fIaddress\fR
is not given\&.
.PP
\fBExamples\fR
.RS 4
22, 123\&.45\&.67\&.89:22, [2001:db8::123:4567:89ab:cdef]:22, [2001:db8::123:4567:89ab:cdef%eth0]:22
.RE
.RE
.PP
\fB\-p\fR, \fB\-\-proxy\fR=\fIhost\fR:\fIport\fR
.RS 4
Use
\fIhost\fR
and
\fIport\fR
as the local proxy to connect to, if not specified the
\fBHTTP_PROXY\fR
environment variable, if set, will be used instead\&.
.RE
.PP
\fB\-r\fR, \fB\-\-remproxy\fR=\fIhost\fR:\fIport\fR
.RS 4
Use
\fIhost\fR
and
\fIport\fR
as the remote (secondary) proxy to connect to\&.
.RE
.PP
\fB\-d\fR, \fB\-\-dest\fR=\fIhost\fR:\fIport\fR
.RS 4
Use
\fIhost\fR
and
\fIport\fR
as the destination for the tunnel, you can also specify them as the argument to the proxytunnel command\&.
.RE
.PP
\fB\-e\fR, \fB\-\-encrypt\fR
.RS 4
SSL encrypt data between local proxy and destination\&.
.RE
.PP
\fB\-E\fR, \fB\-\-encrypt\-proxy\fR
.RS 4
SSL encrypt data between client and local proxy\&.
.RE
.PP
\fB\-X\fR, \fB\-\-encrypt\-remproxy\fR
.RS 4
SSL encrypt data between local and remote (secondary) proxy\&.
.RE
.SH "ADDITIONAL OPTIONS"
.PP
\fB\-W\fR, \fB\-\-wa\-bug\-29744\fR
.RS 4
Workaround ASF Bugzilla 29744: If SSL is in use (by
\fB\-e\fR,
\fB\-E\fR,
\fB\-X\fR
options), stop using it immediately after the CONNECT exchange to workaround apache server bugs (This might not work on all setups)\&.
.RE
.PP
\fB\-B\fR, \fB\-\-buggy\-encrypt\-proxy\fR
.RS 4
Equivalent to
\fB\-E \-W\fR
(Provided for backwards compatibility)\&.
.RE
.PP
\fB\-z\fR, \fB\-\-no\-check\-certificate\fR
.RS 4
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\(cqs subject alternative names if any are present, or common name if there are no subject alternative names\&.
.RE
.PP
\fB\-C\fR, \fB\-\-cacert\fR=\fIfilename/directory\fR
.RS 4
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\(cqs c_rehash tool (default, unless changed at compile time using DEFAULT_CA_FILE or DEFAULT_CA_DIR options: /etc/ssl/certs)\&.
.RE
.PP
\fB\-4\fR, \fB\-\-ipv4\fR
.RS 4
Enforce the use of IPv4 when connecting to the local proxy\&.
.RE
.PP
\fB\-6\fR, \fB\-\-ipv6\fR
.RS 4
Enforce the use of IPv6 when connecting to the local proxy\&.
.RE
.PP
\fB\-F\fR, \fB\-\-passfile\fR=\fIfilename\fR
.RS 4
Use
\fIfilename\fR
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\&.
.RE
.PP
\fB\-P\fR, \fB\-\-proxyauth\fR=\fIusername\fR:\fIpassword\fR
.RS 4
Use
\fIusername\fR
and
\fIpassword\fR
as credentials to authenticate against a local HTTPS proxy, the username and password can also be specified in the
\fBPROXYUSER\fR
and
\fBPROXYPASS\fR
environment variables to hide them from other users\&. If the
\fIpassword\fR
is omitted and no
\fBPROXYPASS\fR
environment variable is set, proxytunnel will prompt for a password\&.
.RE
.PP
\fB\-R\fR, \fB\-\-remproxyauth\fR=\fIusername\fR:\fIpassword\fR
.RS 4
Use
\fIusername\fR
and
\fIpassword\fR
as credentials to authenticate against a remote (secondary) HTTPS proxy, the username and password can also be specified in the
\fBREMPROXYUSER\fR
and
\fBREMPROXYPASS\fR
environment variables to hide them from other users\&. If the
\fIpassword\fR
is omitted and no
\fBREMPROXYPASS\fR
environment variable is set, proxytunnel will prompt for a password\&.
.RE
.PP
\fB\-c\fR, \fB\-\-cert\fR=\fIfilename\fR
.RS 4
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\(cqs end, effectively forming a certificate chain\&. Requires specification of
\fB\-k\fR,
\fB\-\-key\fR
in addition\&. Ignored if neither
\fB\-e\fR,
\fB\-\-encrypt\fR
nor
\fB\-E\fR,
\fB\-\-encrypt\-proxy\fR
nor
\fB\-X\fR,
\fB\-\-encrypt\-remproxy\fR
is given\&.
.RE
.PP
\fB\-k\fR, \fB\-\-key\fR=\fIfilename\fR
.RS 4
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
\fB\-c\fR,
\fB\-\-cert\fR
in addition\&. Ignored if neither
\fB\-e\fR,
\fB\-\-encrypt\fR
nor
\fB\-E\fR,
\fB\-\-encrypt\-proxy\fR
nor
\fB\-X\fR,
\fB\-\-encrypt\-remproxy\fR
is given\&.
.RE
.PP
\fB\-N\fR, \fB\-\-ntlm\fR
.RS 4
Use NTLM based authentication\&.
.RE
.PP
\fB\-t\fR, \fB\-\-domain\fR=\fISTRING\fR
.RS 4
Specify NTLM domain (default: autodetect)\&.
.RE
.PP
\fB\-H\fR, \fB\-\-header\fR=\fISTRING\fR
.RS 4
Add additional HTTP headers to send to proxy\&.
.RE
.PP
\fB\-o\fR, \fB\-\-host\fR=\fIhost\fR[:\fIport\fR]
.RS 4
Send a custom Host header\&. With SSL connections
\fIhost\fR
is also sent as SNI\&.
.RE
.PP
\fB\-x\fR, \fB\-\-proctitle\fR=\fISTRING\fR
.RS 4
Use a different process title\&.
.RE
.SH "MISCELLANEOUS OPTIONS"
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Turn on verbosity\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Suppress messages\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print help and exit\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
Print version and exit\&.
.RE
.SH "ARGUMENTS"
.sp
\fIhost\fR:\fIport\fR is the destination hostname and port number combination\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
Specifying the destination as arguments is exactly the same as specifying them using the \fB\-d\fR or \fB\-\-dest\fR option\&.
.sp .5v
.RE
.SH "USAGE"
.sp
Depending on your situation you might want to do any of the following things:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBConnect through a local proxy to your home system on port 22\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ proxytunnel \-v \-p proxy\&.company\&.com:8080 \-d system\&.home\&.nl:22
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBConnect through a local proxy (with authentication) to your home system\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ proxytunnel \-v \-p proxy\&.company\&.com:8080 \-P username:password \-d system\&.home\&.nl:22
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBConnect through a local proxy (with authentication) hiding your password\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ export PROXYPASS=password
$ proxytunnel \-v \-p proxy\&.company\&.com:8080 \-P username \-d system\&.home\&.nl:22
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBConnect through a local proxy to a remote proxy and bounce to any system\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ proxytunnel \-v \-p proxy\&.company\&.com:8080 \-r proxy\&.athome\&.nl:443 \-d system\&.friend\&.nl:22
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBConnect using SSL through a local proxy to your home system\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ proxytunnel \-v \-E \-p proxy\&.company\&.com:8080 \-d system\&.home\&.nl:22
.fi
.if n \{\
.RE
.\}
.RE
.SH "OPENSSH CONFIGURATION"
.sp
To use this program with OpenSSH to connect to a host somewhere, create a \fI~/\&.ssh/config\fR file with the following content:
.sp
.if n \{\
.RS 4
.\}
.nf
Host system\&.athome\&.nl
    ProxyCommand proxytunnel \-p proxy\&.company\&.com:8080 \-d %h:%p
    ServerAliveInterval 30
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
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\&.
.sp .5v
.RE
.sp
To use the dynamic (SOCKS) portforwarding capability of the SSH client, you can specify the DynamicForward directive in your ssh_config file like:
.sp
.if n \{\
.RS 4
.\}
.nf
Host system\&.athome\&.nl
    DynamicForward 1080
    ProxyCommand proxytunnel \-p proxy\&.company\&.com:8080 \-d %h:%p
    ServerAliveInterval 30
.fi
.if n \{\
.RE
.\}
.SH "NOTES"
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.sp
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\&.
.sp .5v
.RE
.SH "ENVIRONMENT"
.sp
Proxytunnel can be influenced by setting one of the following environment variables:
.PP
\fBHTTP_PROXY\fR
.RS 4
If this environment variable is set, proxytunnel will use it as the
\fIlocal proxy\fR
if
\fB\-p\fR
or
\fB\-\-proxy\fR
is not provided\&.
.RE
.PP
\fBPROXYUSER\fR
.RS 4
If this environment variable is set, proxytunnel will use it as the
\fIusername\fR
for proxy authentication, unless specified using the
\fB\-P\fR
or
\fB\-\-proxyauth\fR
option\&.
.RE
.PP
\fBPROXYPASS\fR
.RS 4
If this environment variable is set, proxytunnel will use it as the
\fIpassword\fR
for proxy authentication, unless specified using the
\fB\-P\fR
or
\fB\-\-proxyauth\fR
option\&.
.RE
.PP
\fBREMPROXYUSER\fR
.RS 4
If this environment variable is set, proxytunnel will use it as the
\fIusername\fR
for remote (secondary) proxy authentication, unless specified using the
\fB\-R\fR
or
\fB\-\-remproxyauth\fR
option\&.
.RE
.PP
\fBREMPROXYPASS\fR
.RS 4
If this environment variable is set, proxytunnel will use it as the
\fIpassword\fR
for remote (secondary) proxy authentication, unless specified using the
\fB\-R\fR
or
\fB\-\-remproxyauth\fR
option\&.
.RE
.SH "SEE ALSO"
.sp
.if n \{\
.RS 4
.\}
.nf
ssh(1), ssh_config(8)
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.sp
This software is bug\-free, at least we\(cqd like to think so\&. If you do not agree with us, please provide the proof with your friendly report at \m[blue]\fBhttps://github\&.com/proxytunnel/proxytunnel/issues\fR\m[] :)
.SH "AUTHOR"
.sp
This manpage was initially written by Lo\(:ic Le Guyader <\m[blue]\fBloic\&.leguyader@laposte\&.net\fR\m[]\&\s-2\u[1]\d\s+2> for the Debian GNU/Linux system, revamped in asciidoc by Dag Wie\(:ers <\m[blue]\fBdag@wieers\&.com\fR\m[]\&\s-2\u[2]\d\s+2> and is now maintained by the Proxytunnel developers\&.
.sp
Homepages at \m[blue]\fBhttps://proxytunnel\&.sourceforge\&.io\fR\m[] and \m[blue]\fBhttps://github\&.com/proxytunnel/proxytunnel\fR\m[]
.SH "NOTES"
.IP " 1." 4
loic.leguyader@laposte.net
.RS 4
\%mailto:loic.leguyader@laposte.net
.RE
.IP " 2." 4
dag@wieers.com
.RS 4
\%mailto:dag@wieers.com
.RE