mirror of https://github.com/moparisthebest/sslh
197 lines
6.0 KiB
Plaintext
197 lines
6.0 KiB
Plaintext
# 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>.
|
|
|
|
=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
|