-----------
proxytunnel
-----------

Author:		Jos Visser <josv@osp.nl>, Mark Janssen <maniac@maniac.nl>
Date: 		Mon Dec 31 16:50:33 CET 2007
Version:	1.8.0

Hi all,

This is proxytunnel, a program that connects stdin and stdout
to an origin server somewhere in the Internet through an industry
standard HTTPS proxy. I originally wrote this program to be used
as an extension to SSH, to be able to SSH to my box at home. In 
this file, I will describe the use with SSH. If you want to use it
with some other application, feel free, and let me know!


Usage:

Proxytunnel is very easy to use, when running proxytunnel with the help
option it specifies it's command-line options.

$ ./proxytunnel --help
Proxytunnel 1.8.0 (rev 165)
Copyright 2001-2007 Proxytunnel Project
Jos Visser (Muppet) <josv@osp.nl>, Mark Janssen (Maniac) <maniac@maniac.nl>

Purpose:
  Build generic tunnels trough HTTPS proxy's, supports HTTP authorization

Usage: Proxytunnel [OPTIONS]...
   -h         --help              Print help and exit
   -V         --version           Print version and exit
   -i         --inetd             Run from inetd (default=off)
   -a INT     --standalone=INT    Run as standalone daemon on specified port
   -e         --encrypt           Encrypt proxy<->destination using SSL
   -E         --encrypt-proxy     Encrypt client<->proxy (proxy talks SSL)
   -x STRING  --proctitle=STRING  Set the process-title to STRING
   -p STRING  --proxy=STRING      Proxy host:port combination to connect to
   -d STRING  --dest=STRING       Destination host:port to built the tunnel to

Parameters for proxy-authentication (not needed for plain proxies):
   -u STRING  --user=STRING       Username to send to HTTPS proxy for auth
   -s STRING  --pass=STRING       Password to send to HTTPS proxy for auth
   -U STRING  --uservar=STRING    Env var with Username for HTTPS proxy auth
   -S STRING  --passvar=STRING    Env var with Password for HTTPS proxy auth
   -F STRING  --passfile=STRING   File with credentials for proxy auth
   -N         --ntlm              Use NTLM Based Authentication
   -t STRING  --domain=STRING     NTLM Domain (default: autodetect)
   -r STRING  --remproxy=STRING   Use a remote proxy to tunnel over (2 proxies)
   -H STRING  --header=STRING     Add STRING to HTTP headers sent to proxy

  If you don't provide -s or -S you will be prompted for a password.

Miscellaneous options:
   -v         --verbose           Turn on verbosity (default=off)
   -q         --quiet             Suppress messages  (default=off)

Examples:
Proxytunnel [ -h | -V ]
Proxytunnel -i [ -u user ] -p proxy:port -d host:port [ -v | -q ]
Proxytunnel -i [ -U envvar ] -p proxy:port -d host:port [ -v | -q ]
Proxytunnel -a port -p proxy:port -d host:port [ -v | -q ]

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

Host foobar
	ProtocolKeepAlives 30
	ProxyCommand /path/to/proxytunnel -p proxy:8080 -u user
-d mybox.athome.nl:443

With:

- foobar		The symbolic name of the host you want to connect to
- proxy         	The host name of the proxy you want to connect through
- 8080			The port number where the proxy software listens to
- user			Your proxy userid
- mybox.athome.nl	The hostname of the box you want to connect to (ultimately)
- 443			The port number of the SSH daemon on mybox.athome.nl

If your proxy doesn't require the username and password for using it,
you can skip these options. If you don't provide the password on the
command-line (which is recommended) you will be prompted for it by
proxytunnel. If you are on a trusted system you can also put the
password in an environment variable, and tell proxytunnel where to
find it with '-S'.

If you want to run proxytunnel from inetd add the '--inetd' option.

Most HTTPS proxies do not allow access to ports other than 443 (HTTPS)
and 563 (SNEWS), so some hacking is necessary to start the SSH daemon on
the required port. (On the server side add an extra Port statement in
the sshd_config file, or use a redirect rule in your firewall.)

When your proxy uses NTLM authentication (like Microsoft IIS proxy)
you need to specify -N to enable NTLM, and then specify your username
and password (and optionally domain, if autodetection fails).
The NT domain can be specified on the commandline if the
auto-detection doesn't work for you (which is usually doesn't)

If you want to have the first proxy connect to another http proxy (like
one you can control, specify -r proxy2:port. The first proxy will then
connect to this remote proxy, which will be asked to connect to the 
requested destination. Note that authentication doesn't (yet) work on
this remote proxy. For more information regarding this feature, check
out http://dag.wieers.com/howto/ssh-http-tunneling/

If your proxy is more advanced, and does protocol inspection it will
detect that your connection is not a real HTTPS/SSL connection. You
can enable SSL encryption (using -e), which will work around this
problem, however, you need to setup stunnel4 on the other side, or
connect to a process that understands SSL itself.

When all this is in place, execute an "ssh foobar" and you're in business!

Share and Enjoy!

Jos Visser <josv@osp.nl>
Mark Janssen <maniac@maniac.nl>