# I'm just not gonna write troff :-)

=head1 NAME

 sslh - ssl/ssh multiplexer

=head1 SYNOPSIS

sslh [B<-F> I<config file>] [ B<-t> I<num> ] [B<-p> I<listening address> [B<-p> I<listening address> ...] [B<--ssl> I<target address for SSL>] [B<--ssh> I<target address for SSH>] [B<--openvpn> I<target address for OpenVPN>] [B<--http> I<target address for HTTP>] [B<-u> I<username>] [B<-P> I<pidfile>] [-v] [-i] [-V] [-f] [-n]

=head1 DESCRIPTION

B<sslh> accepts connections in HTTP, HTTPS, SSH, OpenVPN,
tinc, XMPP, or any other protocol that can be tested using a
regular expression, on the same port. This makes it possible
to connect to any of these servers on port 443 (e.g. from
inside a corporate firewall, which almost never block port
443) while still serving HTTPS on that port. 


The idea is to have B<sslh> listen to the external 443 port,
accept the incoming connections, work out what type of
connection it is, and then fordward to the appropriate
server.

=head2 Protocol detection

The protocol detection is made based on the first bytes sent
by the client: SSH connections start by identifying each
other's versions using clear text "SSH-2.0" strings (or
equivalent version strings). This is defined in RFC4253,
4.2. Meanwhile, OpenVPN clients start with 0x00 0x0D 0x38,
tinc clients start with "0 ", and XMPP client start with a
packet containing "jabber".

Additionally, two kind of SSH clients exist: the client
waits for the server to send its version string ("Shy"
client, which is the case of OpenSSH and Putty), or the
client sends its version first ("Bold" client, which is the
case of Bitvise Tunnelier and ConnectBot). 

If the client stays quiet after the timeout period, B<sslh>
will connect to the first protocol defined (in the
configuration file, or on the command line), so SSH should
be defined first in B<sslh> configuration to accomodate for
shy SSH clients.

=head2 Libwrap support

One drawback of B<sslh> is that the B<ssh> and B<httpd>
servers do not see the original IP address of the client
anymore, as the connection is forwarded through B<sslh>.
B<sslh> provides enough logging to circumvent that problem.
However it is common to limit access to B<ssh> using
B<libwrap> or B<tcpd>. For this reason, B<sslh> can be
compiled to check SSH accesses against SSH access lists as
defined in F</etc/hosts.allow> and F</etc/hosts.deny>.

=head2 Configuration file

A configuration file can be supplied to B<sslh>. Command
line arguments override file settings. B<sslh> uses
B<libconfig> to parse the configuration file, so the general
file format is indicated in
L<http://www.hyperrealm.com/libconfig/libconfig_manual.html>.
Please refer to the example configuration file provided with
B<sslh> for the specific format (Options have the same names
as on the command line, except for the list of listen ports
and the list of protocols).

The configuration file makes it possible to specify
protocols using regular expressions: a list of regular
expressions is given as the I<probe> parameter, and if the
first packet received from the client matches any of these
expressions, B<sslh> connects to that protocol.

Alternatively, the I<probe> parameter can be set to
"builtin", to use the compiled probes which are much faster
than regular expressions.


=head1 OPTIONS

=over 4

=item B<-t> I<num>, B<--timeout> I<num>

Timeout before forwarding the connection to the first
configured protocol (which should usually be SSH). Default
is 2s.

=item B<-p> I<listening address>, B<--listen> I<listening address>

Interface and port on which to listen, e.g. I<foobar:443>,
where I<foobar> is the name of an interface (typically the
IP address on which the Internet connection ends up).

This can be specified several times to bind B<sslh> to
several addresses.

=item B<--ssl> I<target address>

Interface and port on which to forward SSL connection,
typically I<localhost:443>.

Note that you can set B<sslh> to listen on I<ext_ip:443> and
B<httpd> to listen on I<localhost:443>: this allows clients
inside your network to just connect directly to B<httpd>.

=item B<--ssh> I<target address>

Interface and port on which to forward SSH connections,
typically I<localhost:22>.

=item B<--openvpn> I<target address>

Interface and port on which to forward OpenVPN connections,
typically I<localhost:1194>.

=item B<--xmpp> I<target address>

Interface and port on which to forward XMPP connections,
typically I<localhost:5222>.

=item B<--tinc> I<target address>

Interface and port on which to forward tinc connections,
typically I<localhost:655>.

This is experimental. If you use this feature, please report
the results (even if it works!)

=item B<-v>, B<--verbose>

Increase verboseness.

=item B<-n>, B<--numeric>

Do not attempt to resolve hostnames: logs will contain IP
addresses. This is mostly useful if the system's DNS is slow
and running the I<sslh-select> variant, as DNS requests will
hang all connections.

=item B<-V>

Prints B<sslh> version.

=item B<-u> I<username>, B<--user> I<username>

Requires to run under the specified username. 

=item B<-P> I<pidfile>, B<--pidfile> I<pidfile>

Specifies a file in which to write the PID of the main
server.

=item B<-i>, B<--inetd>

Runs as an I<inetd> server. Options B<-P> (PID file), B<-p>
(listen address), B<-u> (user) are ignored.

=item B<-f>, B<--foreground>

Runs in foreground. The server will not fork and will remain connected
to the terminal. Messages normally sent to B<syslog> will also be sent
to I<stderr>.

=item B<--background>

Runs in background. This overrides B<foreground> if set in
the configuration file (or on the command line, but there is
no point setting both on the command line unless you have a
personality disorder).

=back

=head1 FILES

=over 4

=item F</etc/init.d/sslh>

Start-up script. The standard actions B<start>, B<stop> and
B<restart> are supported.

=item F</etc/default/sslh>

Server configuration. These are environment variables
loaded by the start-up script and passed to B<sslh> as
command-line arguments. Refer to the OPTIONS section for a
detailed explanation of the variables used by B<sslh>.

=back

=head1 SEE ALSO

Last version available from
L<http://www.rutschle.net/tech/sslh>, and can be tracked
from L<http://freecode.com/projects/sslh>.

=head1 AUTHOR

Written by Yves Rutschle