sslh/sslh.pod

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

=head1 NAME

 sslh - ssl/ssh multiplexer

=head1 SYNOPSIS

sslh [ B<-t> I<num> ] [B<-p> I<listening address>] [B<-l> I<target address for SSL>] [B<-s> I<target address for SSH>] [B<-o> I<target address for OpenVPN>] [B<-u> I<username>] [B<-P> I<pidfile>] [-v] [-i] [-V] [-f]

=head1 DESCRIPTION

B<sslh> accepts HTTPS, SSH and OpenVPN connections on the
same port. This makes it possible to connect to an SSH
server or an OpenVPN 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.

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). 

B<sslh> waits for some time for the incoming connection to
send data. If it stays quiet after the timeout period, it is
assumed to be a shy SSH client, and is connected to the SSH
server. Otherwise, B<sslh> reads the first packet the client
provides, and connects it to the SSH server if it starts
with "SSH-", or connects it to the SSL server otherwise.

=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>.

=head1 OPTIONS

=over 4

=item B<-t> I<num>

Timeout before a connection is considered to be SSH. Default
is 2s.

=item B<-p> 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).

Defaults to I<0.0.0.0:443> (listen to port 443 on all
available interfaces).

=item B<-l> I<target address for SSL>

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

Defaults to I<localhost:443> (this assumes you would
configure your B<httpd> process to listen to port 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<-s> I<target address for SSH>

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

=item B<-o> I<target address for OpenVPN>

Interface and port on which to forward OpenVPN connections.
This parameter is optional, and has no default. If not
specified, incoming OpenVPN connections will not be detected
as such and treated the same as SSL.

=item B<-v>

Increase verboseness.

=item B<-V>

Prints B<sslh> version.

=item B<-u> I<username>

Requires to run under the specified username. Defaults to
I<nobody> (which is not perfect -- ideally B<sslh> should
run under its own UID).

=item B<-P> I<pidfile>

Specifies the file in which to write the PID of the main
server. Defaults to I</var/run/sslh.pid>.

=item B<-i>

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

=item B<-f>

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>.

=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://freshmeat.net/projects/sslh/>.

=head1 AUTHOR

Written by Yves Rutschle